Distribuire un agente a lunga esecuzione resistente ai crash

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.
  • 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.
  • curl per la fase locale di ripristino da arresto anomalo. L'agente distribuito viene chiamato con azd, che gestisce automaticamente l'autenticazione.

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 -t 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)

Importante

Il valore predefinito di resilient_background è False. Senza di esso, una risposta in background che si arresta in modo anomalo viene contrassegnata failed invece di essere ripristinata. Consultare Recuperare il lavoro con esecuzione prolungata dopo un arresto anomalo.

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. La guida al ripristino locale dopo un arresto anomalo esegue l'agente con curl, quindi ogni esecuzione locale 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

Creare una risposta in background archiviata con --long-runninge restituire non appena la piattaforma assegna il relativo ID con --no-wait:

azd ai agent invoke --long-running --no-wait "renewable energy supply chains"

--long-running invia store=true e background=true, quindi la piattaforma mantiene la risposta in esecuzione senza traffico client. azd ai agent invoke risolve l'endpoint distribuito, esegue l'autenticazione e salva l'ID risposta restituito come chiamata corrente.

Controllare la risposta o riprodurre l'output dall'inizio con l'ID salvato:

azd ai agent invocations show
azd ai agent invocations follow

Passa --id <response-id> per selezionare una risposta specifica. Per il protocollo di riconnessione e il starting_after cursore, vedere Stream with reconnect (Flusso con riconnessione).

Pulizia

azd down