Distribuire un agente a esecuzione prolungata tollerante agli arresti anomali (anteprima)

In questo articolo si distribuisce un agente ospitato a esecuzione prolungata che usa il protocollo Risposte e la funzionalità di risposta in background resiliente. Si esegue una risposta in background archiviata, si provoca intenzionalmente l'arresto anomalo del processo dell'agente e si osserva come riprende dall'ultimo checkpoint dopo il riavvio.

L'agente esegue tre fasi di streaming simulate: analizzare, generare e perfezionare. Ogni fase completata corrisponde a un elemento di output salvato con checkpoint, quindi un'esecuzione ripristinata ripete al massimo una fase.

Prerequisiti

• Una sottoscrizione di Azure con accesso a Microsoft Foundry.
• Python 3.13.
• L'interfaccia della riga di comando per sviluppatori di Azure (azd) con l'estensione agenti Foundry: azd extension install azure.ai.agents.
• interfaccia della riga di comando di Azure () e per chiamare l'agente distribuito.

Ottenere l'esempio

In una directory vuota, inizializzare l'agente di streaming 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-streaming/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'esempio acconsente esplicitamente alla resilienza quando crea l'host:

# src/resilient-streaming/main.py
options = ResponsesServerOptions(resilient_background=True)
app = ResponsesAgentServerHost(options=options)

Eseguilo localmente

L'archivio stati resiliente usa i file quando viene eseguito in locale, quindi il computer usa lo stesso percorso del codice di ripristino. Questa procedura dettagliata esegue l'agente tramite curl, quindi ogni esecuzione usa azd ai agent run --no-client, che installa le dipendenze Python, inietta l'ambiente azd attivo e avvia l'agente su http://localhost:8088 senza avviare Agent Inspector.

Verificare il ripristino da arresto anomalo localmente

Usare Linux, WSL2 o un contenitore per questo esercizio in modo che il sistema operativo rilasci il blocco del file al termine del processo.

Impostare SIMULATE_CRASH_AFTER_STAGE in modo che l'esempio vada in crash dopo aver creato il checkpoint del primo stadio, quindi avviare l'agente:

SIMULATE_CRASH_AFTER_STAGE=0 azd ai agent run --no-client

Il ripristino richiede una risposta in background archiviata (store: true e background: true). In un secondo terminale inviare la richiesta inline con curl:

curl -sS -X POST http://localhost:8088/responses \
  -H "Content-Type: application/json" \
  -d '{"input": "renewable energy supply chains", "store": true, "background": true}'

L'agente esegue il checkpoint della fase di analisi e quindi esce. Riavviarlo dal primo terminale:

azd ai agent run --no-client

Il framework richiama il gestore con context.is_recovery == True. Il gestore ripristina context.persisted_response, ignora la fase di analisi con checkpoint e completa le fasi di generazione e perfezionamento.

Eseguire la distribuzione in Foundry

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.

Richiamare l'agente distribuito

azd up stampa 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)

Create una risposta in background memorizzata e annotate il valore restituito id:

curl -sS -X POST "$RESPONSES_ENDPOINT?api-version=2025-11-15-preview" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"input": "renewable energy supply chains", "store": true, "background": true}'

La piattaforma mantiene la risposta in background in esecuzione senza traffico client. Effettuare il polling o lo streaming con il id della risposta precedente:

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

Per il protocollo di riconnessione e il starting_after cursore, vedere Stream with reconnect (Flusso con riconnessione).

Pulizia

azd down

Contenuti correlati

• Resilienza per gli agenti ospitati di lunga durata
• Recuperare il lavoro con esecuzione prolungata dopo un arresto anomalo.
• Instradare un turno dell'agente in corso
• Flusso con riconnessione