langgraph-dbos 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- langgraph_dbos-0.1.0/.gitignore +11 -0
- langgraph_dbos-0.1.0/CHANGELOG.md +20 -0
- langgraph_dbos-0.1.0/LICENSE +21 -0
- langgraph_dbos-0.1.0/PKG-INFO +327 -0
- langgraph_dbos-0.1.0/README.md +296 -0
- langgraph_dbos-0.1.0/docs/crash-demo.svg +19 -0
- langgraph_dbos-0.1.0/docs/design.md +123 -0
- langgraph_dbos-0.1.0/examples/crash_demo.py +167 -0
- langgraph_dbos-0.1.0/examples/human_approval.py +145 -0
- langgraph_dbos-0.1.0/examples/queue_many_agents.py +67 -0
- langgraph_dbos-0.1.0/pyproject.toml +80 -0
- langgraph_dbos-0.1.0/src/langgraph_dbos/__init__.py +42 -0
- langgraph_dbos-0.1.0/src/langgraph_dbos/_graph.py +645 -0
- langgraph_dbos-0.1.0/src/langgraph_dbos/_input.py +131 -0
- langgraph_dbos-0.1.0/src/langgraph_dbos/py.typed +0 -0
- langgraph_dbos-0.1.0/tests/__init__.py +0 -0
- langgraph_dbos-0.1.0/tests/conftest.py +99 -0
- langgraph_dbos-0.1.0/tests/crash_app.py +237 -0
- langgraph_dbos-0.1.0/tests/test_async.py +112 -0
- langgraph_dbos-0.1.0/tests/test_human_input.py +272 -0
- langgraph_dbos-0.1.0/tests/test_invoke.py +400 -0
- langgraph_dbos-0.1.0/tests/test_recovery.py +100 -0
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## 0.1.0
|
|
4
|
+
|
|
5
|
+
First release.
|
|
6
|
+
|
|
7
|
+
- `DBOSGraph.invoke` / `ainvoke`: run any compiled LangGraph graph inside a DBOS
|
|
8
|
+
workflow. After a crash the run resumes from the latest checkpoint; finished
|
|
9
|
+
nodes are not run again.
|
|
10
|
+
- Durable human-in-the-loop for `interrupt()`: `get_pending_input` and
|
|
11
|
+
`send_input` (sync and async, in-process or through `DBOSClient`), with a
|
|
12
|
+
per-question token and idempotent replies.
|
|
13
|
+
- `stream_mode=` writes graph stream chunks to a DBOS stream; `close_stream=`
|
|
14
|
+
keeps it open across calls.
|
|
15
|
+
- `step_options=` retries a failed segment from the latest checkpoint.
|
|
16
|
+
- A resume value saved by a crashed attempt is never reused for a later
|
|
17
|
+
question (checked with crash tests for two interrupts in one node and in a
|
|
18
|
+
subgraph).
|
|
19
|
+
- Clear errors for lost checkpoints, forks into a running graph, and calls
|
|
20
|
+
outside a workflow.
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Lakshit Mathur
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,327 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: langgraph-dbos
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Durable LangGraph agents on DBOS: crash recovery, durable human-in-the-loop and streaming on your own Postgres
|
|
5
|
+
Project-URL: Homepage, https://github.com/lllakshit/langgraph-dbos
|
|
6
|
+
Project-URL: Repository, https://github.com/lllakshit/langgraph-dbos
|
|
7
|
+
Project-URL: Issues, https://github.com/lllakshit/langgraph-dbos/issues
|
|
8
|
+
Project-URL: Changelog, https://github.com/lllakshit/langgraph-dbos/blob/main/CHANGELOG.md
|
|
9
|
+
Author: Lakshit Mathur
|
|
10
|
+
License-Expression: MIT
|
|
11
|
+
License-File: LICENSE
|
|
12
|
+
Keywords: agents,dbos,durable-execution,human-in-the-loop,langgraph,postgres,workflows
|
|
13
|
+
Classifier: Development Status :: 3 - Alpha
|
|
14
|
+
Classifier: Intended Audience :: Developers
|
|
15
|
+
Classifier: Programming Language :: Python :: 3
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
20
|
+
Classifier: Topic :: Software Development :: Libraries
|
|
21
|
+
Classifier: Typing :: Typed
|
|
22
|
+
Requires-Python: >=3.10
|
|
23
|
+
Requires-Dist: dbos<4,>=3.0
|
|
24
|
+
Requires-Dist: langgraph<2,>=1.0
|
|
25
|
+
Provides-Extra: postgres
|
|
26
|
+
Requires-Dist: langgraph-checkpoint-postgres>=3.0; extra == 'postgres'
|
|
27
|
+
Requires-Dist: psycopg[binary]>=3.2; extra == 'postgres'
|
|
28
|
+
Provides-Extra: sqlite
|
|
29
|
+
Requires-Dist: langgraph-checkpoint-sqlite>=3.0; extra == 'sqlite'
|
|
30
|
+
Description-Content-Type: text/markdown
|
|
31
|
+
|
|
32
|
+
# langgraph-dbos
|
|
33
|
+
|
|
34
|
+
[](https://github.com/lllakshit/langgraph-dbos/actions/workflows/ci.yml)
|
|
35
|
+
[](LICENSE)
|
|
36
|
+
|
|
37
|
+
**Durable LangGraph agents on your own Postgres.** Wrap any compiled LangGraph
|
|
38
|
+
graph, call it from a [DBOS](https://github.com/dbos-inc/dbos-transact-py)
|
|
39
|
+
workflow, and it survives crashes, restarts and deploys:
|
|
40
|
+
|
|
41
|
+
- **Crash recovery that resumes, not restarts.** Kill the process mid-run; on
|
|
42
|
+
restart DBOS finds the unfinished run and continues from the node that was
|
|
43
|
+
running. Nodes that already finished, and the LLM calls inside them, are not
|
|
44
|
+
run or paid for again.
|
|
45
|
+
- **Human-in-the-loop that waits for days.** A node calls LangGraph's
|
|
46
|
+
`interrupt()`; the workflow waits in the database, not in memory, across any
|
|
47
|
+
number of restarts. Answer from a web handler or another service. Late,
|
|
48
|
+
stale or double-clicked answers are never applied to the wrong question.
|
|
49
|
+
- **Queues and rate limits for agents.** Run many graph runs through a DBOS
|
|
50
|
+
queue with concurrency and per-second limits to stay under LLM API quotas.
|
|
51
|
+
- **Retries that resume.** A segment that fails with a transient error is
|
|
52
|
+
retried from the latest checkpoint, so only the failed node runs again.
|
|
53
|
+
- **Streaming that outlives the request.** Stream graph events into a DBOS
|
|
54
|
+
stream and read them from any process, while the run is going or after.
|
|
55
|
+
- **No rewrite.** Your graph stays a normal LangGraph graph: `StateGraph`, the
|
|
56
|
+
Functional API, subgraphs, `Send`, reducers, callbacks. No nodes to
|
|
57
|
+
re-register.
|
|
58
|
+
|
|
59
|
+
No extra server to run: DBOS is a library, and its state lives in the same
|
|
60
|
+
Postgres (or SQLite) database as your LangGraph checkpoints.
|
|
61
|
+
|
|
62
|
+

|
|
63
|
+
|
|
64
|
+
## Install
|
|
65
|
+
|
|
66
|
+
```bash
|
|
67
|
+
pip install "langgraph-dbos[postgres]" # PostgresSaver + psycopg
|
|
68
|
+
pip install "langgraph-dbos[sqlite]" # SqliteSaver, for local development
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
Needs Python 3.10+, `dbos>=3.0` and `langgraph>=1.0`.
|
|
72
|
+
|
|
73
|
+
## Quickstart
|
|
74
|
+
|
|
75
|
+
```python
|
|
76
|
+
import psycopg
|
|
77
|
+
from dbos import DBOS
|
|
78
|
+
from langgraph.checkpoint.postgres import PostgresSaver
|
|
79
|
+
from langgraph.graph import START, StateGraph
|
|
80
|
+
from psycopg.rows import dict_row
|
|
81
|
+
from typing_extensions import TypedDict
|
|
82
|
+
|
|
83
|
+
from langgraph_dbos import DBOSGraph
|
|
84
|
+
|
|
85
|
+
DATABASE_URL = "postgresql://postgres:dbos@localhost:5433/langgraph_dbos"
|
|
86
|
+
|
|
87
|
+
|
|
88
|
+
class State(TypedDict, total=False):
|
|
89
|
+
question: str
|
|
90
|
+
research: str
|
|
91
|
+
answer: str
|
|
92
|
+
|
|
93
|
+
|
|
94
|
+
def research(state: State) -> State:
|
|
95
|
+
return {"research": f"notes about {state['question']}"} # an LLM call
|
|
96
|
+
|
|
97
|
+
|
|
98
|
+
def write(state: State) -> State:
|
|
99
|
+
return {"answer": f"answer from {state['research']}"} # another LLM call
|
|
100
|
+
|
|
101
|
+
|
|
102
|
+
builder = StateGraph(State)
|
|
103
|
+
builder.add_node("research", research)
|
|
104
|
+
builder.add_node("write", write)
|
|
105
|
+
builder.add_edge(START, "research")
|
|
106
|
+
builder.add_edge("research", "write")
|
|
107
|
+
|
|
108
|
+
conn = psycopg.connect(DATABASE_URL, autocommit=True, prepare_threshold=0, row_factory=dict_row)
|
|
109
|
+
checkpointer = PostgresSaver(conn)
|
|
110
|
+
checkpointer.setup()
|
|
111
|
+
|
|
112
|
+
agent = DBOSGraph(builder.compile(checkpointer=checkpointer))
|
|
113
|
+
|
|
114
|
+
DBOS(config={"name": "research-agent", "system_database_url": DATABASE_URL})
|
|
115
|
+
|
|
116
|
+
|
|
117
|
+
@DBOS.workflow()
|
|
118
|
+
def answer_question(question: str) -> str:
|
|
119
|
+
return agent.invoke({"question": question})["answer"]
|
|
120
|
+
|
|
121
|
+
|
|
122
|
+
if __name__ == "__main__":
|
|
123
|
+
DBOS.launch() # also recovers runs that a crash left unfinished
|
|
124
|
+
print(answer_question("What is durable execution?"))
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
`DBOSGraph.invoke` takes the same input and config as `graph.invoke` and
|
|
128
|
+
returns the same output. It must be called from a `@DBOS.workflow()`. From an
|
|
129
|
+
`async` workflow, use `await agent.ainvoke(...)` with an async checkpointer
|
|
130
|
+
such as `AsyncPostgresSaver`.
|
|
131
|
+
|
|
132
|
+
Start a local Postgres with `docker compose up -d` ([compose.yaml](compose.yaml)) or:
|
|
133
|
+
|
|
134
|
+
```bash
|
|
135
|
+
docker run -d --name langgraph-dbos-pg -e POSTGRES_PASSWORD=dbos -e POSTGRES_DB=langgraph_dbos -p 5433:5432 postgres:17
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
## See it survive a crash
|
|
139
|
+
|
|
140
|
+
```bash
|
|
141
|
+
python examples/crash_demo.py # 5 "LLM" nodes; the process is killed with SIGKILL during "write"
|
|
142
|
+
python examples/crash_demo.py # restart: resumes at "write", the first 3 nodes are not called again
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
## Human-in-the-loop
|
|
146
|
+
|
|
147
|
+
Use LangGraph's own `interrupt()` in a node. `invoke` waits durably for the
|
|
148
|
+
answer and then continues the graph:
|
|
149
|
+
|
|
150
|
+
```python
|
|
151
|
+
from langgraph.types import interrupt
|
|
152
|
+
|
|
153
|
+
|
|
154
|
+
def approve(state: State) -> State:
|
|
155
|
+
decision = interrupt({"draft": state["draft"], "ask": "Send this reply?"})
|
|
156
|
+
return {"decision": decision}
|
|
157
|
+
|
|
158
|
+
|
|
159
|
+
@DBOS.workflow()
|
|
160
|
+
def reply_to_ticket(question: str) -> State:
|
|
161
|
+
return agent.invoke({"question": question})
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
From anywhere else (a FastAPI route, a Slack handler, a CLI):
|
|
165
|
+
|
|
166
|
+
```python
|
|
167
|
+
from dbos import DBOSClient
|
|
168
|
+
from langgraph_dbos import get_pending_input, send_input
|
|
169
|
+
|
|
170
|
+
client = DBOSClient(system_database_url=DATABASE_URL) # or leave out client= inside a DBOS app
|
|
171
|
+
|
|
172
|
+
pending = get_pending_input(workflow_id, client=client)
|
|
173
|
+
# {"token": "...", "thread_id": "...", "interrupts": [{"id": "...", "value": {"draft": ..., "ask": ...}}]}
|
|
174
|
+
|
|
175
|
+
send_input(workflow_id, "ship it", token=pending["token"], client=client)
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
- The answer becomes the return value of `interrupt()`, exactly as with
|
|
179
|
+
`Command(resume=...)`.
|
|
180
|
+
- Pass the `token` you showed the human. A reply with an old token is ignored,
|
|
181
|
+
and a second reply with the same token is not delivered (DBOS idempotency).
|
|
182
|
+
- Several nodes interrupted at once: send a dict that maps each interrupt `id`
|
|
183
|
+
to its answer.
|
|
184
|
+
- `invoke(..., input_timeout=3600)` stops waiting after an hour and returns the
|
|
185
|
+
interrupted output (with `"__interrupt__"`). `wait_for_input=False` returns
|
|
186
|
+
at the first interrupt.
|
|
187
|
+
|
|
188
|
+
Try it: [examples/human_approval.py](examples/human_approval.py). Kill the
|
|
189
|
+
worker while it waits, start it again, then answer from another terminal.
|
|
190
|
+
|
|
191
|
+
## Many agents, with limits
|
|
192
|
+
|
|
193
|
+
```python
|
|
194
|
+
@DBOS.workflow()
|
|
195
|
+
def weather(city: str) -> str:
|
|
196
|
+
return agent.invoke({"city": city})["summary"]
|
|
197
|
+
|
|
198
|
+
|
|
199
|
+
DBOS.launch()
|
|
200
|
+
agents = DBOS.register_queue("agents", global_concurrency=3, limiter={"limit": 10, "period": 1})
|
|
201
|
+
handles = [agents.enqueue(weather, city) for city in cities]
|
|
202
|
+
```
|
|
203
|
+
|
|
204
|
+
See [examples/queue_many_agents.py](examples/queue_many_agents.py).
|
|
205
|
+
|
|
206
|
+
## Streaming
|
|
207
|
+
|
|
208
|
+
```python
|
|
209
|
+
@DBOS.workflow()
|
|
210
|
+
def run(question: str) -> State:
|
|
211
|
+
return agent.invoke({"question": question}, stream_mode=["updates", "custom"])
|
|
212
|
+
|
|
213
|
+
|
|
214
|
+
for mode, chunk in DBOS.read_stream(workflow_id, "langgraph.stream"):
|
|
215
|
+
...
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
Chunks have the same shape as `graph.stream(...)` with the same `stream_mode`.
|
|
219
|
+
Change the key with `stream_key=`, and use a different key for each
|
|
220
|
+
streaming `invoke` in one workflow (or pass `close_stream=False` to keep
|
|
221
|
+
writing to one stream). The stream is closed when `invoke` returns, so
|
|
222
|
+
readers stop. Delivery is at-least-once: after a crash or retry, chunks from
|
|
223
|
+
the node that was running are written again.
|
|
224
|
+
|
|
225
|
+
## Retries
|
|
226
|
+
|
|
227
|
+
```python
|
|
228
|
+
agent = DBOSGraph(
|
|
229
|
+
graph, step_options={"retries_allowed": True, "max_attempts": 5, "backoff_rate": 2}
|
|
230
|
+
)
|
|
231
|
+
```
|
|
232
|
+
|
|
233
|
+
Each retry resumes from the latest checkpoint, so nodes that finished before
|
|
234
|
+
the failure are not run again.
|
|
235
|
+
|
|
236
|
+
## How it works
|
|
237
|
+
|
|
238
|
+
```
|
|
239
|
+
@DBOS.workflow
|
|
240
|
+
├─ step <name>.start records the thread id and the checkpoint the run starts from
|
|
241
|
+
├─ step <name>.run graph.invoke(...) until it finishes or hits interrupt()
|
|
242
|
+
├─ set_event "waiting for input" + token
|
|
243
|
+
├─ recv the human's reply (durable wait)
|
|
244
|
+
├─ step <name>.run graph.invoke(Command(resume=reply))
|
|
245
|
+
└─ ...
|
|
246
|
+
```
|
|
247
|
+
|
|
248
|
+
- A run is split into **segments**: one `graph.invoke` until the graph ends or
|
|
249
|
+
interrupts. Each segment is one DBOS step, so the workflow's recorded history
|
|
250
|
+
is the same on every replay.
|
|
251
|
+
- **Inside** a segment, LangGraph's checkpointer saves every super-step
|
|
252
|
+
(`durability="sync"` by default).
|
|
253
|
+
- If the process dies mid-segment, DBOS reruns that step on recovery. The step
|
|
254
|
+
compares the thread's latest checkpoint and its pending writes with what was
|
|
255
|
+
recorded when the segment began. Unchanged: it applies the input. Changed: a
|
|
256
|
+
previous attempt made progress, so it resumes with `invoke(None)`, never
|
|
257
|
+
applying the input twice and never letting a saved answer reach a later
|
|
258
|
+
question.
|
|
259
|
+
- `@DBOS.step()` functions called inside nodes run inline as part of the
|
|
260
|
+
segment, so existing DBOS tools can be reused in nodes.
|
|
261
|
+
|
|
262
|
+
More detail, and the designs that were rejected: [docs/design.md](docs/design.md).
|
|
263
|
+
|
|
264
|
+
## Guarantees and limits
|
|
265
|
+
|
|
266
|
+
- **A node that was running when the process died runs again.** Finished nodes
|
|
267
|
+
do not. Make side effects in nodes idempotent (an idempotency key on the
|
|
268
|
+
payment, upsert instead of insert), as with any at-least-once system.
|
|
269
|
+
- **Use a persistent checkpointer.** With `InMemorySaver`, a recovered run
|
|
270
|
+
cannot resume and raises `CheckpointLostError` (you get a warning when you
|
|
271
|
+
create the `DBOSGraph`).
|
|
272
|
+
- **An answer is never applied to a question it was not given for.** In one
|
|
273
|
+
narrow crash window (after LangGraph saved the answer, before the node read
|
|
274
|
+
it) the question is asked again instead of guessing; the human answers
|
|
275
|
+
twice, but no answer lands on the wrong question.
|
|
276
|
+
- **Graph output and interrupt values must be serializable by DBOS** (pickle by
|
|
277
|
+
default), because DBOS records each segment's output. LangChain messages
|
|
278
|
+
are. This package's own records are plain dicts.
|
|
279
|
+
- **Only this run writes to its thread.** Two workflows on the same
|
|
280
|
+
`thread_id` at once are not supported (with a queue, partition by thread).
|
|
281
|
+
Do not call `graph.update_state(...)` on a thread while its workflow waits
|
|
282
|
+
for input: the next reply is then treated as stale and the question is
|
|
283
|
+
asked again. Put edits in the reply instead.
|
|
284
|
+
- **Call `invoke`/`ainvoke` one after another in a workflow**, not with
|
|
285
|
+
`asyncio.gather`. For parallel graph runs, start child workflows.
|
|
286
|
+
- **Use `interrupt()`, not static `interrupt_before`/`interrupt_after`
|
|
287
|
+
breakpoints.** After a crash, a run paused at a static breakpoint could
|
|
288
|
+
continue past it.
|
|
289
|
+
- **Forking** (`DBOS.fork_workflow`) works from the `<name>.start` step or
|
|
290
|
+
earlier: the fork gets its own fresh graph run. Forking into the middle of a
|
|
291
|
+
run raises `ForkNotSupportedError` instead of sharing the original's thread.
|
|
292
|
+
- **Python 3.10 and async nodes:** LangGraph's `interrupt()` does not work in
|
|
293
|
+
`async` nodes on Python 3.10 (a LangGraph limitation). Sync nodes are fine.
|
|
294
|
+
- **Code changes:** as with any DBOS workflow, a pending run must be recovered
|
|
295
|
+
by compatible code. Keep `DBOSGraph(name=...)` stable.
|
|
296
|
+
|
|
297
|
+
## Compared with
|
|
298
|
+
|
|
299
|
+
| | Checkpointer only | langgraph-dbos |
|
|
300
|
+
|---|---|---|
|
|
301
|
+
| State saved after each super-step | yes | yes (same checkpointer) |
|
|
302
|
+
| Unfinished runs restarted after a crash | no: you find and re-invoke them | yes, on `DBOS.launch()` |
|
|
303
|
+
| Waiting for a human across restarts | thread stays paused; you build the resume plumbing | built in, with stale and duplicate protection |
|
|
304
|
+
| Queues, concurrency and rate limits | no | DBOS queues |
|
|
305
|
+
| Run history, cancel, resume, fork | no | DBOS workflow management |
|
|
306
|
+
|
|
307
|
+
[`SamuelXing/dbos-langgraph`](https://github.com/SamuelXing/dbos-langgraph)
|
|
308
|
+
takes a different route: it runs each node as its own DBOS child workflow with
|
|
309
|
+
no LangGraph checkpointer, and nodes are registered through its plugin. This
|
|
310
|
+
package keeps LangGraph's checkpointer and runs your compiled graph as it is,
|
|
311
|
+
which is what lets `interrupt()`, subgraphs and streaming work unchanged.
|
|
312
|
+
|
|
313
|
+
## Development
|
|
314
|
+
|
|
315
|
+
```bash
|
|
316
|
+
uv sync
|
|
317
|
+
uv run pytest # SQLite
|
|
318
|
+
LANGGRAPH_DBOS_TEST_POSTGRES=postgresql://postgres:dbos@localhost:5433/langgraph_dbos uv run pytest
|
|
319
|
+
uv run ruff check . && uv run mypy
|
|
320
|
+
```
|
|
321
|
+
|
|
322
|
+
The recovery tests start a real process, kill it with `SIGKILL` in the middle
|
|
323
|
+
of a run, restart it, and count how many times each node body ran.
|
|
324
|
+
|
|
325
|
+
## License
|
|
326
|
+
|
|
327
|
+
MIT
|
|
@@ -0,0 +1,296 @@
|
|
|
1
|
+
# langgraph-dbos
|
|
2
|
+
|
|
3
|
+
[](https://github.com/lllakshit/langgraph-dbos/actions/workflows/ci.yml)
|
|
4
|
+
[](LICENSE)
|
|
5
|
+
|
|
6
|
+
**Durable LangGraph agents on your own Postgres.** Wrap any compiled LangGraph
|
|
7
|
+
graph, call it from a [DBOS](https://github.com/dbos-inc/dbos-transact-py)
|
|
8
|
+
workflow, and it survives crashes, restarts and deploys:
|
|
9
|
+
|
|
10
|
+
- **Crash recovery that resumes, not restarts.** Kill the process mid-run; on
|
|
11
|
+
restart DBOS finds the unfinished run and continues from the node that was
|
|
12
|
+
running. Nodes that already finished, and the LLM calls inside them, are not
|
|
13
|
+
run or paid for again.
|
|
14
|
+
- **Human-in-the-loop that waits for days.** A node calls LangGraph's
|
|
15
|
+
`interrupt()`; the workflow waits in the database, not in memory, across any
|
|
16
|
+
number of restarts. Answer from a web handler or another service. Late,
|
|
17
|
+
stale or double-clicked answers are never applied to the wrong question.
|
|
18
|
+
- **Queues and rate limits for agents.** Run many graph runs through a DBOS
|
|
19
|
+
queue with concurrency and per-second limits to stay under LLM API quotas.
|
|
20
|
+
- **Retries that resume.** A segment that fails with a transient error is
|
|
21
|
+
retried from the latest checkpoint, so only the failed node runs again.
|
|
22
|
+
- **Streaming that outlives the request.** Stream graph events into a DBOS
|
|
23
|
+
stream and read them from any process, while the run is going or after.
|
|
24
|
+
- **No rewrite.** Your graph stays a normal LangGraph graph: `StateGraph`, the
|
|
25
|
+
Functional API, subgraphs, `Send`, reducers, callbacks. No nodes to
|
|
26
|
+
re-register.
|
|
27
|
+
|
|
28
|
+
No extra server to run: DBOS is a library, and its state lives in the same
|
|
29
|
+
Postgres (or SQLite) database as your LangGraph checkpoints.
|
|
30
|
+
|
|
31
|
+

|
|
32
|
+
|
|
33
|
+
## Install
|
|
34
|
+
|
|
35
|
+
```bash
|
|
36
|
+
pip install "langgraph-dbos[postgres]" # PostgresSaver + psycopg
|
|
37
|
+
pip install "langgraph-dbos[sqlite]" # SqliteSaver, for local development
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
Needs Python 3.10+, `dbos>=3.0` and `langgraph>=1.0`.
|
|
41
|
+
|
|
42
|
+
## Quickstart
|
|
43
|
+
|
|
44
|
+
```python
|
|
45
|
+
import psycopg
|
|
46
|
+
from dbos import DBOS
|
|
47
|
+
from langgraph.checkpoint.postgres import PostgresSaver
|
|
48
|
+
from langgraph.graph import START, StateGraph
|
|
49
|
+
from psycopg.rows import dict_row
|
|
50
|
+
from typing_extensions import TypedDict
|
|
51
|
+
|
|
52
|
+
from langgraph_dbos import DBOSGraph
|
|
53
|
+
|
|
54
|
+
DATABASE_URL = "postgresql://postgres:dbos@localhost:5433/langgraph_dbos"
|
|
55
|
+
|
|
56
|
+
|
|
57
|
+
class State(TypedDict, total=False):
|
|
58
|
+
question: str
|
|
59
|
+
research: str
|
|
60
|
+
answer: str
|
|
61
|
+
|
|
62
|
+
|
|
63
|
+
def research(state: State) -> State:
|
|
64
|
+
return {"research": f"notes about {state['question']}"} # an LLM call
|
|
65
|
+
|
|
66
|
+
|
|
67
|
+
def write(state: State) -> State:
|
|
68
|
+
return {"answer": f"answer from {state['research']}"} # another LLM call
|
|
69
|
+
|
|
70
|
+
|
|
71
|
+
builder = StateGraph(State)
|
|
72
|
+
builder.add_node("research", research)
|
|
73
|
+
builder.add_node("write", write)
|
|
74
|
+
builder.add_edge(START, "research")
|
|
75
|
+
builder.add_edge("research", "write")
|
|
76
|
+
|
|
77
|
+
conn = psycopg.connect(DATABASE_URL, autocommit=True, prepare_threshold=0, row_factory=dict_row)
|
|
78
|
+
checkpointer = PostgresSaver(conn)
|
|
79
|
+
checkpointer.setup()
|
|
80
|
+
|
|
81
|
+
agent = DBOSGraph(builder.compile(checkpointer=checkpointer))
|
|
82
|
+
|
|
83
|
+
DBOS(config={"name": "research-agent", "system_database_url": DATABASE_URL})
|
|
84
|
+
|
|
85
|
+
|
|
86
|
+
@DBOS.workflow()
|
|
87
|
+
def answer_question(question: str) -> str:
|
|
88
|
+
return agent.invoke({"question": question})["answer"]
|
|
89
|
+
|
|
90
|
+
|
|
91
|
+
if __name__ == "__main__":
|
|
92
|
+
DBOS.launch() # also recovers runs that a crash left unfinished
|
|
93
|
+
print(answer_question("What is durable execution?"))
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
`DBOSGraph.invoke` takes the same input and config as `graph.invoke` and
|
|
97
|
+
returns the same output. It must be called from a `@DBOS.workflow()`. From an
|
|
98
|
+
`async` workflow, use `await agent.ainvoke(...)` with an async checkpointer
|
|
99
|
+
such as `AsyncPostgresSaver`.
|
|
100
|
+
|
|
101
|
+
Start a local Postgres with `docker compose up -d` ([compose.yaml](compose.yaml)) or:
|
|
102
|
+
|
|
103
|
+
```bash
|
|
104
|
+
docker run -d --name langgraph-dbos-pg -e POSTGRES_PASSWORD=dbos -e POSTGRES_DB=langgraph_dbos -p 5433:5432 postgres:17
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
## See it survive a crash
|
|
108
|
+
|
|
109
|
+
```bash
|
|
110
|
+
python examples/crash_demo.py # 5 "LLM" nodes; the process is killed with SIGKILL during "write"
|
|
111
|
+
python examples/crash_demo.py # restart: resumes at "write", the first 3 nodes are not called again
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
## Human-in-the-loop
|
|
115
|
+
|
|
116
|
+
Use LangGraph's own `interrupt()` in a node. `invoke` waits durably for the
|
|
117
|
+
answer and then continues the graph:
|
|
118
|
+
|
|
119
|
+
```python
|
|
120
|
+
from langgraph.types import interrupt
|
|
121
|
+
|
|
122
|
+
|
|
123
|
+
def approve(state: State) -> State:
|
|
124
|
+
decision = interrupt({"draft": state["draft"], "ask": "Send this reply?"})
|
|
125
|
+
return {"decision": decision}
|
|
126
|
+
|
|
127
|
+
|
|
128
|
+
@DBOS.workflow()
|
|
129
|
+
def reply_to_ticket(question: str) -> State:
|
|
130
|
+
return agent.invoke({"question": question})
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
From anywhere else (a FastAPI route, a Slack handler, a CLI):
|
|
134
|
+
|
|
135
|
+
```python
|
|
136
|
+
from dbos import DBOSClient
|
|
137
|
+
from langgraph_dbos import get_pending_input, send_input
|
|
138
|
+
|
|
139
|
+
client = DBOSClient(system_database_url=DATABASE_URL) # or leave out client= inside a DBOS app
|
|
140
|
+
|
|
141
|
+
pending = get_pending_input(workflow_id, client=client)
|
|
142
|
+
# {"token": "...", "thread_id": "...", "interrupts": [{"id": "...", "value": {"draft": ..., "ask": ...}}]}
|
|
143
|
+
|
|
144
|
+
send_input(workflow_id, "ship it", token=pending["token"], client=client)
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
- The answer becomes the return value of `interrupt()`, exactly as with
|
|
148
|
+
`Command(resume=...)`.
|
|
149
|
+
- Pass the `token` you showed the human. A reply with an old token is ignored,
|
|
150
|
+
and a second reply with the same token is not delivered (DBOS idempotency).
|
|
151
|
+
- Several nodes interrupted at once: send a dict that maps each interrupt `id`
|
|
152
|
+
to its answer.
|
|
153
|
+
- `invoke(..., input_timeout=3600)` stops waiting after an hour and returns the
|
|
154
|
+
interrupted output (with `"__interrupt__"`). `wait_for_input=False` returns
|
|
155
|
+
at the first interrupt.
|
|
156
|
+
|
|
157
|
+
Try it: [examples/human_approval.py](examples/human_approval.py). Kill the
|
|
158
|
+
worker while it waits, start it again, then answer from another terminal.
|
|
159
|
+
|
|
160
|
+
## Many agents, with limits
|
|
161
|
+
|
|
162
|
+
```python
|
|
163
|
+
@DBOS.workflow()
|
|
164
|
+
def weather(city: str) -> str:
|
|
165
|
+
return agent.invoke({"city": city})["summary"]
|
|
166
|
+
|
|
167
|
+
|
|
168
|
+
DBOS.launch()
|
|
169
|
+
agents = DBOS.register_queue("agents", global_concurrency=3, limiter={"limit": 10, "period": 1})
|
|
170
|
+
handles = [agents.enqueue(weather, city) for city in cities]
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
See [examples/queue_many_agents.py](examples/queue_many_agents.py).
|
|
174
|
+
|
|
175
|
+
## Streaming
|
|
176
|
+
|
|
177
|
+
```python
|
|
178
|
+
@DBOS.workflow()
|
|
179
|
+
def run(question: str) -> State:
|
|
180
|
+
return agent.invoke({"question": question}, stream_mode=["updates", "custom"])
|
|
181
|
+
|
|
182
|
+
|
|
183
|
+
for mode, chunk in DBOS.read_stream(workflow_id, "langgraph.stream"):
|
|
184
|
+
...
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
Chunks have the same shape as `graph.stream(...)` with the same `stream_mode`.
|
|
188
|
+
Change the key with `stream_key=`, and use a different key for each
|
|
189
|
+
streaming `invoke` in one workflow (or pass `close_stream=False` to keep
|
|
190
|
+
writing to one stream). The stream is closed when `invoke` returns, so
|
|
191
|
+
readers stop. Delivery is at-least-once: after a crash or retry, chunks from
|
|
192
|
+
the node that was running are written again.
|
|
193
|
+
|
|
194
|
+
## Retries
|
|
195
|
+
|
|
196
|
+
```python
|
|
197
|
+
agent = DBOSGraph(
|
|
198
|
+
graph, step_options={"retries_allowed": True, "max_attempts": 5, "backoff_rate": 2}
|
|
199
|
+
)
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
Each retry resumes from the latest checkpoint, so nodes that finished before
|
|
203
|
+
the failure are not run again.
|
|
204
|
+
|
|
205
|
+
## How it works
|
|
206
|
+
|
|
207
|
+
```
|
|
208
|
+
@DBOS.workflow
|
|
209
|
+
├─ step <name>.start records the thread id and the checkpoint the run starts from
|
|
210
|
+
├─ step <name>.run graph.invoke(...) until it finishes or hits interrupt()
|
|
211
|
+
├─ set_event "waiting for input" + token
|
|
212
|
+
├─ recv the human's reply (durable wait)
|
|
213
|
+
├─ step <name>.run graph.invoke(Command(resume=reply))
|
|
214
|
+
└─ ...
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
- A run is split into **segments**: one `graph.invoke` until the graph ends or
|
|
218
|
+
interrupts. Each segment is one DBOS step, so the workflow's recorded history
|
|
219
|
+
is the same on every replay.
|
|
220
|
+
- **Inside** a segment, LangGraph's checkpointer saves every super-step
|
|
221
|
+
(`durability="sync"` by default).
|
|
222
|
+
- If the process dies mid-segment, DBOS reruns that step on recovery. The step
|
|
223
|
+
compares the thread's latest checkpoint and its pending writes with what was
|
|
224
|
+
recorded when the segment began. Unchanged: it applies the input. Changed: a
|
|
225
|
+
previous attempt made progress, so it resumes with `invoke(None)`, never
|
|
226
|
+
applying the input twice and never letting a saved answer reach a later
|
|
227
|
+
question.
|
|
228
|
+
- `@DBOS.step()` functions called inside nodes run inline as part of the
|
|
229
|
+
segment, so existing DBOS tools can be reused in nodes.
|
|
230
|
+
|
|
231
|
+
More detail, and the designs that were rejected: [docs/design.md](docs/design.md).
|
|
232
|
+
|
|
233
|
+
## Guarantees and limits
|
|
234
|
+
|
|
235
|
+
- **A node that was running when the process died runs again.** Finished nodes
|
|
236
|
+
do not. Make side effects in nodes idempotent (an idempotency key on the
|
|
237
|
+
payment, upsert instead of insert), as with any at-least-once system.
|
|
238
|
+
- **Use a persistent checkpointer.** With `InMemorySaver`, a recovered run
|
|
239
|
+
cannot resume and raises `CheckpointLostError` (you get a warning when you
|
|
240
|
+
create the `DBOSGraph`).
|
|
241
|
+
- **An answer is never applied to a question it was not given for.** In one
|
|
242
|
+
narrow crash window (after LangGraph saved the answer, before the node read
|
|
243
|
+
it) the question is asked again instead of guessing; the human answers
|
|
244
|
+
twice, but no answer lands on the wrong question.
|
|
245
|
+
- **Graph output and interrupt values must be serializable by DBOS** (pickle by
|
|
246
|
+
default), because DBOS records each segment's output. LangChain messages
|
|
247
|
+
are. This package's own records are plain dicts.
|
|
248
|
+
- **Only this run writes to its thread.** Two workflows on the same
|
|
249
|
+
`thread_id` at once are not supported (with a queue, partition by thread).
|
|
250
|
+
Do not call `graph.update_state(...)` on a thread while its workflow waits
|
|
251
|
+
for input: the next reply is then treated as stale and the question is
|
|
252
|
+
asked again. Put edits in the reply instead.
|
|
253
|
+
- **Call `invoke`/`ainvoke` one after another in a workflow**, not with
|
|
254
|
+
`asyncio.gather`. For parallel graph runs, start child workflows.
|
|
255
|
+
- **Use `interrupt()`, not static `interrupt_before`/`interrupt_after`
|
|
256
|
+
breakpoints.** After a crash, a run paused at a static breakpoint could
|
|
257
|
+
continue past it.
|
|
258
|
+
- **Forking** (`DBOS.fork_workflow`) works from the `<name>.start` step or
|
|
259
|
+
earlier: the fork gets its own fresh graph run. Forking into the middle of a
|
|
260
|
+
run raises `ForkNotSupportedError` instead of sharing the original's thread.
|
|
261
|
+
- **Python 3.10 and async nodes:** LangGraph's `interrupt()` does not work in
|
|
262
|
+
`async` nodes on Python 3.10 (a LangGraph limitation). Sync nodes are fine.
|
|
263
|
+
- **Code changes:** as with any DBOS workflow, a pending run must be recovered
|
|
264
|
+
by compatible code. Keep `DBOSGraph(name=...)` stable.
|
|
265
|
+
|
|
266
|
+
## Compared with
|
|
267
|
+
|
|
268
|
+
| | Checkpointer only | langgraph-dbos |
|
|
269
|
+
|---|---|---|
|
|
270
|
+
| State saved after each super-step | yes | yes (same checkpointer) |
|
|
271
|
+
| Unfinished runs restarted after a crash | no: you find and re-invoke them | yes, on `DBOS.launch()` |
|
|
272
|
+
| Waiting for a human across restarts | thread stays paused; you build the resume plumbing | built in, with stale and duplicate protection |
|
|
273
|
+
| Queues, concurrency and rate limits | no | DBOS queues |
|
|
274
|
+
| Run history, cancel, resume, fork | no | DBOS workflow management |
|
|
275
|
+
|
|
276
|
+
[`SamuelXing/dbos-langgraph`](https://github.com/SamuelXing/dbos-langgraph)
|
|
277
|
+
takes a different route: it runs each node as its own DBOS child workflow with
|
|
278
|
+
no LangGraph checkpointer, and nodes are registered through its plugin. This
|
|
279
|
+
package keeps LangGraph's checkpointer and runs your compiled graph as it is,
|
|
280
|
+
which is what lets `interrupt()`, subgraphs and streaming work unchanged.
|
|
281
|
+
|
|
282
|
+
## Development
|
|
283
|
+
|
|
284
|
+
```bash
|
|
285
|
+
uv sync
|
|
286
|
+
uv run pytest # SQLite
|
|
287
|
+
LANGGRAPH_DBOS_TEST_POSTGRES=postgresql://postgres:dbos@localhost:5433/langgraph_dbos uv run pytest
|
|
288
|
+
uv run ruff check . && uv run mypy
|
|
289
|
+
```
|
|
290
|
+
|
|
291
|
+
The recovery tests start a real process, kill it with `SIGKILL` in the middle
|
|
292
|
+
of a run, restart it, and count how many times each node body ran.
|
|
293
|
+
|
|
294
|
+
## License
|
|
295
|
+
|
|
296
|
+
MIT
|