Distribuire un agente orientabile (anteprima)

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.

Annotazioni

Gli agenti a esecuzione prolungata sono in anteprima. Le API e le versioni dei pacchetti sono soggette a modifiche.

Prerequisiti

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 -m 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

azd up visualizza l'endpoint Responses. Salvarlo, rimuovere la stringa di query e ottenere un token di accesso:

ENDPOINT="<responses-endpoint-from-azd-up>"
RESPONSES_ENDPOINT="${ENDPOINT%%\?*}"
TOKEN=$(az account get-access-token --resource https://ai.azure.com --query accessToken -o tsv)

Lo steering richiede risposte in background memorizzate (store: true e background: true). Avviare il primo turno e prendere nota dell'ID conversation nella risposta:

curl -sS -X POST "$RESPONSES_ENDPOINT?api-version=2025-11-15-preview" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"input": "Explain quantum computing in detail, including its history, principles, algorithms, hardware, error correction, and applications.", "store": true, "background": true}'

Mentre il primo turno è ancora in corso, inviare immediatamente una nuova istruzione nella stessa conversazione in modo che gestisca il turno in corso:

curl -sS -X POST "$RESPONSES_ENDPOINT?api-version=2025-11-15-preview" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"input": "Instead, explain relativity and focus on practical examples.", "conversation": "<conversation-id-from-turn-1>", "store": true, "background": true}'

La prima iterazione rileva l'input in coda e termina nel successivo punto sicuro. Il turno in coda viene quindi eseguito fino al completamento. Trasmetti in streaming una delle due risposte con il relativo id per vedere il passaggio:

curl -sS "$RESPONSES_ENDPOINT/<response-id>?api-version=2025-11-15-preview" \
  -H "Authorization: Bearer $TOKEN"

Pulizia

azd down

Contenuti correlati

  • Last updated on