Najlepsze praktyki dotyczące usługi Microsoft Foundry Agent Service.

Podczas kompilowania agentów w usłudze agenta usługi Microsoft Foundry narzędzia rozszerzają możliwości agenta — pobieranie informacji, wywoływanie interfejsów API i nawiązywanie połączenia z usługami zewnętrznymi. Ten artykuł pomaga efektywnie konfigurować narzędzia, kontrolować, kiedy agent je wywołuje, i zapewnić bezpieczeństwo danych.

Wskazówka

W instrukcjach agenta opisz, jakie narzędzie ma być używane i kiedy należy z niego korzystać. Na przykład:

When you need information from my indexed documents, use File Search. When you need to call an API, use the OpenAPI tool. When a tool call fails or returns no results, explain what happened and ask a follow-up question.

Wymagania wstępne

  • Dostęp do projektu Foundry w portalu Foundry z rolą Azure Deweloper AI lub równoważnymi uprawnieniami.
  • Model wdrożony w tym samym projekcie.
  • Wszystkie wymagane połączenia muszą być skonfigurowane dla narzędzi, których planujesz użyć (na przykład Wyszukiwanie AI platformy Azure, SharePoint lub ustalanie kontekstu w Bing).
  • Model i region projektu, które obsługują to narzędzie. Zobacz Obsługa narzędzi według regionów i modelu.

Konfigurowanie i weryfikowanie użycia narzędzia

Zwiększanie niezawodności wywoływania narzędzi

Narzędzia do projektowania dla agentów monitów opartych na głosach

Agenci głosowi sterowani promptami używają narzędzi podczas rozmowy głosowej na żywo, więc opóźnienia narzędzi i długość odpowiedzi wpływają na doświadczenie rozmówcy. Zachowaj zwięzłe opisy narzędzi, zwracaj tylko informacje, których agent potrzebuje, aby odpowiedzieć na bieżące żądanie, i przekazuj krótki głosowy komunikat o postępie, gdy wywołanie narzędzia trwa dłużej.

  • Użyj natywnych narzędzi funkcji, gdy połączony klient musi wykonać akcję.
  • Użyj narzędzi MCP lub Toolbox, gdy wywołanie narzędzia wykonuje usługa agenta lub integracja Voice Live.
  • Ustaw tool_choice celowo do otwierania lub innych zmian wrażliwych na czas. Użyj none, gdy agent powinien mówić bez wywoływania narzędzia, auto, gdy model podejmuje decyzję, lub required, gdy konieczne jest wywołanie narzędzia.
  • Przerwy w testowaniu i błędy narzędzi w sesji głosowej na żywo. Agent powinien pozostać funkcjonalny, gdy rozmówca mówi, podczas gdy narzędzie jest uruchomione, lub gdy narzędzie nie zwraca wyniku.

Aby uzyskać informacje na temat konfiguracji, zobacz Szybki start: tworzenie agenta monitu opartego na głosach.

Wywoływanie narzędzia kontroli za pomocą polecenia tool_choice

Użyj tool_choice, aby uzyskać najbardziej deterministyczną kontrolę nad wywoływaniem narzędzi.

  • auto: model decyduje, czy ma uruchamiać narzędzia.
  • required: Model musi wywoływać co najmniej jedno narzędzie.
  • none: Model nie wywołuje narzędzi.

Szczegółowe informacje można znaleźć w tool_choicedokumentacji referencyjnej interfejsu API REST projektu Foundry.

Pisanie skutecznych instrukcji dotyczących narzędzi

  • Utrzymuj instrukcje szczegółowe i spójne z konfiguracją narzędzia.
  • Poinformuj model, do czego służy każde narzędzie.
  • Jeśli masz wiele narzędzi, które nakładają się na siebie, dodaj regułę podejmowania decyzji (na przykład "Użyj wyszukiwania plików przed wyszukiwaniem zawartości wewnętrznej w sieci Web").

Bezpieczne użycie narzędzia

Narzędzia wysyłają i odbierają dane poza modelem. Zmniejsz ryzyko związane z bezpieczeństwem i prywatnością, wykonując następujące rozwiązania:

  • Traktuj dane wyjściowe narzędzia jako niezaufane dane wejściowe i weryfikuj wartości krytyczne zanim podejmiesz na ich podstawie działania.
  • Weryfikuj ustrukturyzowane dane wyjściowe względem oczekiwanego schematu, zezwalaj tylko na znane pola i operacje oraz wymagaj zatwierdzenia przez użytkownika przed wykonaniem działań o istotnych skutkach.
  • Wyślij tylko informacje wymagane do ukończenia zadania.
  • Nie dołączaj kluczy, tokenów ani innych poświadczeń w monitach.
  • Unikaj zapisywania tajemnic w śladach lub dziennikach aplikacji.
  • Jeśli łączysz się z usługami spoza firmy Microsoft (na przykład z serwerami MCP innych firm), zapoznaj się z zagadnieniami dotyczącymi przetwarzania danych w Tworzenie i zarządzanie przybornikiem w Foundry.
  • Jeśli potrzebujesz scentralizowanego routingu i wymuszania zasad dla narzędzi MCP, zobacz zarządzanie narzędziami za pomocą AI Gateway (wersja wstępna).

Rozwiązywanie problemów

Użyj tych testów, aby rozwiązać typowe problemy:

  • Agent nie wywołuje narzędzia:
    • Upewnij się, że narzędzie jest dołączone do agenta.
    • Potwierdź, że model obsługuje narzędzie.
    • Jeśli potrzebujesz zachowania deterministycznego, ustaw wartość tool_choicerequired.
    • Przejrzyj ślady, aby potwierdzić, czy model wygenerował wywołanie narzędzia.
  • Wywołania narzędzi zwracają puste lub nieistotne wyniki:
    • Ulepszanie opisów narzędzi i instrukcji agenta.
    • W przypadku narzędzi do pobierania upewnij się, że dane są przetwarzane i można je przeszukiwać.
  • Wywołania narzędzi kończą się niepowodzeniem:
    • Weryfikowanie konfiguracji i uwierzytelniania narzędzi.
    • W przypadku narzędzi MCP i OpenAPI sprawdź, czy punkt końcowy jest osiągalny i zwraca oczekiwane odpowiedzi.
  • Foundry zwraca błąd "narzędzie nieobsługiwane", mimo że tabele pokazują obsługę:
    • Dostępność narzędzia wymaga obsługi zarówno modelu, jak i regionu. Sprawdź tabelę dostępności regionów dla twojego regionu i tabelę obsługi modelu dla modelu. Jeśli którakolwiek z tabel wyświetla No, nie można uruchomić narzędzia, nawet jeśli druga tabela wyświetla Yes.
    • Upewnij się, że model jest rzeczywiście wdrożony w odpowiednim projekcie i regionie, który Cię interesuje. Model, który ogólnie obsługuje narzędzie, może nie zostać wdrożony w każdym regionie.
    • Spróbuj użyć innego regionu lub innego wdrożenia modelu, które obsługuje to narzędzie. Na przykład interpreter kodu nie działa w regionach, które pokazują no dla Interpretera Kodu (takich jak southcentralus i spaincentral), niezależnie od używanego modelu.

Często zadawane pytania

Jak sprawdzić, czy narzędzie zostało wywołane?

Przejrzyj ślady, aby potwierdzić, czy agent wywołał narzędzie, oraz sprawdzić dane wejściowe i wyjściowe narzędzia. Aby uzyskać instrukcje dotyczące konfiguracji, zobacz Konfigurowanie funkcji śledzenia dla agentów usługi Foundry.

Jak zwiększyć niezawodność użycia narzędzi?

Zacznij od przejrzystych instrukcji narzędzia. Jeśli potrzebujesz deterministycznego wywoływania narzędzi, użyj polecenia tool_choice. Aby uzyskać szczegółowe informacje, zobacz Wywoływanie narzędzia sterującego za pomocą polecenia tool_choice.

Powiązana zawartość

Zarządzanie narzędziami

Pobieranie i narzędzia wyszukiwania

Narzędzia do obsługi danych i integracji

Narzędzia automatyzacji i generowania

  • Ostatnia aktualizacja o