Een gehoste agent aanroepen met de Azure Developer CLI

Gebruik azd ai agent invoke deze optie om berichten naar uw agent te verzenden, ofwel de geïmplementeerde versie in Microsoft Foundry of een lokaal uitgevoerd exemplaar. U leert hoe u een agent kiest, directe eindpunten gebruikt, sessies beheert, bestanden verzendt, versies vastmaken en onbewerkte antwoorden inspecteert.

Prerequisites

Roep de geïmplementeerde agent aan

  • Verstuur een prompt naar de geïmplementeerde agent:

    azd ai agent invoke "What is Microsoft Foundry?"

Een specifieke agent aanroepen

  • Als uw project meerdere agents bevat, geeft u op welke agents u wilt aanroepen:

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

Een specifiek geïmplementeerd eindpunt aanroepen

Wanneer u een specifieke geïmplementeerde agent wilt aanroepen zonder afhankelijk te zijn van de actieve azd-omgeving of azure.yaml, gebruikt u --agent-endpoint om rechtstreeks naar de URL van de geïmplementeerde agent te verwijzen. Dit patroon is handig vanuit een script buiten het project, van een coderingsagent of wanneer u een specifieke agentversie test.

  • Geef het geïmplementeerde agent-endpoint door:

    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 overschrijft azd environment en azure.yaml resolution, dus u hoeft zich niet in een azd-projectmap te bevinden om deze te gebruiken.

Lokaal aanroepen

  • Een lokale agent aanroepen:

    azd ai agent invoke --local "Hello!"

    De agent moet al actief zijn met azd ai agent run in een andere terminal.

Aanroepen via een aangepaste lokale poort

  • Als uw agent op een niet-standaardpoort draait, geeft u --port door:

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

Een protocol kiezen

Het protocol dat wordt gebruikt voor aanroepen, wordt bepaald door het protocols veld van de azure.ai.agent service in azure.yaml.

  • responses -- verzendt een standaard Api-aanvraag voor OpenAI-antwoorden met {"input": "your message"}. Gespreksgeschiedenis wordt automatisch beheerd.
  • invocations -- verzendt de payload die uw agentcode verwacht. Gebruik --input-file (-f) met een JSON-bestand dat overeenkomt met het schema dat uw handler definieert.

Voor invocations agents, controleer de README van het voorbeeld of inspecteer het toegangspunt van de handler om de verwachte payload te begrijpen.

  • Als uw agent meerdere protocollen implementeert, geef --protocol (-p) mee om te kiezen:

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

Sessies beheren

Sessies worden per agent bewaard. Wanneer u een agent aanroept, slaat u de sessie-id lokaal op, azd zodat de volgende invoke automatisch dezelfde sessie doorgaat en de gespreksgeschiedenis bij gesprekken onderhoudt.

Een nieuwe sessie starten

  • Verwijder de opgeslagen sessie en begin nieuw:

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

Een specifieke sessie-id gebruiken

  • Geef een bestaande sessie-id door:

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

Een bestand verzenden als invoer

Geef voor gestructureerde of grote nettoladingen, met name met het invocations protocol, een JSON-bestand door.

  1. Een bestand verzenden:

    azd ai agent invoke -f request.json

  2. Of verzend een bestand naar een specifieke agent:

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

Een geïmplementeerde versie aanroepen

Wanneer een agent meerdere uitgebrachte versies heeft, zet er dan een specifieke vast met --version. azd maakt of hergebruikt een sessie die wordt ondersteund door die versie, zodat elke versie een eigen gespreksstatus behoudt.

  • Een versie vastzetten:

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

    --version kan niet worden gecombineerd met --local of --session-id omdat sessies zijn gebonden aan een versie wanneer ze worden gemaakt.

Een aangepaste time-out instellen

  • Geef een time-out in seconden door:

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

    De standaardtime-out is 1800 seconden (30 minuten). Gebruik --timeout 0 om geen time-out in te stellen.

Isolatiesleutels doorgeven

Agents die zijn geconfigureerd met headergebaseerde isolatie van Foundry vereisen bij elke aanvraag sleutels per gebruiker of per chat. Geef ze door met --user-isolation-key en --chat-isolation-key.

  • Isolatiesleutels doorgeven met de aanvraag:

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

Zie Isolatiesleutels doorgeven aan een gehoste agent voor het volledige patroon, inclusief hoe sessies, bestanden en controleopdrachten dezelfde vlaggen gebruiken.

Het onbewerkte HTTP-antwoord controleren

Wanneer u precies wilt zien wat de server heeft geretourneerd, inclusief responseheaders zoals de agentversie, de statusregel en de ongewijzigde body, geeft u --output raw (-o raw) door.

  • Onbewerkte uitvoer aanvragen:

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

    In de onbewerkte modus worden beschrijvende samenvattingslijnen zoals Session: en Invocation: onderdrukt en wordt het HTTP-antwoord gedumpt. Deze modus is handig voor het opsporen van fouten in servergedrag en het bevestigen van welke agentversie de aanroep heeft verwerkt.

Verwante inhoud

  • Last updated on