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

Limitazioni dell'agente vocale

azd ai agent invoke non implementa conversazioni vocali. Quando azure.yaml identifica il servizio selezionato come voice o prompt-voice, il comando restituisce voice agents cannot be invoked with this command e reindirizza al portale Foundry.

Questa restrizione si applica anche a un wrapper vocale che usa conversationEngine per fare riferimento a una destinazione ospitata. Selezionando --protocol responses non si aggira il controllo del servizio voce.

Usa il playground per testare un agente vocale, come descritto nella guida introduttiva all'agente vocale.

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 un'identità utente finale

Passare --user-identity per inviare una richiesta per conto di un utente finale. Per le richieste remote, azd invia il valore nell'intestazione x-ms-user-identity . Il flag funziona con i protocolli Risposte, Chiamate e A2A.

La richiesta viene comunque autenticata con le credenziali Microsoft Entra del chiamante. L'intestazione identifica l'utente rappresentato; non sostituisce l'autenticazione o concede l'autorizzazione di delega elencata nei prerequisiti.

  • Inviare un'identità dell'utente finale all'agente distribuito:

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

    Sostituire user-123 con un identificatore stabile per l'utente finale autenticato. Includere --user-identity in ogni chiamata; il flag è vuoto per impostazione predefinita. Senza di esso, Foundry usa l'identità del chiamante.

azd salva gli ID sessione e conversazione per agente, non per --user-identity valore. La modifica dell'identità non seleziona uno stato salvato diverso. Quando si cambia utente con il protocollo Risposte, avviare una nuova sessione e una nuova conversazione:

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

Per riprendere lo stato Risposte esistente di un utente, passare i valori --session-id e --conversation-id di quell'utente insieme allo stesso valore di --user-identity. Non riutilizzare l'ID conversazione di un altro utente.

Usare --user-identity, non --client-header, per x-ms-user-identity. Il --client-header flag accetta solo nomi x-client-* e rifiuta gli header identity.

Per i requisiti di identificatore e il comportamento di isolamento, vedere Isolare le sessioni dell'agente ospitato per utente. Le versioni correnti dell'estensione agenti non accettano i precedenti flag --chat-isolation-key, --isolation-key o --user-isolation-key.

Passare l'identità a un agente locale

Con --local, azd invia lo stesso valore del flag di x-agent-user-id invece di x-ms-user-identity:

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

Usare questa intestazione per testare il modo in cui l'agente locale gestisce il contesto utente. Le esecuzioni locali non applicano le autorizzazioni di isolamento o delega di Foundry.

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

  • Ultimo aggiornamento: