Anropa en värdbaserad agent med Azure Developer CLI

Använd azd ai agent invoke för att skicka meddelanden till din agent, antingen den distribuerade versionen i Microsoft Foundry eller en instans som körs lokalt. Du lär dig hur du väljer en agent, använder direkta slutpunkter, hanterar sessioner, skickar filer, fäster versioner och inspekterar råsvar.

Förutsättningar

• Ett initierat värdbaserat agentprojekt. Information om hur du skapar ett finns i Initiera ett agentprojekt.
• azd Foundry-tilläggen har installerats. Installationssteg finns i Installera azd Foundry-tilläggen.
• En autentiserad CLI-session för Azure utvecklare. Kör azd auth login om det behövs.
• För fjärranrop, en distribuerad värdbaserad agent. Information om hur du distribuerar en finns i Distribuera en värdbaserad agent.
• För lokalt anrop: en lokal agent som körs. Information om hur du startar en finns i Kör en värdbaserad agent lokalt med cli:et Azure Developer.

Anropa den distribuerade agenten

• Skicka en uppmaning till den distribuerade agenten:

  azd ai agent invoke "What is Microsoft Foundry?"
  

Anropa en specifik agent

• Om projektet innehåller flera agenter anger du vilken som ska anropas:

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

Anropa en specifik distribuerad slutpunkt

När du vill anropa en specifik distribuerad agent utan beroende på den aktiva azd-miljön eller azure.yamlanvänder du --agent-endpoint för att peka direkt på den distribuerade agentens URL. Det här mönstret är användbart från ett skript utanför projektet, från en kodningsagent eller när du testar en specifik agentversion.

• Ange den driftsatta agentslutpunkten:

  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 åsidosätter azd-miljö och azure.yaml lösning, så du behöver inte vara i en azd-projektkatalog för att använda den.

Anropa lokalt

• Anropa en lokal agent:

  azd ai agent invoke --local "Hello!"
  

  Agenten måste redan vara igång med azd ai agent run i en annan terminal.

Anropa via en anpassad lokal port

• Om din agent körs på en port som inte är standard skickar du --port:

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

Välj ett protokoll

Det protokoll som används för att anropa bestäms av protocols fältet för azure.ai.agent tjänsten i azure.yaml.

• responses - skickar en standardbegäran för OpenAI-svars-API:et med {"input": "your message"}. Konversationshistorik hanteras automatiskt.
• invocations - skickar den nyttolast som agentkoden förväntar sig. Använd --input-file (-f) med en JSON-fil som matchar det schema som hanteraren definierar.

För invocations-agenter, läs README-filen för exemplet eller granska hanterarens ingångspunkt för att förstå vilken nyttolast som förväntas.

• Om din agent implementerar flera protokoll, skicka --protocol (-p) för att välja:

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

Hantera sessioner

Sessioner sparas per agent. När du anropar en agent azd sparar du sessions-ID:t lokalt så att nästa invoke automatiskt fortsätter samma session och upprätthåller konversationshistoriken mellan anrop.

Starta en ny session

• Ignorera den sparade sessionen och börja om på nytt:

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

Använda ett specifikt sessions-ID

• Skicka ett befintligt sessions-ID:

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

Skicka en fil som inmatning

För strukturerade eller stora nyttolaster, särskilt med invocations protokollet, skickar du en JSON-fil.

1. Skicka en fil:

   azd ai agent invoke -f request.json
   

2. Eller skicka en fil till en specifik agent:

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

Använd en distribuerad version

När en agent har flera distribuerade versioner fäster du en specifik med --version. azd skapar eller återanvänder en session som backas upp av den versionen, så att varje version behåller sitt eget konversationstillstånd.

• Fäst en viss version:

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

  --version kan inte kombineras med --local eller --session-id eftersom sessioner är bundna till en version när de skapas.

Ange en anpassad tidsgräns

• Skicka en timeout i sekunder:

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

  Standardtidsgränsen är 1 800 sekunder (30 minuter). Använd --timeout 0 för att inte överskrida tidsgränsen.

Skicka isoleringsnycklar

Agenter som konfigurerats med Foundry-huvudbaserad isolering kräver nycklar per användare eller per chatt för varje begäran. Skicka dem med --user-isolation-key och --chat-isolation-key.

• Skicka isoleringsnycklar med begäran:

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

Det fullständiga mönstret, inklusive hur sessioner, filer och övervakningskommandon använder samma flaggor, finns i Skicka isoleringsnycklar till en värdbaserad agent.

Granska HTTP-råsvaret

När du behöver se exakt vad servern returnerade, inklusive svarshuvuden som agentversionen, statusraden och den oförändrade brödtexten, anger du --output raw (-o raw).

• Begär råutdata:

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

  I raw-läge ignoreras egna sammanfattningsrader som Session: och Invocation: och HTTP-svaret dumpas ordagrant. Det här läget är användbart för felsökning av serverbeteende och för att bekräfta vilken agentversion som hanterade anropet.

Relaterat innehåll

• Isolera sessioner för värdbaserade agenter per användare för användarisolering i agenter för flera klienter.
• Kör en värdbaserad agent lokalt med Azure Developer CLI för att starta din agent för lokal utveckling.
• Övervaka värdbaserade agentloggar med Azure Developer CLI för att inspektera distribuerade agentbeteenden.