Distribuire un agente orientabile

In questo articolo, si distribuisce un agente ospitato a esecuzione prolungata che supporta la gestione: quando arriva un secondo turno nella stessa conversazione mentre il primo è ancora in esecuzione, la piattaforma accoda il nuovo turno e annulla in modo cooperativo quello in corso anziché rifiutarlo con 409 conversation_locked.

L'esempio è un agente del protocollo Responses che abilita la resilienza e l'instradamento con due opzioni. Usa un flusso di modelli simulato, in modo da poterlo eseguire senza credenziali del modello.

Prerequisiti

  • Una sottoscrizione di Azure con accesso a Microsoft Foundry.
  • Python 3.13.
  • La Azure Developer CLI (azd) con l'estensione degli agenti Foundry (azd extension install azure.ai.agents), la versione azd-ext-azure-ai-agents_1.0.0-beta.16 o successiva per il flag di chiamata --long-running e i comandi del ciclo di vita invocations. azd gestisce l'autenticazione quando chiama l'agente distribuito.

Ottenere l'esempio

In una directory vuota inizializzare l'agente di gestione resiliente dal relativo manifesto azure.yaml:

azd auth login
azd ai agent init -t https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/bring-your-own/responses/resilient-steering/azure.yaml

Il comando scarica il codice sorgente di esempio, ne adotta il relativo azure.yaml, crea un ambiente azd e lo collega al progetto Foundry selezionato.

L'agente consente resilienza e gestione durante la creazione dell'host:

options = ResponsesServerOptions(
    resilient_background=True,
    steerable_conversations=True,
)
app = ResponsesAgentServerHost(options=options)

Usando steerable_conversations=True, un secondo turno in una conversazione già occupata viene accodato e l'handler in esecuzione viene annullato in modo cooperativo, anziché restituire 409 conversation_locked.

Provisioning e distribuzione

Effettuare il provisioning del progetto e distribuire l'agente. Quando viene richiesta una località, seleziona una regione che supporta gli agenti ospitati.

azd up

azd up mostra l'endpoint di risposte e un link al playground.

Gestire l'agente distribuito

La gestione reindirizza un turno corrente, quindi il primo turno deve continuare a funzionare mentre si invia il secondo. Avvia la prima interazione come risposta in background di lunga durata in una nuova conversazione e restituisci immediatamente --no-wait:

azd ai agent invoke --long-running --no-wait --new-session "Explain quantum computing in detail, including its history, principles, algorithms, hardware, error correction, and applications."

--long-running invia store=true e background=true, e azd ai agent invoke riutilizza quella conversazione alla successiva chiamata per impostazione predefinita. Mentre il primo turno è ancora in esecuzione, inviare una nuova istruzione per guidare il turno in corso. Ometti --no-wait questa volta in modo che la CLI resti collegata e trasmetta in streaming il turno guidato fino al completamento:

azd ai agent invoke --long-running "Instead, explain relativity and focus on practical examples."

La prima iterazione rileva l'input in coda e termina nel successivo punto sicuro. Il turno in coda viene quindi trasmesso nel terminale fino al completamento, così è possibile osservare il passaggio. Per riprodurre invece una risposta specifica in base all'ID, usare azd ai agent invocations follow --id <response-id>.

Pulizia

azd down