Simplify DBOS docs

Author: qianl15

docs/dbos.md

@@ -1,41 +1,22 @@
 # Durable Execution with DBOS
 
-!!! note
-    Durable execution support is in beta and the public interface is subject to change based on user feedback. We expect it to be stable by the release of Pydantic AI v1 at the end of August. Questions and feedback are welcome in [GitHub issues](https://github.com/pydantic/pydantic-ai/issues) and the [`#pydantic-ai` Slack channel](https://logfire.pydantic.dev/docs/join-slack/).
-
 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.
 
-[DBOS](https://www.dbos.dev/) is a lightweight [durable execution](https://docs.dbos.dev/architecture) library 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 other durable execution systems.
+[DBOS](https://www.dbos.dev/) is a lightweight [durable execution](https://docs.dbos.dev/architecture) library natively integrated with Pydantic AI. The integration only uses Pydantic AI's public interface, so it also serves as a reference for integrating with other durable systems.
 
 ### Durable Execution
 
-In DBOS'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.
-
-DBOS relies primarily on a replay mechanism to recover from failures.
-As the program makes progress, DBOS saves key inputs and decisions, allowing a re-started program to pick up right where it left off.
-
-The key to making this work is to separate the application's repeatable (deterministic) and non-repeatable (non-deterministic) parts:
-
-1. Deterministic pieces, termed [**workflows**](https://docs.dbos.dev/python/tutorials/workflow-tutorial), execute the same way when re-run with the same inputs.
-2. Non-deterministic pieces, termed [**steps**](https://docs.dbos.dev/python/tutorials/step-tutorial), can run arbitrary code, performing I/O and any other operations.
-
-Workflow code can run for extended periods and, if interrupted, resume exactly where it left off.
-Critically, workflow code generally _cannot_ include any kind of I/O, over the network, disk, etc.
-Step code faces no restrictions on I/O or external interactions, but if a step fails part-way through it is restarted from the beginning.
-
-
-!!! note
+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.
 
-    If you are familiar with celery, it may be helpful to think of DBOS steps as similar to celery tasks, but where you wait for the task to complete and obtain its result before proceeding to the next step in the workflow.
-    However, DBOS workflows and steps offer a great deal more flexibility and functionality than celery tasks.
+* **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.
 
-    See the [DBOS documentation](https://docs.dbos.dev/architecture) for more information.
+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.
 
-In the case of Pydantic AI agents, integration with DBOS means that [model requests](models/index.md), [tool calls](tools.md) that may require I/O, and [MCP server communication](mcp/client.md) all need to be offloaded to DBOS steps 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 steps as needed.
+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 is lightweight because it runs entirely in-process as a library, so your workflows and steps remain normal functions within your application that you can call from other application code. DBOS instruments them to checkpoint their state into a database (i.e., possibly replicated across cloud regions).
+DBOS runs fully in-process as a library. Functions remain normal Python functions but are checkpointed into a database (Postgres or SQLite).
 
 ```text
                     Clients
@@ -66,18 +47,20 @@ See the [DBOS documentation](https://docs.dbos.dev/architecture) for more inform
 
 ## Durable Agent
 
-Any agent can be wrapped in a [`DBOSAgent`][pydantic_ai.durable_exec.dbos.DBOSAgent] to get a durable agent, by automatically wrapping the agent run loop as a deterministic DBOS workflow and offloading work that requires I/O (namely model requests and MCP server communication) to non-deterministic steps. To make it flexible, `DBOSAgent` doesn't automatically wrap other tool functions, so you can decorate them as either DBOS workflows or steps as needed.
+Any agent can be wrapped in a [`DBOSAgent`][pydantic_ai.durable_exec.dbos.DBOSAgent] to get durable execution. `DBOSAgent` automatically:,
 
-At the time of wrapping, the agent's [model](models/index.md) and [MCP server communication](mcp/client.md) are wrapped as DBOS steps instead of directly invoking the original functions inside the workflow. The original agent can still be used as normal outside the DBOS workflow.
+* Wraps `Agent.run` and `Agent.run_sync` as DBOS workflows.
+* Wraps [model requests](models/index.md) and [MCP communication](mcp/client.md) as DBOS steps.
 
-Here is a simple but complete example of wrapping an agent for durable execution. All it requires is to install the DBOS [open-source library](https://github.com/dbos-inc/dbos-transact-py):
+Custom tool functions are not wrapped automatically. You can decorate them with `@DBOS.workflow` or `@DBOS.step` as needed.
 
-```sh
-uv add pydantic-ai[dbos]
-```
+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):
 
-or if you use pip:
 ```sh
+uv add pydantic-ai[dbos]
+# or
 pip install pydantic-ai[dbos]
 ```
 
@@ -108,9 +91,9 @@ async def main():
     #> Mexico City (Ciudad de México, CDMX)
 ```
 
-1. The original `Agent` cannot be used inside a deterministic DBOS workflow, but the `DBOSAgent` can. Workflow function declarations and `DBOSAgent` creations need to happen before calling `DBOS.launch()` because DBOS requires all workflows to be registered before 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 inside a DBOS workflow and wraps model requests, decorated tool calls, and MCP communication as DBOS steps.
-3. This assumes DBOS is using SQLite. To deploy your agent to production, we recommend using a Postgres server.
+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`)_
@@ -121,34 +104,35 @@ For more information on how to use DBOS in Python applications, see their [Pytho
 
 ## DBOS Integration Considerations
 
-There are a few considerations specific to agents and toolsets when using DBOS for durable execution. These are important to understand to ensure that your agents and toolsets work correctly with DBOS's workflow and step model.
+When using DBOS with Pydantic AI agents, there are a few important considerations to ensure workflows and toolsets behave correctly.
 
 ### Agent and Toolset Requirements
 
-To ensure that DBOS knows what code to run when a workflow fails or is interrupted and then restarted, each agent instance needs to have a unique name.
+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
 
-As DBOS checkpoints workflow and step execution into a database, workflow inputs and outputs, and step outputs need to be serializable (JSON pickleable). You may also want to keep the inputs and outputs small (the maximum size for a single field in PostgreSQL is 1 GB, but usually you want to keep the output size under 2 MB).
+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 steps cannot stream output directly to the step call site, [`Agent.run_stream()`][pydantic_ai.Agent.run_stream] is not supported.
+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
 
-DBOS step configuration, like retry policies, can be customized by passing [`StepConfig`][pydantic_ai.durable_exec.dbos.StepConfig] objects to the `DBOSAgent` constructor:
+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.
 
-- `mcp_step_config`: The DBOS step config to use for MCP server communication. If no config is provided, it disables DBOS step retries.
-- `model_step_config`: The DBOS step config to use for model request steps. If no config is provided, it disables DBOS step retries.
+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.
 
-For individual tools, you can annotate them 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. Decorated steps are just normal functions if called outside of DBOS workflows, which can be used in non-DBOS agents.
 
 ## Step Retries
 
@@ -160,9 +144,9 @@ You can customize DBOS's retry policy using [step configuration](#step-configura
 
 ## Observability with Logfire
 
-DBOS generates OpenTelemetry traces and events for each workflow and step 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.
+DBOS emits OpenTelemetry traces and events for every workflow and step, 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 disable sending DBOS traces to Logfire, you can pass `disable_otlp=True` to the `DBOS` constructor. For example:
+To disable DBOS traces and logs, you can set `disable_otlp=True` in `DBOSConfig`. For example:
 
 
 ```python {title="dbos_no_traces.py" test="skip"}
@@ -176,4 +160,4 @@ dbos_config: DBOSConfig = {
 DBOS(config=dbos_config)
 ```
 
-1. If `True`, disables OpenTelemetry tracing and logging for DBOS. Defaults to `False`.
+1. If `True`, disables OpenTelemetry tracing and logging for DBOS. Default is `False`.