Wywoływanie hostowanego agenta za pomocą interfejsu wiersza polecenia dewelopera Azure

Użyj azd ai agent invoke, aby wysyłać wiadomości do agenta — zarówno do wersji wdrożonej w Microsoft Foundry, jak i do lokalnie uruchomionego wystąpienia. Dowiesz się, jak wybrać agenta, używać bezpośrednich punktów końcowych, zarządzać sesjami, wysyłać pliki, przypinać wersje i sprawdzać nieprzetworzone odpowiedzi.

Wymagania wstępne

Wywoływanie wdrożonego agenta

  • Wyślij monit do wdrożonego agenta:

    azd ai agent invoke "What is Microsoft Foundry?"

Wywoływanie określonego agenta

  • Jeśli projekt zawiera wielu agentów, określ, który z nich ma być wywoływany:

    azd ai agent invoke my-agent "What is Microsoft Foundry?"

Wywołaj konkretny wdrożony punkt końcowy

Jeśli chcesz wywołać określonego wdrożonego agenta bez względu na aktywne środowisko azd lub azure.yaml, użyj polecenia --agent-endpoint , aby wskazać bezpośrednio adres URL wdrożonego agenta. Ten schemat jest przydatny w skrypcie spoza projektu, z poziomu agenta programistycznego lub podczas testowania konkretnej wersji agenta.

  • Przekaż punkt końcowy wdrożonego agenta:

    azd ai agent invoke \
   --agent-endpoint "https://my-project.services.ai.azure.com/api/projects/my-project/agents/release-summarizer/endpoint/protocols/openai/responses?api-version=v1" \
   "Summarize today's release notes."

    Skopiuj endpoint protokołu callable z azd ai agent show lub azd ai agent endpoint show. Adres URL zarządzania wersjami kończący się ciągiem /versions/3 nie jest punktem końcowym wywołania. --agent-endpoint pomija środowisko azd i azure.yaml rozpoznawanie.

Wywoływanie lokalnie

  • Wywołaj agenta lokalnego:

    azd ai agent invoke --local "Hello!"

    Agent musi być już uruchomiony z azd ai agent run w innym terminalu.

Wywołaj na niestandardowym porcie lokalnym

  • Jeśli agent jest uruchomiony na porcie inny niż domyślny, przekaż polecenie --port:

    azd ai agent invoke --local --port 9090 "Hello!"

Wybieranie protokołu

W przypadku pominięcia --protocolCLI używa pełnych wdrożonych danych punktu końcowego, jeśli są dostępne, a następnie definicji agenta. Jeśli nie może zidentyfikować dokładnie jednego protokołu, który można wywołać, przekaż --protocol jawnie. Wdróż ponownie, aby odświeżyć dane punktu końcowego zapisane przez starsze rozszerzenia.

  • responses — wysyła standardowe żądanie do interfejsu OpenAI Responses API z użyciem {"input": "your message"}. Historia konwersacji jest zarządzana automatycznie.
  • invocations — wysyła dowolny ładunek danych oczekiwany przez kod agenta. Użyj --input-file (-f) z plikiem JSON zgodnym ze schematem, który definiuje program obsługi.
  • a2a - wywołuje wdrożony punkt końcowy Agent-to-Agent. Przekaż komunikat lub użyj --input-file z pełnym żądaniem JSON-RPC. Ten protokół nie obsługuje --local.

W przypadku agentów invocations zajrzyj do pliku README przykładu lub sprawdź punkt wejścia modułu obsługi, aby zrozumieć oczekiwany ładunek danych.

  • Jeśli agent implementuje wiele protokołów, przekaż --protocol (-p), aby wybrać:

    azd ai agent invoke --protocol invocations -f request.json

Ograniczenia agenta głosowego

azd ai agent invoke nie implementuje rozmów głosowych. Po azure.yaml zidentyfikowaniu wybranej usługi jako voice lub prompt-voicepolecenie zwraca voice agents cannot be invoked with this command i kieruje cię do portalu Foundry.

To ograniczenie dotyczy również nakładki głosowej, która używa conversationEngine, aby odwoływać się do hostowanego elementu docelowego. Wybranie --protocol responses nie pomija sprawdzania usługi głosowej.

Użyj placu zabaw, aby przetestować agenta głosowego zgodnie z opisem w przewodniku Szybki start agenta głosowego.

Zarządzaj sesjami

Interfejs wiersza polecenia zapisuje wybory sesji i konwersacji lokalnie dla poszczególnych agentów. Sesja zachowuje stan piaskownicy, taki jak przesłane pliki. W przypadku protokołu Responses konwersacja zachowuje historię komunikatów. Ponowne wykorzystanie samej sesji nie zapewnia historii konwersacji dla protokołu Invocations.

Rozpoczynanie nowej sesji

  • Odrzuć zapisaną sesję i rozpocznij nową:

    azd ai agent invoke --new-session "Start fresh"

Używanie określonego identyfikatora sesji

  • Przekaż istniejący identyfikator sesji:

    azd ai agent invoke --session-id my-session-123 "Continue conversation"

Wybierz oddzielnie historię konwersacji

W przypadku protokołu Responses rozpocznij nową konwersację z usługą --new-conversationlub kontynuuj znaną konwersację z --conversation-id:

azd ai agent invoke --new-conversation "Start a new topic"
azd ai agent invoke --conversation-id <conversation-id> "Continue this topic"

--new-session resetuje również zapisaną konwersację. Informacje o rozróżnieniu między historią konwersacji a stanem piaskownicy znajdziesz w Zarządzanie sesjami hostowanych agentów.

Wysyłanie pliku jako danych wejściowych

W przypadku uporządkowanych lub dużych danych wejściowych, szczególnie z użyciem protokołu invocations, przekaż plik JSON.

  1. Wyślij plik:

    azd ai agent invoke -f request.json

  2. Możesz też wysłać plik do określonego agenta:

    azd ai agent invoke my-agent -f request.json

Wywoływanie wdrożonej wersji

Jeśli agent ma wiele wdrożonych wersji, przypnij konkretną wersję za pomocą --version. azd tworzy lub ponownie używa sesji powiązanej z tą wersją, więc każda wersja zachowuje własny stan rozmowy.

  • Przypinanie wersji:

    azd ai agent invoke --version 3 "Use the v3 prompt"

    --version nie można połączyć z --local ani --session-id, ponieważ sesje są przypisywane do wersji w momencie ich tworzenia.

Ustaw niestandardowy limit czasu

  • Podaj limit czasu w sekundach:

    azd ai agent invoke --timeout 300 "Process this large dataset"

    Domyślny limit czasu to 1800 sekund (30 minut). Użyj --timeout 0, aby wyłączyć limit czasu.

Przekazywanie tożsamości użytkownika końcowego

Przekaż --user-identity , aby wysłać żądanie w imieniu użytkownika końcowego. W przypadku żądań azd zdalnych wysyła wartość w nagłówku x-ms-user-identity . Flaga działa z protokołami Responses, Invocations i A2A.

Żądanie jest nadal uwierzytelniane przy użyciu poświadczeń Microsoft Entra wywołującego. Nagłówek identyfikuje reprezentowanego użytkownika; nie zastępuje uwierzytelniania ani nie udziela uprawnień delegowania wymienionych w wymaganiach wstępnych.

  • Wyślij tożsamość użytkownika końcowego do wdrożonego agenta:

    azd ai agent invoke my-agent \
   --user-identity "user-123" \
   "Hello!"

    Zastąp user-123 stabilnym identyfikatorem uwierzytelnionego użytkownika końcowego. Dołącz --user-identity do każdego wywołania; domyślnie flaga jest pusta. Bez tego Foundry używa tożsamości podmiotu wywołującego.

azd zapisuje identyfikatory sesji i konwersacji dla każdego agenta, a nie dla każdej wartości --user-identity. Zmiana identyfikatora nie wybiera innego zapisanego stanu. Podczas przełączania użytkowników przy użyciu protokołu Odpowiedzi rozpocznij nową sesję i konwersację:

azd ai agent invoke my-agent --protocol responses \
  --user-identity "user-456" \
  --new-session --new-conversation \
  "Start a conversation for this user"

Aby wznowić istniejący stan Responses użytkownika, przekaż --session-id i --conversation-id tego użytkownika z użyciem tego samego --user-identity. Nie używaj ponownie identyfikatora rozmowy innego użytkownika.

Użyj wartości --user-identity, a nie --client-header, dla x-ms-user-identity. Flaga --client-header akceptuje tylko x-client-* nazwy i odrzuca nagłówki tożsamości.

Aby uzyskać informacje o wymaganiach dotyczących identyfikatorów i sposobie izolacji, zobacz Izolowanie sesji hostowanych agentów dla każdego użytkownika. Bieżące wersje rozszerzenia agentów nie akceptują wcześniejszych --user-isolation-keyflag , --chat-isolation-keyani --isolation-key .

Przekaż tożsamość lokalnemu agentowi

W przypadku polecenia --localazd wysyła tę samą wartość flagi co x-agent-user-id zamiast x-ms-user-identity:

azd ai agent invoke my-agent --local \
  --user-identity "user-123" \
  "Hello!"

Użyj tego nagłówka, aby przetestować sposób obsługi kontekstu użytkownika przez agenta lokalnego. Uruchomienia lokalne nie egzekwują uprawnień izolacji ani delegowania w Foundry.

Wyślij nagłówki specyficzne dla aplikacji

Użyj powtarzalnych --client-header "Name: Value" flag dla metadanych żądania, takich jak identyfikator korelacji lub etykieta dzierżawy:

azd ai agent invoke \
  --client-header "x-client-request-id: request-123" \
  --client-header "x-client-tenant: contoso" \
  "Hello!"

Akceptowane są tylko x-client-* nazwy nagłówków. Endpointy Responses i Invocations przekazują te nagłówki do agenta. Protokół A2A nie obsługuje tej flagi. Użyj wartości --user-identity, a nie --client-header, dla tożsamości delegowanej.

Uruchom pracę po rozłączeniu klienta

W przypadku protokołu Responses --long-running uruchamia pracę w tle po stronie usługi. Polecenie pozostaje podłączone do momentu ukończenia, chyba że przekażesz również --no-wait:

azd ai agent invoke --long-running --no-wait "Run the long task"

Polecenie kończy się po odebraniu identyfikatora odpowiedzi przypisanej przez usługę. Sprawdź, śledź lub zażądaj anulowania tej pracy:

azd ai agent invocations show --protocol responses
azd ai agent invocations follow --protocol responses
azd ai agent invocations cancel --protocol responses

Te polecenia domyślnie używają najnowszego zapisanego identyfikatora wybranego agenta i protokołu. Przekaż --id <response-id>, aby wskazać inną odpowiedź bez zmiany tego zaznaczenia. Użyj --agent-name lub --agent-endpoint, aby wybrać element docelowy i powtórz --user-identity dla delegowanych żądań. Bezpośredni punkt końcowy identyfikuje protokół; nie łącz go z --protocol ani z --agent-name.

Odpowiedzi obsługują wartości show, followi cancel. Wywołania obsługują show i cancel, ale nie follow. A2A nie obsługuje tych poleceń dotyczących cyklu życia. Usługa może odrzucać operacje, których dany agent nie obsługuje.

Wykonywanie w tle nie włącza odzyskiwania awaryjnego ani automatycznego ponownego nawiązywania połączenia. Skonfiguruj zachowanie odzyskiwania agenta oddzielnie; Zobacz Odzyskiwanie długotrwałej pracy po awarii.

Sprawdź opóźnienie platformy

Zdalne żądania Responses i Invocations hostowanego agenta domyślnie zbierają diagnostykę opóźnień platformy. Gdy usługa zwraca nagłówki chronometrażu, CLI wyświetla podsumowanie. Wyłącz gromadzenie i podsumowanie przy użyciu --debug-latency=false.

Wywołania lokalne, prompt-agent i A2A nie uwzględniają opóźnień platformy. Jawne --debug-latency=true jest odrzucane dla tych tras. To ustawienie jest niezależne od flagi globalnej --debug .

Sprawdzanie nieprzetworzonej odpowiedzi HTTP

Gdy musisz zobaczyć dokładnie to, co zwrócił serwer, w tym nagłówki odpowiedzi, na przykład wersję agenta, wiersz statusu i niezmodyfikowaną treść, przekaż parametr --output raw (-o raw).

  • Żądanie nieprzetworzonych danych wyjściowych:

    azd ai agent invoke --output raw "Hello!"

    W trybie surowym czytelne wiersze podsumowania, takie jak Session: i Invocation:, są pomijane, a odpowiedź HTTP jest wypisywana w niezmienionej postaci. Ten tryb jest przydatny do debugowania zachowania serwera i potwierdzania, która wersja agenta obsłużyła wywołanie.

Treści powiązane

  • Ostatnia aktualizacja o