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/versions/3 \
   "Summarize today's release notes."

    --agent-endpoint überschreibt die azd-Umgebung und die azure.yaml-Auflösung, sodass Sie sich nicht in einem azd-Projektverzeichnis befinden müssen, um es zu verwenden.

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

Das für den Aufruf verwendete Protokoll wird durch das protocols Feld des azure.ai.agent Diensts in azure.yamlbestimmt.

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

Ü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

Verwalten von Sitzungen

Sitzungen werden agentenspezifisch persistent gespeichert. Wenn Sie einen Agent aufrufen, wird die Sitzungs-ID lokal gespeichert, azd sodass die nächste invoke Sitzung automatisch dieselbe Sitzung fortsetzt und den Unterhaltungsverlauf über Anrufe hinweg verwaltet.

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"

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.

Isolationsschlüssel übergeben

Agenten, die mit der Header-basierten Isolation von Foundry konfiguriert sind, erfordern bei jeder Anfrage Schlüssel pro Benutzer oder pro Chat. Übergeben Sie sie mit --user-isolation-key und --chat-isolation-key.

  • Übergeben von Isolationsschlüsseln mit der Anforderung:

    azd ai agent invoke \
   --user-isolation-key "$USER_KEY" \
   --chat-isolation-key "$CHAT_KEY" \
   "Hello!"

Das vollständige Muster, einschließlich der Frage, wie Sitzungen, Dateien und Monitorbefehle dieselben Flags verwenden, finden Sie unter Isolationsschlüssel an einen gehosteten Agent übergeben.

Ü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

  • Last updated on