Aufrufen eines gehosteten Agents mit der Azure Developer CLI

Verwenden Sie azd ai agent invoke, um Nachrichten an Ihren Agenten zu senden, entweder an die bereitgestellte Version in Microsoft Foundry oder an eine lokal ausgeführte Instanz. Sie erfahren, wie Sie einen Agent auswählen, direkte Endpunkte verwenden, Sitzungen verwalten, Dateien senden, Versionen anheften und unformatierte Antworten überprüfen.

Voraussetzungen

Aufrufen des bereitgestellten Agents

  • Senden Sie einen Prompt an den bereitgestellten Agenten:

    azd ai agent invoke "What is Microsoft Foundry?"

Aufrufen eines bestimmten Agents

  • Wenn Ihr Projekt mehrere Agents enthält, geben Sie an, welches aufgerufen werden soll:

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

Aufrufen eines bestimmten bereitgestellten Endpunkts

Wenn Sie einen bestimmten bereitgestellten Agenten aufrufen möchten, ohne von der aktiven azd-Umgebung oder azure.yaml abhängig zu sein, verwenden Sie --agent-endpoint, um direkt auf die URL des bereitgestellten Agenten zu verweisen. Dieses Muster ist nützlich aus einem Skript außerhalb des Projekts, von einem Codierungs-Agent oder wenn Sie eine bestimmte Agent-Version testen.

  • Geben Sie den bereitgestellten Agent-Endpunkt an:

    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."

    Kopieren Sie den Callable-Protokollendpunkt von azd ai agent show oder azd ai agent endpoint show. Eine Versionsverwaltungs-URL, die mit /versions/3 endet, ist kein Aufrufendpunkt. --agent-endpoint umgeht die azd-Umgebung und die azure.yaml-Auflösung.

Lokal aufrufen

  • Aufrufen eines lokalen Agents:

    azd ai agent invoke --local "Hello!"

    Der Agent muss bereits mit azd ai agent run in einem anderen Terminal laufen.

Über einen benutzerdefinierten lokalen Port aufrufen

  • Wenn Ihr Agent auf einem anderen als dem Standardport ausgeführt wird, geben Sie --port an:

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

Auswählen eines Protokolls

Wenn Sie --protocol weglassen, verwendet die CLI vollständige bereitgestellte Endpunktdaten, wenn verfügbar, und dann die Agentdefinition. Wenn es nicht genau ein aufrufbares Protokoll identifizieren kann, geben Sie --protocol explizit an. Stellen Sie erneut bereit, um Endpunktdaten zu aktualisieren, die von älteren Erweiterungen gespeichert wurden.

  • responses -- sendet eine standardmäßige OpenAI-Antwort-API-Anforderung mit {"input": "your message"}. Aufgezeichnete Unterhaltungen werden automatisch verwaltet.
  • invocations -- sendet jede beliebige Payload, die Ihr Agentcode erwartet. Verwenden Sie --input-file (-f) mit einer JSON-Datei, die dem vom Handler definierten Schema entspricht.
  • a2a -- ruft einen bereitgestellten Agent-zu-Agent-Endpunkt auf. Übergeben Sie eine Nachricht, oder verwenden Sie --input-file mit einer vollständigen JSON-RPC-Anforderung. Dieses Protokoll unterstützt --local nicht.

Überprüfen Sie bei invocations-Agents die Infodatei des Beispiels, oder überprüfen Sie den Handler-Einstiegspunkt, um die erwartete Nutzlast zu verstehen.

  • Wenn Ihr Agent mehrere Protokolle implementiert, übergeben Sie --protocol (-p), um auszuwählen:

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

Einschränkungen des VoIP-Agents

azd ai agent invoke implementiert keine Sprachunterhaltungen. Wenn azure.yaml den ausgewählten Dienst als prompt-voice oder voice identifiziert, gibt der Befehl voice agents cannot be invoked with this command zurück und führt Sie zum Foundry portal.

Diese Einschränkung gilt auch für einen Sprachwrapper, der conversationEngine verwendet, um auf ein gehostetes Ziel zu verweisen. Durch die Auswahl --protocol responses wird die Sprachdienstprüfung nicht umgangen.

Verwenden Sie den Playground, um einen VoIP-Agent zu testen, wie in der Schnellstartanleitung des Sprach-Agents beschrieben.

Verwalten von Sitzungen

Die CLI speichert Die Sitzungs- und Unterhaltungsauswahl lokal pro Agent. Eine Sitzung behält den Sandbox-Status bei, z. B. hochgeladene Dateien. Für das Responses-Protokoll behält eine Unterhaltung den Nachrichtenverlauf bei. Die bloße Wiederverwendung einer Sitzung stellt für das Invocations-Protokoll keinen Gesprächsverlauf bereit.

Starten einer neuen Sitzung

  • Verwerfen Sie die gespeicherte Sitzung, und beginnen Sie neu:

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

Verwenden einer bestimmten Sitzungs-ID

  • Übergeben Sie eine vorhandene Sitzungs-ID:

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

Unterhaltungsverlauf separat auswählen

Starten Sie für das Antwortprotokoll eine neue Unterhaltung mit --new-conversation, oder setzen Sie eine bekannte Unterhaltung mit --conversation-id fort:

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

--new-session setzt auch die gespeicherte Unterhaltung zurück. Informationen zum Unterschied zwischen Konversationsverlauf und Sandkastenstatus finden Sie unter Verwalten gehosteter Agentsitzungen.

Senden einer Datei als Eingabe

Übergeben Sie für strukturierte oder große Nutzlasten, insbesondere mit dem invocations Protokoll, eine JSON-Datei.

  1. Senden einer Datei:

    azd ai agent invoke -f request.json

  2. Oder senden Sie eine Datei an einen bestimmten Agent:

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

Bereitgestellte Version aufrufen

Wenn ein Agent über mehrere bereitgestellten Versionen verfügt, fixieren Sie eine bestimmte mit --version. azd erstellt oder verwendet eine Sitzung wieder, die dieser Version zugeordnet ist, sodass jede Version ihren eigenen Konversationszustand beibehält.

  • Anheften einer Version:

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

    --version kann nicht mit --local oder --session-id kombiniert werden, weil Sitzungen bei ihrer Erstellung an eine Version gebunden werden.

Festlegen eines benutzerdefinierten Timeouts

  • Geben Sie ein Timeout in Sekunden an:

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

    Das Standardtimeout beträgt 1800 Sekunden (30 Minuten). Verwenden Sie --timeout 0 für kein Timeout.

Übergeben Sie eine Endbenutzeridentität

Übergeben Sie --user-identity, um eine Anfrage im Auftrag eines Endbenutzers zu senden. Sendet für Remoteanforderungen azd den Wert im x-ms-user-identity Header. Die Kennzeichnung funktioniert mit den Protokollen „Antworten“, „Aufrufe“ und „A2A“.

Die Anfrage wird weiterhin mit den Microsoft Entra-Anmeldeinformationen des Aufrufers authentifiziert. Die Kopfzeile identifiziert den repräsentierten Benutzer; sie ersetzt die Authentifizierung nicht und erteilt nicht die in den Voraussetzungen aufgeführte Delegierungsberechtigung.

  • Endbenutzeridentität an den bereitgestellten Agenten senden:

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

    Ersetzen Sie den user-123 Wert durch einen stabilen Bezeichner für den authentifizierten Endbenutzer. Bei jedem Aufruf --user-identity einschließen; die Kennzeichnung ist standardmäßig leer. Ohne diese Angabe verwendet Foundry die eigene Identität des Aufrufers.

azd Speichert Sitzungs- und Unterhaltungs-IDs pro Agent und nicht pro --user-identity Wert. Das Ändern der Identität führt nicht zur Auswahl eines anderen gespeicherten Zustands. Wenn Sie Benutzer mit dem Responses-Protokoll wechseln, starten Sie eine neue Sitzung und Konversation:

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

Wenn Sie den vorhandenen Responses-Status eines Benutzers fortsetzen möchten, übergeben Sie die --session-id und --conversation-id dieses Benutzers mit demselben --user-identity. Verwenden Sie die Konversations-ID eines anderen Benutzers nicht erneut.

Verwenden Sie --user-identity, nicht --client-header, für x-ms-user-identity. Das --client-header Flag akzeptiert nur x-client-* Namen und lehnt Identitätsheader ab.

Informationen zu Bezeichneranforderungen und Isolationsverhalten finden Sie unter Gehostete Agentsitzungen pro Benutzer isolieren. Aktuelle Versionen der Agents-Erweiterung akzeptieren die früheren --user-isolation-key, --chat-isolation-keyoder --isolation-key Flags nicht.

Identität an einen lokalen Agenten übergeben

Mit --local, azd sendet denselben Flagwert wie x-agent-user-id anstelle von x-ms-user-identity:

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

Verwenden Sie diesen Header, um zu testen, wie Ihr lokaler Agent den Benutzerkontext verarbeitet. Lokale Ausführungen erzwingen die Isolations- oder Delegierungsberechtigungen von Foundry nicht.

Anwendungsspezifische Header senden

Verwenden Sie wiederholbare --client-header "Name: Value" Flags für Anforderungsmetadaten, z. B. eine Korrelations-ID oder Mandantenbezeichnung:

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

Nur x-client-* Headernamen werden akzeptiert. Die Endpunkte Responses und Invocations leiten diese Header an Ihren Agent weiter. Das A2A-Protokoll unterstützt dieses Flag nicht. Verwenden Sie --user-identity, nicht --client-header, für Identitätsdelegierung.

Arbeit nach dem Trennen des Clients ausführen

Für das Responses-Protokoll startet --long-running dienstseitige Hintergrundarbeit. Der Befehl bleibt bis zum Abschluss angefügt, es sei denn, Sie übergeben auch --no-wait:

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

Der Befehl kehrt zurück, nachdem er die vom Dienst zugewiesene Antwort-ID empfängt. Überprüfen, verfolgen oder die Stornierung dieser Arbeit anfordern:

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

Diese Befehle verwenden standardmäßig die neueste gespeicherte ID für den ausgewählten Agent und das ausgewählte Protokoll. Übergeben Sie --id <response-id>, um eine andere Antwort als Ziel festzulegen, ohne diese Auswahl zu ändern. Verwenden Sie --agent-name oder --agent-endpoint, um ein Ziel auszuwählen, und wiederholen Sie --user-identity für delegierte Anforderungen. Ein direkter Endpunkt identifiziert das Protokoll; kombinieren Sie ihn nicht mit --protocol oder --agent-name.

Die Funktion „Antworten“ unterstützt show, follow und cancel. Aufrufe unterstützen show und cancel, aber nicht follow. A2A unterstützt diese Lebenszyklusbefehle nicht. Der Dienst kann Vorgänge ablehnen, die ein einzelner Agent nicht implementiert.

Die Hintergrundausführung aktiviert keine Absturzwiederherstellung oder automatische Wiederverbindung. Konfigurieren Sie das Wiederherstellungsverhalten des Agents separat; siehe "Wiederherstellung lang ausgeführter Arbeit nach einem Absturz".

Plattformlatenz überprüfen

Response- und Invocation-Anfragen von Remote-Hosted-Agent sammeln standardmäßig Plattformlatenzdiagnosen. Wenn der Dienst Timing-Header zurückgibt, zeigt die CLI eine Zusammenfassung an. Deaktivieren Sie die Erfassung und die Zusammenfassung über --debug-latency=false.

Lokale Aufrufe, Prompt-Agent und A2A-Aufrufe sammeln keine Plattformlatenz. Die explizite Angabe --debug-latency=true wird für diese Routen nicht akzeptiert. Diese Einstellung ist unabhängig von dem globalen --debug Flag.

Überprüfen der unformatierten HTTP-Antwort

Wenn Sie genau sehen müssen, was der Server zurückgegeben hat, einschließlich Response-Headern wie der Agent-Version, der Statuszeile und dem unveränderten Body, übergeben Sie --output raw (-o raw).

  • Rohausgabe anfordern:

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

    Im unformatierten Modus werden benutzerfreundliche Sammelzeilen wie Session: und Invocation: unterdrückt, und die HTTP-Antwort wird verbatim gedumpt. Dieser Modus ist nützlich für das Debuggen des Serververhaltens und die Bestätigung, welche Agentversion den Anruf verarbeitet hat.

Verwandte Inhalte

  • Zuletzt aktualisiert um