> ## Documentation Index
> Fetch the complete documentation index at: https://hobbyist-e43fa225.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/agents/long-running-agent-resilience) 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.

<Note>
  Long-running agents are in preview. APIs and package versions are subject to change.
</Note>

## Prerequisites

* An Azure subscription with Microsoft Foundry access.
* [Python 3.13](https://www.python.org/downloads/).
* The [Azure Developer CLI (`azd`)](https://learn.microsoft.com/azure/developer/azure-developer-cli/install-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:

```bash theme={null}
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:

```python theme={null}
# src/resilient-streaming/main.py
options = ResponsesServerOptions(resilient_background=True)
app = ResponsesAgentServerHost(options=options)
```

<Info>
  `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](/agents/recover-long-running-work).
</Info>

## Run it locally

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

```bash theme={null}
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:

```bash theme={null}
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:

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

Invoke the local agent with that body:

```bash theme={null}
azd ai agent invoke --local -f request.json
```

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

```bash theme={null}
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](/agents/hosted-agents#region-availability).

```bash theme={null}
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:

```bash theme={null}
azd ai agent invoke -f request.json
```

Stream the agent logs:

```bash theme={null}
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](/agents/stream-with-reconnect).

## Clean up

```bash theme={null}
azd down
```

## Related content

* [Resilience for long-running hosted agents](/agents/long-running-agent-resilience)
* [Recover long-running work after a crash](/agents/recover-long-running-work)
* [Steer an in-flight agent turn](/agents/steer-hosted-agent)
* [Stream with reconnect](/agents/stream-with-reconnect)