Richiamare un agente ospitato con l'interfaccia della riga di comando per sviluppatori Azure

Usare azd ai agent invoke per inviare messaggi all'agente, ovvero la versione distribuita in Microsoft Foundry o un'istanza in esecuzione in locale. Imparerai come scegliere un agente, usare endpoint diretti, gestire le sessioni, inviare file, bloccare le versioni e controllare le risposte grezze.

Prerequisiti

Richiamare l'agente distribuito

  • Inviare un prompt all'agente distribuito:

    azd ai agent invoke "What is Microsoft Foundry?"

Richiamare un agente specifico

  • Se il progetto contiene più agenti, specificare quale richiamare:

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

Richiamare un endpoint distribuito specifico

Quando si vuole richiamare un agente distribuito specifico senza dipendere dall'ambiente azd attivo o azure.yaml, usare --agent-endpoint per puntare direttamente all'URL dell'agente distribuito. Questo modello è utile da uno script esterno al progetto, da un agente di codifica o quando si testa una versione specifica dell'agente.

  • Specifica l'endpoint dell'agente distribuito:

    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 sostituisce l'ambiente azd e la risoluzione di azure.yaml, quindi non è necessario essere all'interno della directory di progetto azd per usarlo.

Invoca localmente

  • Richiamare un agente locale:

    azd ai agent invoke --local "Hello!"

    L'agente deve essere già in esecuzione con azd ai agent run in un altro terminale.

Invocare su una porta locale personalizzata

  • Se l'agente è in esecuzione su una porta non predefinita, passare --port:

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

Scegliere un protocollo

Il protocollo utilizzato per invoke è determinato dal protocols campo del azure.ai.agent servizio in azure.yaml.

  • responses -- invia una richiesta API OpenAI Responses standard con {"input": "your message"}. La cronologia delle conversazioni viene gestita automaticamente.
  • invocations - invia qualsiasi payload previsto dal codice dell'agente. Usare --input-file (-f) con un file JSON corrispondente allo schema definito dal gestore.

Per gli agenti invocations, consultare il file LEGGIMI dell’esempio o esaminare il punto di ingresso del gestore per capire il payload previsto.

  • Se l'agente implementa più protocolli, passare --protocol (-p) per scegliere:

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

Gestire le sessioni

Le sessioni vengono salvate in modo permanente per agente. Quando si richiama un agente, salva l'ID sessione in locale, azd quindi la successiva invoke continua automaticamente la stessa sessione e mantiene la cronologia delle conversazioni tra le chiamate.

Avviare una nuova sessione

  • Rimuovere la sessione salvata e iniziare a eseguire le operazioni seguenti:

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

Usare un ID sessione specifico

  • Passa un ID di sessione esistente:

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

Inviare un file come input

Per payload strutturati o di grandi dimensioni, in particolare con il invocations protocollo, passare un file JSON.

  1. Inviare un file:

    azd ai agent invoke -f request.json

  2. In alternativa, inviare un file a un agente specifico:

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

Invocare una versione distribuita

Quando un agente dispone di più versioni distribuite, aggiungerne una specifica con --version. azd crea o riutilizza una sessione supportata da tale versione, in modo che ogni versione mantenga il proprio stato di conversazione.

  • Aggiungere una versione:

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

    --version non può essere combinato con --local o --session-id perché le sessioni sono associate a una versione al momento della creazione.

Impostare un timeout personalizzato

  • Passare un timeout in secondi:

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

    Il timeout predefinito è 1800 secondi (30 minuti). Utilizzare --timeout 0 per non impostare alcun timeout.

Passare le chiavi di isolamento

Gli agenti configurati con l'isolamento basato su intestazione di Foundry richiedono le chiavi per utente o per chat in ogni richiesta. Passarli con --user-isolation-key e --chat-isolation-key.

  • Passare le chiavi di isolamento con la richiesta:

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

Per il modello completo, incluso il modo in cui sessioni, file e comandi di monitoraggio usano gli stessi flag, vedere Passare le chiavi di isolamento a un agente ospitato.

Esaminare la risposta HTTP non elaborata

Quando è necessario visualizzare esattamente ciò che il server ha restituito, comprese intestazioni di risposta come la versione dell'agente, la riga di stato e il corpo non modificato, specificare --output raw (-o raw).

  • Richiedi output non elaborato:

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

    In modalità raw, le righe di riepilogo intuitive come Session: e Invocation: vengono soppresse e la risposta HTTP viene riportata integralmente. Questa modalità è utile per il debug del comportamento del server e la conferma della versione dell'agente che ha gestito la chiamata.

Contenuti correlati

  • Last updated on