Skip to content

Commit 5d2651b

Browse files
kraftpqianl15
kraftp
and
qianl15
authored
Top-Level Agents Section (#536)
Co-authored-by: Qian Li <qian.li@dbos.dev>
1 parent 3003449 commit 5d2651b

26 files changed

+573
-181
lines changed

‎docs/ai/ai-quickstart.md‎

Lines changed: 344 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,344 @@
1+
---
2+
sidebar_position: 10
3+
title: AI Quickstart
4+
hide_table_of_contents: true
5+
---
6+
7+
You can integrate DBOS durable workflows with your AI agents (or other AI systems) to make them reliable, observable, and resilient to failures.
8+
Rather than bolting on ad-hoc retry logic, DBOS workflows give you one consistent model for ensuring your agents can recover from any failure from exactly where they left off.
9+
10+
In particular, integrating DBOS to your agents gives you:
11+
12+
- Resilience to failure: automatic recovery from server restarts, process crashes, network hiccups or outages, and other unexpected events.
13+
- [Reproducibility](./debugging.md): if your agents exhibit unexpected behavior, you can use saved workflow progress to reproduce it in a development environment to identify and fix the root cause.
14+
- [Support for long-running flows and reliable human-in-the-loop](./hitl.md): you can build agents that run for hours, days, or weeks (potentially waiting for human responses) and seamlessly recover from any interruption.
15+
- [Built in scalability and task distribution](./distributing-agents.md): if your agent or AI system needs to run many tasks in parallel (for example, a data pipeline processing many documents), you can use durable queues to distribute the work across many servers with managed flow control.
16+
17+
## Get Started
18+
19+
You can integrate DBOS into an agent built in regular Python or TypeScript, or use native integrations with popular agentic frameworks like [Pydantic AI](https://ai.pydantic.dev/durable_execution/dbos), [LlamaIndex](https://developers.llamaindex.ai/python/llamaagents/workflows/dbos/), and the [OpenAI Agents SDK](https://openai.github.io/openai-agents-python/running_agents/#dbos).
20+
21+
<LargeTabs groupId="language" queryString="language">
22+
<LargeTabItem value="python" label="Python">
23+
24+
### 1. Install DBOS
25+
`pip install` DBOS into your application.
26+
27+
```shell
28+
pip install dbos
29+
```
30+
31+
### 2. Configure and Launch DBOS
32+
33+
Add these lines of code to your agent's main function.
34+
They initialize DBOS when your agentic application starts.
35+
36+
```python
37+
import os
38+
from dbos import DBOS, DBOSConfig
39+
40+
config: DBOSConfig = {
41+
"name": "my-app",
42+
"system_database_url": os.environ.get("DBOS_SYSTEM_DATABASE_URL"),
43+
}
44+
DBOS(config=config)
45+
DBOS.launch()
46+
```
47+
48+
:::info
49+
DBOS uses a database to durably store workflow and step state.
50+
By default, it uses SQLite, which requires no configuration.
51+
For production use, we recommend connecting your DBOS application to a Postgres database.
52+
When you're ready for production, you can connect this initialization code to Postgres by setting the `DBOS_SYSTEM_DATABASE_URL` environment variable to a connection string to your Postgres database.
53+
:::
54+
55+
### 3. Annotate Workflows and Steps
56+
57+
Next, annotate your main agentic loop as a durable workflow and each LLM and tool call it makes as a step.
58+
This causes DBOS to checkpoint the progress of your agent in your database so it can recover from any failure.
59+
60+
For instance, in the [deep research agent example](../python/examples/hacker-news-agent.md), here is the main agentic loop:
61+
62+
```python
63+
@DBOS.workflow()
64+
def agentic_research_workflow(topic: str, max_iterations: int = 3):
65+
"""
66+
This agent starts with a research topic then:
67+
1. Searches Hacker News for information on that topic.
68+
2. Iteratively searches related topics, collecting information.
69+
3. Makes decisions about when to continue.
70+
4. Synthesizes findings into a final report.
71+
"""
72+
...
73+
```
74+
75+
And here is an example step, an LLM call to evaluate results:
76+
77+
```python
78+
@DBOS.step()
79+
def evaluate_results_step(
80+
topic: str,
81+
query: str,
82+
stories: List[Dict[str, Any]],
83+
comments: Optional[List[Dict[str, Any]]] = None,
84+
) -> EvaluationResult:
85+
"""LLM evaluates search results and extracts insights."""
86+
...
87+
```
88+
89+
To learn more about how to build with DBOS Python, check out the [Python docs](../python/programming-guide.md).
90+
91+
</LargeTabItem>
92+
<LargeTabItem value="typescript" label="TypeScript">
93+
94+
### 1. Install DBOS
95+
`npm install` DBOS into your application.
96+
97+
```shell
98+
npm install @dbos-inc/dbos-sdk@latest
99+
```
100+
101+
### 2. Configure and Launch DBOS
102+
103+
Add these lines of code to your agent's main function.
104+
They initialize DBOS when your agentic application starts.
105+
106+
```javascript
107+
import { DBOS } from "@dbos-inc/dbos-sdk";
108+
109+
DBOS.setConfig({
110+
"name": "my-app",
111+
"systemDatabaseUrl": process.env.DBOS_SYSTEM_DATABASE_URL,
112+
});
113+
await DBOS.launch();
114+
```
115+
116+
:::info
117+
DBOS uses a database to durably store workflow and step state.
118+
By default, it uses a Postgres database.
119+
You can start Postgres locally with `npx dbos postgres start`, or set the `DBOS_SYSTEM_DATABASE_URL` environment variable to a connection string to an existing Postgres database.
120+
:::
121+
122+
### 3. Register Workflows and Steps
123+
124+
Next, register your main agentic loop as a durable workflow and run each LLM and tool call as a step.
125+
This causes DBOS to checkpoint the progress of your agent in your database so it can recover from any failure.
126+
127+
For instance, in the [deep research agent example](../typescript/examples/hacker-news-agent.md), here is the main agentic loop, registered as a workflow:
128+
129+
```typescript
130+
async function agenticResearchWorkflowFunction(
131+
topic: string,
132+
maxIterations: number,
133+
): Promise<ResearchResult> {
134+
...
135+
}
136+
export const agenticResearchWorkflow = DBOS.registerWorkflow(
137+
agenticResearchWorkflowFunction,
138+
);
139+
```
140+
141+
And here is an example step, an LLM call to evaluate results:
142+
143+
```typescript
144+
const evaluation = await DBOS.runStep(
145+
() => evaluateResults(topic, query, stories, comments),
146+
{ name: "evaluateResults" },
147+
);
148+
```
149+
150+
To learn more about how to build with DBOS TypeScript, check out the [TypeScript docs](../typescript/programming-guide.md).
151+
152+
</LargeTabItem>
153+
<LargeTabItem value="pydantic" label="Pydantic AI">
154+
155+
### 1. Install Pydantic AI with DBOS
156+
157+
Install Pydantic AI with the DBOS optional dependency.
158+
159+
```shell
160+
pip install pydantic-ai[dbos]
161+
```
162+
163+
### 2. Configure DBOS and Wrap Your Agent
164+
165+
Import and configure DBOS, then wrap your Pydantic AI agent in a `DBOSAgent` for durable execution.
166+
`DBOSAgent` automatically wraps your agent's run loop as a DBOS workflow and model requests and MCP communication as DBOS steps.
167+
168+
```python
169+
import asyncio
170+
# highlight-next-line
171+
from dbos import DBOS, DBOSConfig
172+
173+
from pydantic_ai import Agent
174+
# highlight-next-line
175+
from pydantic_ai.durable_exec.dbos import DBOSAgent
176+
177+
# highlight-start
178+
dbos_config: DBOSConfig = {
179+
'name': 'pydantic_dbos_agent',
180+
'system_database_url': 'sqlite:///dbostest.sqlite',
181+
}
182+
DBOS(config=dbos_config)
183+
#highlight-end
184+
185+
agent = Agent(
186+
'gpt-5',
187+
instructions="You're an expert in geography.",
188+
name='geography',
189+
)
190+
191+
# highlight-next-line
192+
dbos_agent = DBOSAgent(agent)
193+
194+
async def main():
195+
# highlight-next-line
196+
DBOS.launch()
197+
result = await dbos_agent.run('What is the capital of Mexico?')
198+
print(result.output)
199+
200+
if __name__ == "__main__":
201+
asyncio.run(main())
202+
```
203+
204+
Custom tool functions can optionally be decorated with `@DBOS.step` if they involve non-determinism or I/O.
205+
206+
To learn more, check out the [Pydantic AI integration guide](../integrations/pydantic-ai.md) and the [Pydantic AI docs](https://ai.pydantic.dev/durable_execution/dbos).
207+
208+
</LargeTabItem>
209+
<LargeTabItem value="llamaindex" label="LlamaIndex">
210+
211+
### 1. Install LlamaIndex with DBOS
212+
213+
Install the [`llama-agents-dbos`](https://github.com/run-llama/workflows-py/tree/main/packages/llama-agents-dbos) package.
214+
215+
```shell
216+
pip install llama-agents-dbos
217+
```
218+
219+
### 2. Configure DBOS and Use the DBOS Runtime
220+
221+
Import and configure DBOS, then create a `DBOSRuntime` and pass it to your LlamaIndex workflow.
222+
The DBOS runtime automatically persists every workflow transition so your workflow can resume exactly where it left off after any failure.
223+
224+
```python
225+
import asyncio
226+
227+
# highlight-next-line
228+
from dbos import DBOS, DBOSConfig
229+
# highlight-next-line
230+
from llama_agents.dbos import DBOSRuntime
231+
from pydantic import Field
232+
from workflows import Context, Workflow, step
233+
from workflows.events import Event, StartEvent, StopEvent
234+
235+
# highlight-start
236+
config: DBOSConfig = {
237+
"name": "llamaindex-example",
238+
"system_database_url": "sqlite:///example.sqlite",
239+
}
240+
DBOS(config=config)
241+
# highlight-end
242+
243+
244+
class MyResult(StopEvent):
245+
output: str = Field(description="Result")
246+
247+
248+
class MyWorkflow(Workflow):
249+
@step
250+
async def start(self, ctx: Context, ev: StartEvent) -> MyResult:
251+
return MyResult(output="Hello from a durable workflow!")
252+
253+
254+
# highlight-next-line
255+
runtime = DBOSRuntime()
256+
workflow = MyWorkflow(runtime=runtime)
257+
258+
259+
async def main() -> None:
260+
# highlight-next-line
261+
await runtime.launch()
262+
result = await workflow.run(run_id="my-run-1")
263+
print(result.output)
264+
265+
266+
asyncio.run(main())
267+
```
268+
269+
To learn more, check out the [LlamaIndex integration guide](../integrations/llamaindex.md) and the [LlamaIndex docs](https://developers.llamaindex.ai/python/llamaagents/workflows/dbos/).
270+
271+
</LargeTabItem>
272+
<LargeTabItem value="openai" label="OpenAI Agents SDK">
273+
274+
### 1. Install DBOS and the OpenAI Agents Integration
275+
276+
Install DBOS and the [durable OpenAI agents integration](https://github.com/dbos-inc/dbos-openai-agents).
277+
278+
```shell
279+
pip install dbos dbos-openai-agents
280+
```
281+
282+
### 2. Configure DBOS and Wrap Your Agent
283+
284+
Use `DBOSRunner` as a drop-in replacement for `Runner` and annotate your agent's workflow and tool calls with DBOS decorators.
285+
286+
```python
287+
import asyncio
288+
from agents import Agent, function_tool
289+
# highlight-start
290+
from dbos import DBOS, DBOSConfig
291+
from dbos_openai_agents import DBOSRunner
292+
#highlight-end
293+
294+
@function_tool
295+
# highlight-next-line
296+
@DBOS.step()
297+
async def get_weather(city: str) -> str:
298+
"""Get the weather for a city."""
299+
return f"Sunny in {city}"
300+
301+
agent = Agent(name="weather", tools=[get_weather])
302+
303+
# highlight-start
304+
@DBOS.workflow()
305+
async def run_agent(user_input: str) -> str:
306+
result = await DBOSRunner.run(agent, user_input)
307+
return str(result.final_output)
308+
# highlight-end
309+
310+
311+
async def main():
312+
# highlight-start
313+
config: DBOSConfig = {
314+
"name": "my-agent",
315+
"system_database_url": 'sqlite:///my_agent.sqlite',
316+
}
317+
DBOS(config=config)
318+
DBOS.launch()
319+
# highlight-end
320+
output = await run_agent("How is the weather in San Francisco")
321+
print(output)
322+
323+
324+
if __name__ == "__main__":
325+
asyncio.run(main())
326+
```
327+
328+
To learn more, check out the [OpenAI Agents SDK integration guide](../integrations/openai-agents.md) and the [OpenAI Agents SDK documentation](https://openai.github.io/openai-agents-python/running_agents/#dbos).
329+
330+
</LargeTabItem>
331+
</LargeTabs>
332+
333+
## Using Coding Agents
334+
335+
DBOS provides skills and prompts to help you use coding agents to add DBOS to your AI applications.
336+
Learn more about them here:
337+
338+
- [AI-assisted development in Python](../python/prompting.md)
339+
- [AI-assisted development in TypeScript](../typescript/prompting.md)
340+
- [AI-assisted development in Go](../golang/prompting.md)
341+
- [AI-assisted development in Java](../java/prompting.md)
342+
343+
Additionally, DBOS provides an MCP server so your agents can observe and monitor your workflows and help you find and catch issues.
344+
Learn more about it [here](../integrations/mcp.md).

‎docs/ai/debugging.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
---
2+
sidebar_position: 20
3+
title: Reproducing & Debugging Agents
4+
hide_table_of_contents: false
5+
---
6+
7+
One of the most common problems you encounter building and operating agents is failures due to **unexpected agent behavior**.
8+
For example, an agent might:
9+
10+
- Return a malformed structured output, causing a tool call to fail.
11+
- Invoke the wrong tool or the right tool with the wrong inputs, causing the tool to fail.
12+
- Generate an undesirable or inappropriate text output, with potentially business-critical consequences.
13+
14+
These behaviors are especially hard to diagnose in a complex or long-running agent&mdash;if an agent runs for two hours then fails unexpectedly, it's difficult to reproduce the exact set of conditions that caused the failure and test a fix.
15+
16+
Durable workflows help by making it easier to observe the root cause of the failure, deterministically reproduce the failure, and test or apply fixes.
17+
Because workflows checkpoint the outcome of each step of your workflow, you can review these checkpoints to see the cause of the failure and audit every step that led to it.
18+
For example, using the [DBOS Console dashboard](../production/workflow-management.md), you might see that your agent failed because of a validation error caused by a malformed structured output:
19+
20+
<img src={require('@site/static/img/why-dbos-agents/agent-fail.png').default} alt="Failing Agent" width="750" className="custom-img"/>
21+
22+
Once you've identified the cause of a failure, you can use the [**workflow fork**](../python/tutorials/workflow-management.md#forking-workflows) operation to reproduce it.
23+
Fork restarts a workflow from a completed step, using checkpointed information to deterministically reproduce the state of the workflow up to that step.
24+
Thus, you can rerun the misbehaving step under the exact conditions that originally caused the misbehavior.
25+
26+
Once you can reproduce a failure in a development environment, it becomes much easier to fix.
27+
You can add additional logging or telemetry to the misbehaving step to identify the root cause.
28+
Then, when you have a fix, you can reproduce the failure with the fix in place to test if it works.
29+
For example, if you hypothesize that the malformed output was caused by an error in the prompt, you can fix the prompt, rerun the failed step, and watch it complete successfully:
30+
31+
<img src={require('@site/static/img/why-dbos-agents/agent-succeed.png').default} alt="Successful Agent" width="750" className="custom-img"/>

0 commit comments

Comments
 (0)