Deploy a crash-resilient long-running agent (preview)

Deploy a long-running hosted agent that keeps working with no client traffic, survives a container crash, and resumes from its last checkpoint.

In this article, you deploy a long-running hosted agent that uses the Responses protocol and the resilient background response feature. You run a stored background response, crash the agent process on purpose, and watch it resume from the last checkpoint after restart.

The agent runs three simulated streamed stages: analyze, generate, and refine. Each completed stage is one checkpointed output item, so a recovered run repeats at most one stage.

Long-running agents are in preview. APIs and package versions are subject to change.

Prerequisites

• An Azure subscription with Microsoft Foundry access.
• Python 3.13.
• The Azure Developer CLI (azd) with the Foundry agents extension: azd extension install azure.ai.agents.

Get the sample

In an empty directory, initialize the resilient streaming agent from its azure.yaml manifest:

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

The command downloads the sample source, adopts its azure.yaml, creates an azd environment, and connects it to the Foundry project you select.

The sample opts in to resilience when it creates the host:

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

resilient_background defaults to False. Without it, a background response that crashes is marked failed instead of being recovered. See Recover long-running work after a crash.

Run it locally

The resilient state store uses files when you run it locally, so your machine uses the same recovery code path.

azd ai agent run

azd ai agent run installs the Python dependencies, injects the active azd environment, and starts the agent on http://localhost:8088.

Test crash recovery locally

Use Linux, WSL2, or a container for this exercise so the operating system releases the file lock when the process exits.

In the terminal that runs the agent, set SIMULATE_CRASH_AFTER_STAGE so the sample crashes after it checkpoints the first stage, and then start it:

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

Recovery needs a stored background response (store: true and background: true), so send the full request body from a file. In a second terminal, create the request file:

cat > request.json <<'EOF'
{ "input": "renewable energy supply chains", "store": true, "background": true }
EOF

Invoke the local agent with that body:

azd ai agent invoke --local -f request.json

The agent checkpoints the analyze stage and then exits. Restart it from the first terminal:

azd ai agent run --no-client

The framework reinvokes the handler with context.is_recovery == True. The handler restores context.persisted_response, skips the checkpointed analyze stage, and completes the generate and refine stages.

Deploy to Foundry

Provision the project and deploy the agent. When prompted for a location, choose a region that supports hosted agents.

azd up

azd up prints the Responses endpoint and a playground link.

Invoke the deployed agent

Create a stored background response on the deployed agent. Reuse the same request.json body:

azd ai agent invoke -f request.json

Stream the agent logs:

azd ai agent monitor --follow

The platform keeps a background response running with no client traffic. For the reconnect protocol and the starting_after cursor, see Stream with reconnect.

Clean up

azd down

Related content

• Resilience for long-running hosted agents
• Recover long-running work after a crash
• Steer an in-flight agent turn
• Stream with reconnect