pydantic · DouweM · Sep 8, 2025 · Aug 18, 2025 · Aug 18, 2025 · Aug 18, 2025
diff --git a/docs/api/durable_exec.md b/docs/api/durable_exec.md
@@ -1,3 +1,5 @@
 # `pydantic_ai.durable_exec`
 
 ::: pydantic_ai.durable_exec.temporal
+
+::: pydantic_ai.durable_exec.dbos
diff --git a/docs/durable_execution/dbos.md b/docs/durable_execution/dbos.md
@@ -0,0 +1,160 @@
+# Durable Execution with DBOS
+
+[DBOS](https://www.dbos.dev/) is a lightweight [durable execution](https://docs.dbos.dev/architecture) library natively integrated with Pydantic AI.
+
+## Durable Execution
+
+DBOS workflows make your program **durable** by checkpointing its state in a database. If your program ever fails, when it restarts all your workflows will automatically resume from the last completed step.
+
+* **Workflows** must be deterministic and generally cannot include I/O.
+* **Steps** may perform I/O (network, disk, API calls). If a step fails, it restarts from the beginning.
+
+Every workflow input and step output is durably stored in the system database. When workflow execution fails, whether from crashes, network issues, or server restarts, DBOS leverages these checkpoints to recover workflows from their last completed step.
+
+DBOS **queues** provide durable, database-backed alternatives to systems like Celery or BullMQ, supporting features such as concurrency limits, rate limits, timeouts, and prioritization. See the [DBOS docs](https://docs.dbos.dev/architecture) for details.
+
+The diagram below shows the overall architecture of an agentic application in DBOS.
+DBOS runs fully in-process as a library. Functions remain normal Python functions but are checkpointed into a database (Postgres or SQLite).
+
+```text
+                    Clients
+            (HTTP, RPC, Kafka, etc.)
+                        |
+                        v
++------------------------------------------------------+
+|               Application Servers                    |
+|                                                      |
+|   +----------------------------------------------+   |
+|   |        Pydantic AI + DBOS Libraries          |   |
+|   |                                              |   |
+|   |  [ Workflows (Agent Run Loop) ]              |   |
+|   |  [ Steps (Tool, MCP, Model) ]                |   |
+|   |  [ Queues ]   [ Cron Jobs ]   [ Messaging ]  |   |
+|   +----------------------------------------------+   |
+|                                                      |
++------------------------------------------------------+
+                        |
+                        v
++------------------------------------------------------+
+|                      Database                        |
+|   (Stores workflow and step state, schedules tasks)  |
++------------------------------------------------------+
+```
+
+See the [DBOS documentation](https://docs.dbos.dev/architecture) for more information.
+
+## Durable Agent
+
+Any agent can be wrapped in a [`DBOSAgent`][pydantic_ai.durable_exec.dbos.DBOSAgent] to get durable execution. `DBOSAgent` automatically:,
+
+* Wraps `Agent.run` and `Agent.run_sync` as DBOS workflows.
+* Wraps [model requests](../models/overview.md) and [MCP communication](../mcp/client.md) as DBOS steps.
+
+Custom tool functions and event stream handlers are not wrapped automatically. You can decorate them with `@DBOS.workflow` or `@DBOS.step` as needed.
+
+The original agent, model, and MCP server can still be used as normal outside the DBOS workflow.
+
+Here is a simple but complete example of wrapping an agent for durable execution. All it requires is to install Pydantic AI with the DBOS [open-source library](https://github.com/dbos-inc/dbos-transact-py):
+
+```sh
+pip/uv-add pydantic-ai[dbos]
+```
+
+```python {title="dbos_agent.py" test="skip"}
+from dbos import DBOS, DBOSConfig
+
+from pydantic_ai import Agent
+from pydantic_ai.durable_exec.dbos import DBOSAgent
+
+dbos_config: DBOSConfig = {
+    'name': 'pydantic_dbos_agent',
+    'system_database_url': 'sqlite:///dbostest.sqlite',  # (3)!
+}
+DBOS(config=dbos_config)
+
+agent = Agent(
+    'gpt-5',
+    instructions="You're an expert in geography.",
+    name='geography',  # (4)!
+)
+
+dbos_agent = DBOSAgent(agent)  # (1)!
+
+async def main():
+    DBOS.launch()
+    result = await dbos_agent.run('What is the capital of Mexico?')  # (2)!
+    print(result.output)
+    #> Mexico City (Ciudad de México, CDMX)
+```
+
+1. Workflows and `DBOSAgent` must be defined before `DBOS.launch()` so that recovery can correctly find all workflows.
+2. [`DBOSAgent.run()`][pydantic_ai.durable_exec.dbos.DBOSAgent.run] works like [`Agent.run()`][pydantic_ai.Agent.run], but runs as a DBOS workflow and executes model requests, decorated tool calls, and MCP communication as DBOS steps.
+3. This example uses SQLite. Postgres is recommended for production.
+4. The agent's `name` is used to uniquely identify its workflows.
+
+_(This example is complete, it can be run "as is" — you'll need to add `asyncio.run(main())` to run `main`)_
+
+Because DBOS workflows need to be defined before calling `DBOS.launch()` and the `DBOSAgent` instance automatically registers `run` and `run_sync` as workflows, it needs to be defined before calling `DBOS.launch()` as well.
+
+For more information on how to use DBOS in Python applications, see their [Python SDK guide](https://docs.dbos.dev/python/programming-guide).
+
+## DBOS Integration Considerations
+
+When using DBOS with Pydantic AI agents, there are a few important considerations to ensure workflows and toolsets behave correctly.
+
+### Agent and Toolset Requirements
+
+Each agent instance must have a unique `name` so DBOS can correctly resume workflows after a failure or restart. Tools that perform I/O or external interactions should be annotated as DBOS steps.
+
+Other than that, any agent and toolset will just work!
+
+### Agent Run Context and Dependencies
+
+DBOS checkpoints workflow inputs/outputs and step outputs into a database using `jsonpickle`. This means you need to make sure [dependencies](../dependencies.md) object provided to [`DBOSAgent.run()`][pydantic_ai.durable_exec.dbos.DBOSAgent.run] or [`DBOSAgent.run_sync()`][pydantic_ai.durable_exec.dbos.DBOSAgent.run_sync], and tool outputs can be serialized using jsonpickle. You may also want to keep the inputs and outputs small (under \~2 MB). PostgreSQL and SQLite support up to 1 GB per field, but large objects may impact performance.
+
+### Streaming
+
+Because DBOS cannot stream output directly to the workflow or step call site, [`Agent.run_stream()`][pydantic_ai.Agent.run_stream] is not supported when running inside of a DBOS workflow.
+
+Instead, you can implement streaming by setting an [`event_stream_handler`][pydantic_ai.agent.EventStreamHandler] on the `Agent` or `DBOSAgent` instance and using [`DBOSAgent.run()`][pydantic_ai.durable_exec.dbos.DBOSAgent.run].
+The event stream handler function will receive the agent [run context][pydantic_ai.tools.RunContext] and an async iterable of events from the model's streaming response and the agent's execution of tools. For examples, see the [streaming docs](../agents.md#streaming-all-events).
+
+
+## Step Configuration
+
+You can customize DBOS step behavior, such as retries, by passing [`StepConfig`][pydantic_ai.durable_exec.dbos.StepConfig] objects to the `DBOSAgent` constructor:
+
+- `mcp_step_config`: The DBOS step config to use for MCP server communication. No retries if omitted.
+- `model_step_config`: The DBOS step config to use for model request steps. No retries if omitted.
+
+For custom tools, you can annotate them directly with [`@DBOS.step`](https://docs.dbos.dev/python/reference/decorators#step) or [`@DBOS.workflow`](https://docs.dbos.dev/python/reference/decorators#workflow) decorators as needed. These decorators have no effect outside DBOS workflows, so tools remain usable in non-DBOS agents.
+
+
+## Step Retries
+
+On top of the automatic retries for request failures that DBOS will perform, Pydantic AI and various provider API clients also have their own request retry logic. Enabling these at the same time may cause the request to be retried more often than expected, with improper `Retry-After` handling.
+
+When using DBOS, it's recommended to not use [HTTP Request Retries](../retries.md) and to turn off your provider API client's own retry logic, for example by setting `max_retries=0` on a [custom `OpenAIProvider` API client](../models/openai.md#custom-openai-client).
+
+You can customize DBOS's retry policy using [step configuration](#step-configuration).
+
+## Observability with Logfire
+
+When using [Pydantic Logfire](../logfire.md), we **recommend disabling DBOS's built-in OpenTelemetry tracing**.
+DBOS automatically wraps workflow and step execution in spans, while Pydantic AI and Logfire already emit spans for the same function calls, model requests, and tool invocations. Without disabling DBOS tracing, these operations may appear twice in your trace tree.
+
+To disable DBOS traces and logs, you can set `disable_otlp=True` in `DBOSConfig`. For example:
+
+
+```python {title="dbos_no_traces.py" test="skip"}
+from dbos import DBOS, DBOSConfig
+
+dbos_config: DBOSConfig = {
+    'name': 'pydantic_dbos_agent',
+    'system_database_url': 'sqlite:///dbostest.sqlite',
+    'disable_otlp': True  # (1)!
+}
+DBOS(config=dbos_config)
+```
+
+1. If `True`, disables OpenTelemetry tracing and logging for DBOS. Default is `False`.
diff --git a/docs/durable_execution/overview.md b/docs/durable_execution/overview.md
@@ -0,0 +1,10 @@
+# Durable Execution
+
+Pydantic AI allows you to build durable agents that can preserve their progress across transient API failures and application errors or restarts, and handle long-running, asynchronous, and human-in-the-loop workflows with production-grade reliability. Durable agents have full support for [streaming](../agents.md#streaming-all-events) and [MCP](../mcp/client.md), with the added benefit of fault tolerance.
+
+Pydantic AI natively supports two durable execution solutions:
+
+- [Temporal](./temporal.md)
+- [DBOS](./dbos.md)
+
+These integrations only uses Pydantic AI's public interface, so they also serve as a reference for integrating with other durable systems.
diff --git a/docs/temporal.md → docs/durable_execution/temporal.md b/docs/temporal.md → docs/durable_execution/temporal.md
@@ -1,11 +1,8 @@
 # Durable Execution with Temporal
 
-Pydantic AI enables you to build durable agents that can preserve their progress across transient API failures and application errors or restarts, and handle long-running, asynchronous, and human-in-the-loop workflows with production-grade reliability. Durable agents have full support for [streaming](agents.md#streaming-all-events) and [MCP](mcp/client.md), with the added benefit of fault tolerance.
-
 [Temporal](https://temporal.io) is a popular [durable execution](https://docs.temporal.io/evaluate/understanding-temporal#durable-execution) platform that's natively supported by Pydantic AI.
-The integration only uses Pydantic AI's public interface, so it can also serve as a reference for how to integrate with another durable execution systems.
 
-### Durable Execution
+## Durable Execution
 
 In Temporal's durable execution implementation, a program that crashes or encounters an exception while interacting with a model or API will retry until it can successfully complete.
 
@@ -29,7 +26,7 @@ Activity code faces no restrictions on I/O or external interactions, but if an a
 
     See the [Temporal documentation](https://docs.temporal.io/evaluate/understanding-temporal#temporal-application-the-building-blocks) for more information
 
-In the case of Pydantic AI agents, integration with Temporal means that [model requests](models/overview.md), [tool calls](tools.md) that may require I/O, and [MCP server communication](mcp/client.md) all need to be offloaded to Temporal activities due to their I/O requirements, while the logic that coordinates them (i.e. the agent run) lives in the workflow. Code that handles a scheduled job or web request can then execute the workflow, which will in turn execute the activities as needed.
+In the case of Pydantic AI agents, integration with Temporal means that [model requests](../models/overview.md), [tool calls](../tools.md) that may require I/O, and [MCP server communication](../mcp/client.md) all need to be offloaded to Temporal activities due to their I/O requirements, while the logic that coordinates them (i.e. the agent run) lives in the workflow. Code that handles a scheduled job or web request can then execute the workflow, which will in turn execute the activities as needed.
 
 The diagram below shows the overall architecture of an agentic application in Temporal.
 The Temporal Server is responsible for tracking program execution and making sure the associated state is preserved reliably (i.e., stored to an internal database, and possibly replicated across cloud regions).
@@ -71,7 +68,7 @@ See the [Temporal documentation](https://docs.temporal.io/evaluate/understanding
 
 Any agent can be wrapped in a [`TemporalAgent`][pydantic_ai.durable_exec.temporal.TemporalAgent] to get a durable agent that can be used inside a deterministic Temporal workflow, by automatically offloading all work that requires I/O (namely model requests, tool calls, and MCP server communication) to non-deterministic activities.
 
-At the time of wrapping, the agent's [model](models/overview.md) and [toolsets](toolsets.md) (including function tools registered on the agent and MCP servers) are frozen, activities are dynamically created for each, and the original model and toolsets are wrapped to call on the worker to execute the corresponding activities instead of directly performing the actions inside the workflow. The original agent can still be used as normal outside the Temporal workflow, but any changes to its model or toolsets after wrapping will not be reflected in the durable agent.
+At the time of wrapping, the agent's [model](../models/overview.md) and [toolsets](../toolsets.md) (including function tools registered on the agent and MCP servers) are frozen, activities are dynamically created for each, and the original model and toolsets are wrapped to call on the worker to execute the corresponding activities instead of directly performing the actions inside the workflow. The original agent can still be used as normal outside the Temporal workflow, but any changes to its model or toolsets after wrapping will not be reflected in the durable agent.
 
 Here is a simple but complete example of wrapping an agent for durable execution, creating a Temporal workflow with durable execution logic, connecting to a Temporal server, and running the workflow from non-durable code. All it requires is a Temporal server to be [running locally](https://github.com/temporalio/temporal#download-and-start-temporal-server-locally):
 
@@ -173,7 +170,7 @@ Synchronous tool functions are supported, as tools are automatically run in acti
 
 As workflows and activities run in separate processes, any values passed between them need to be serializable. As these payloads are stored in the workflow execution event history, Temporal limits their size to 2MB.
 
-To account for these limitations, tool functions and the [event stream handler](#streaming) running inside activities receive a limited version of the agent's [`RunContext`][pydantic_ai.tools.RunContext], and it's your responsibility to make sure that the [dependencies](dependencies.md) object provided to [`TemporalAgent.run()`][pydantic_ai.durable_exec.temporal.TemporalAgent.run] can be serialized using Pydantic.
+To account for these limitations, tool functions and the [event stream handler](#streaming) running inside activities receive a limited version of the agent's [`RunContext`][pydantic_ai.tools.RunContext], and it's your responsibility to make sure that the [dependencies](../dependencies.md) object provided to [`TemporalAgent.run()`][pydantic_ai.durable_exec.temporal.TemporalAgent.run] can be serialized using Pydantic.
 
 Specifically, only the `deps`, `retries`, `tool_call_id`, `tool_name`, `tool_call_approved`, `retry`, and `run_step` fields are available by default, and trying to access `model`, `usage`, `prompt`, `messages`, or `tracer` will raise an error.
 If you need one or more of these attributes to be available inside activities, you can create a [`TemporalRunContext`][pydantic_ai.durable_exec.temporal.TemporalRunContext] subclass with custom `serialize_run_context` and `deserialize_run_context` class methods and pass it to [`TemporalAgent`][pydantic_ai.durable_exec.temporal.TemporalAgent] as `run_context_type`.
@@ -183,7 +180,7 @@ If you need one or more of these attributes to be available inside activities, y
 Because Temporal activities cannot stream output directly to the activity call site, [`Agent.run_stream()`][pydantic_ai.Agent.run_stream] and [`Agent.iter()`][pydantic_ai.Agent.iter] are not supported.
 
 Instead, you can implement streaming by setting an [`event_stream_handler`][pydantic_ai.agent.EventStreamHandler] on the `Agent` or `TemporalAgent` instance and using [`TemporalAgent.run()`][pydantic_ai.durable_exec.temporal.TemporalAgent.run] inside the workflow.
-The event stream handler function will receive the agent [run context][pydantic_ai.tools.RunContext] and an async iterable of events from the model's streaming response and the agent's execution of tools. For examples, see the [streaming docs](agents.md#streaming-all-events).
+The event stream handler function will receive the agent [run context][pydantic_ai.tools.RunContext] and an async iterable of events from the model's streaming response and the agent's execution of tools. For examples, see the [streaming docs](../agents.md#streaming-all-events).
 
 As the streaming model request activity, workflow, and workflow execution call all take place in separate processes, passing data between them requires some care:
 
@@ -206,13 +203,13 @@ Temporal activity configuration, like timeouts and retry policies, can be custom
 
 On top of the automatic retries for request failures that Temporal will perform, Pydantic AI and various provider API clients also have their own request retry logic. Enabling these at the same time may cause the request to be retried more often than expected, with improper `Retry-After` handling.
 
-When using Temporal, it's recommended to not use [HTTP Request Retries](retries.md) and to turn off your provider API client's own retry logic, for example by setting `max_retries=0` on a [custom `OpenAIProvider` API client](models/openai.md#custom-openai-client).
+When using Temporal, it's recommended to not use [HTTP Request Retries](../retries.md) and to turn off your provider API client's own retry logic, for example by setting `max_retries=0` on a [custom `OpenAIProvider` API client](../models/openai.md#custom-openai-client).
 
 You can customize Temporal's retry policy using [activity configuration](#activity-configuration).
 
 ## Observability with Logfire
 
-Temporal generates telemetry events and metrics for each workflow and activity execution, and Pydantic AI generates events for each agent run, model request and tool call. These can be sent to [Pydantic Logfire](logfire.md) to get a complete picture of what's happening in your application.
+Temporal generates telemetry events and metrics for each workflow and activity execution, and Pydantic AI generates events for each agent run, model request and tool call. These can be sent to [Pydantic Logfire](../logfire.md) to get a complete picture of what's happening in your application.
 
 To use Logfire with Temporal, you need to pass a [`LogfirePlugin`][pydantic_ai.durable_exec.temporal.LogfirePlugin] object to Temporal's `Client.connect()`: