AgentOps
Azure Durable Task for Pydantic AI Agents, Explained
Codesprint Consulting
By,Codesprint Consulting
  • 17 November 2026

Azure Durable Task for Pydantic AI agents was announced on November 16, 2026, in coordinated posts from the Azure team and the Pydantic team, and it targets the most expensive failure in agent systems: a worker that dies mid-run and takes all the progress you already paid for with it. The integration ships as AzureDurableTaskDurability, a Pydantic AI capability that turns model requests, function tool calls, and MCP calls into checkpointed Durable Task activities, so a replacement worker replays recorded results instead of repeating them. This post covers what the integration actually does, the replay model and its honest limits, how human approval works without holding an activity open, per-role retries, deployment to Azure, and when to pick it over Temporal, DBOS, or the other durable engines Pydantic AI supports. Source: Introducing Azure Durable Task for Pydantic AI agents, Microsoft Community Hub

What the integration does

Azure Durable Task Scheduler records the result of every completed activity. When a worker dies, another worker picks up the orchestration, replays the recorded results, and continues from the step that was in flight. The new capability brings the Pydantic AI agent loop into that model: by default, model requests, function tool calls, MCP calls, and durable capability operations each run as a Durable Task activity. Outside an orchestration, the agent runs exactly as it did before, so adopting it is not a rewrite. Source: Durable Pydantic AI agents with Azure Durable Task, pydantic.dev

The pitch is practical rather than conceptual. Completed model responses and tool results are recorded durably, so recovery reuses them instead of spending the tokens again. Retry policies for model requests and tool calls are configured, not hand-built around every step. An agent can prepare a proposal, pause for hours or days for a human decision, and continue when the answer arrives, without holding an activity execution open during the wait. And Durable Task workflows can coordinate several specialist agents when one is not enough. Source: Introducing Azure Durable Task for Pydantic AI agents, Microsoft Community Hub

Adding durability without rewriting the agent

A Pydantic AI Capability is a reusable extension that adds behavior to an agent: tools, instructions, or lifecycle hooks. Durability ships as a Capability, not a replacement framework. You attach AzureDurableTaskDurability through capabilities=[durability], give the agent a name (the name prefixes every activity it registers, which is how it lands in orchestration history), and call the agent from a Durable Task orchestrator through run_durable. Prompts and tool functions stay ordinary Pydantic AI code. The quickstart uses the standalone Durable Task Python SDK, so no Azure Functions app is required. Source: Introducing Azure Durable Task for Pydantic AI agents, Microsoft Community Hub

Local development runs against the Durable Task Scheduler emulator in Docker, which serves the SDK on port 8080 and a dashboard on localhost:8082. The dashboard shows orchestration instances moving through Pending, Running, Completed, or Failed, and each instance's timeline exposes the individual model, tool, and MCP activities with their inputs, outputs, durations, and retry attempts. You can see which operation failed without reconstructing the conversation from logs. Source: Introducing Azure Durable Task for Pydantic AI agents, Microsoft Community Hub

The crash test, and what it proves

The Pydantic team's article includes a deliberately brutal demo. A support agent looks up an order and issues a refund; the author kills the worker with os._exit(1) inside the refund tool, after the refund ran but before its result reached the scheduler. A second worker then resumes the orchestration: it does not repeat the two model requests or the order lookup, because those results were recorded. It re-runs only the refund call, whose result was never recorded, then makes the final model request and completes about a second later. Two details matter here. The idempotency key built from ctx.run_id and ctx.tool_call_id was identical across both executions, which is what makes a retried side effect safe. And the refund tool genuinely ran twice. Source: Durable Pydantic AI agents with Azure Durable Task, pydantic.dev

That second fact is the honest shape of durable execution, and both write-ups state it plainly: recovery is at-least-once for anything whose result was not yet recorded. Durable recovery does not guarantee exactly-once side effects, so tools that change external systems, like creating an order or moving money, must be idempotent. If you want the broader pattern behind this, our post on AI agent idempotency covers key design across agent tools. Source: Introducing Azure Durable Task for Pydantic AI agents, Microsoft Community Hub

Replay rules worth memorizing

The replay model imposes real constraints on how you write the agent, and the Pydantic article lists them plainly. Activities run at least once, so tools need idempotency keys. Orchestrator-side code, including hooks, instruction functions, output validators, and inline tools, runs on every replay, so it must be deterministic and free of network, file, or thread I/O; put I/O in a tool or a capability's durable operation method. Activity names are persisted, so do not rename the agent, toolsets, or tools while orchestrations that use them are still running. Replay cost grows with run length, because each replay re-runs the agent up to its latest step, so orchestrator CPU grows with the square of the step count; keep very long conversations in separate orchestrations. Dependencies must be JSON-serializable, so create database clients and HTTP sessions inside the tool that uses them, not in deps. Source: Durable Pydantic AI agents with Azure Durable Task, pydantic.dev

Two operational quirks round out the list. Spans repeat: Pydantic AI spans created in orchestrator code are emitted again on every replay, so one run can show its agent spans several times in Logfire. And errors change type across the boundary: an exception raised in a model request or tool reaches the orchestrator as durabletask.task.TaskFailedError, while UserError keeps its type. Source: Durable Pydantic AI agents with Azure Durable Task, pydantic.dev

Approvals that hold no activity open

Some tool calls need a person to say yes: a refund above a threshold, a production deploy, a payment. With this integration, the approval belongs to the orchestrator and the orchestration waits for an external event, so no activity runs while it waits, whether the review takes five minutes or three days. You mark the tool with requires_approval=True and add DeferredToolRequests to the agent's output type. The orchestrator publishes the pending tool calls and a fresh event name in its custom status; your review UI reads that status, collects the decision, and raises the event back. The agent resumes with its full message history and the usage it had already accumulated. Source: Durable Pydantic AI agents with Azure Durable Task, pydantic.dev

Two details are easy to get wrong. A new event name per pause means a late decision cannot accidentally answer a later review. And Durable Task matches event names case-insensitively, so tool-call IDs belong in the event payload, never in the event name. This approval shape is worth comparing with the one we covered yesterday in managed tool approvals in the OpenAI Agents SDK: the OpenAI flow suspends session state and resumes inside the SDK, while the Durable Task flow parks the whole orchestration on an external event. Same goal, different durability model. Source: Durable Pydantic AI agents with Azure Durable Task, pydantic.dev

Retries per role

Native RetryPolicy values can be set separately for model requests and tool calls, for example three attempts for model requests and two for tool calls, each with its own first retry interval. ModelRetry and deferred calls are agent control flow rather than activity failures, so they never consume a retry, and UserError and serialization failures are not retried at all. For finer control, resolve_tool_options returns a policy per tool, or False to run a pure function tool inline in the orchestrator instead of as an activity; inline tools replay on every step, so they must be deterministic and free of I/O. MCP and dynamic tools always run as activities. Source: Durable Pydantic AI agents with Azure Durable Task, pydantic.dev

From emulator to Azure

Moving to a real scheduler changes the worker and client, not the agent: swap in the Azure-managed DurableTaskSchedulerWorker and DurableTaskSchedulerClient with DefaultAzureCredential, grant the worker's identity the Durable Task Data Contributor role on the scheduler or task hub, and use a separate task hub per environment so staging orchestrations never replay against production workers. The worker is a long-running Python process that runs wherever you already run those, such as Azure Container Apps, AKS, or a VM; nothing registers with Azure Functions. The same dashboard experience is available from your task hub in the Azure portal. Source: Durable Pydantic AI agents with Azure Durable Task, pydantic.dev

Where it fits among durable engines

Pydantic AI now lists nine durable execution options: Temporal, DBOS, Prefect, Restate, AWS Lambda, Absurd, pgtask, Azure Durable Task, and Apache Airflow. The Azure option is the natural pick when your estate already runs on Azure and you want the managed scheduler, the portal dashboard, and identity-based access instead of operating a Temporal cluster. Teams already invested in Temporal or DBOS have no reason to move; the capability pattern means the agent code barely changes between engines. Source: Durable Pydantic AI agents with Azure Durable Task, pydantic.dev

Why this matters

Durable execution has been the dividing line between agent demos and agent systems, and it used to mean adopting a workflow engine's whole worldview. Shipping durability as a capability that wraps the agent you already have lowers that bar considerably. The pieces that matter for production trust are all present on day one: checkpointed model calls so crashes do not double your token bill, idempotency keys that survive restarts, an approval flow that parks the run instead of burning compute, and a dashboard that shows each model and tool step without log archaeology. Pair it with an observability practice like the one in our AI agent observability checklist and the operational story is close to complete. Source: Introducing Azure Durable Task for Pydantic AI agents, Microsoft Community Hub

Our read

Our read: the most important sentence in either announcement is the at-least-once admission, because it tells you the teams shipping this understand the failure modes instead of hiding them. The capability design is the right call, and the approval-via-external-event pattern is cleaner for long waits than in-SDK session suspension when reviewers take days. Two cautions from our assessment: the quadratic replay cost makes very long agent conversations a real capacity concern, not a theoretical one, and the rename freeze on agents and tools during in-flight orchestrations will bite teams that version tool names casually. Start with one high-value, crash-sensitive workflow like refunds or onboarding, run it against the emulator with a kill test of your own, and only then move the orchestrator to Azure.

FAQ

It is an integration, announced November 16, 2026, that adds durable execution to Pydantic AI agents through the AzureDurableTaskDurability capability. Model requests, function tool calls, and MCP calls become checkpointed Durable Task activities, so a replacement worker can resume a crashed run from recorded results instead of repeating work.

No. You attach the capability to your existing agent, give the agent a name, and call it from a Durable Task orchestrator with run_durable. Prompts and tool functions stay as they are, and outside an orchestration the agent runs exactly as before.

No. Activities run at least once: a worker can die after a tool's side effect but before its result is recorded, and the replacement worker will run that tool again. Tools that change external systems must be idempotent, and ctx.run_id plus ctx.tool_call_id survive restarts unchanged, which makes them a good idempotency key.

Mark the tool with requires_approval=True and add DeferredToolRequests to the output type. The orchestration publishes the pending calls in its custom status and waits for an external event, so no activity runs during the wait. A review UI reads the status, collects the decision, and raises the event; the agent resumes with full history and accumulated usage.

No. The integration uses the standalone Durable Task Python SDK, and local development runs against the Durable Task Scheduler emulator in Docker, which includes a dashboard at localhost:8082. An Azure subscription is only needed when you move the worker and client to the managed scheduler.

Tag:
  • azure durable task
  • pydantic ai
  • durable execution
  • agent orchestration
  • human in the loop

Have a project in mind? Let's talk.

Drop Us a Line

Connect with Codesprint Consulting

Ready to take the first step towards unlocking opportunities, realizing goals, and embracing innovation? We're here and eager to connect.

Your Success Starts Here!