temporalio-langgraph 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.
- temporalio_langgraph-0.1.0/LICENSE +21 -0
- temporalio_langgraph-0.1.0/PKG-INFO +336 -0
- temporalio_langgraph-0.1.0/README.md +311 -0
- temporalio_langgraph-0.1.0/pyproject.toml +128 -0
- temporalio_langgraph-0.1.0/pyproject.toml.orig +114 -0
- temporalio_langgraph-0.1.0/src/temporalio/langgraph/__init__.py +25 -0
- temporalio_langgraph-0.1.0/src/temporalio/langgraph/_activity.py +188 -0
- temporalio_langgraph-0.1.0/src/temporalio/langgraph/_interceptor.py +77 -0
- temporalio_langgraph-0.1.0/src/temporalio/langgraph/_langgraph_config.py +164 -0
- temporalio_langgraph-0.1.0/src/temporalio/langgraph/_plugin.py +382 -0
- temporalio_langgraph-0.1.0/src/temporalio/langgraph/_task_cache.py +83 -0
- temporalio_langgraph-0.1.0/src/temporalio/langgraph/_workflow.py +73 -0
- temporalio_langgraph-0.1.0/src/temporalio/langgraph/py.typed +1 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 temporal.io
|
|
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,336 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: temporalio-langgraph
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Temporal integration for langgraph
|
|
5
|
+
Author: Temporal Technologies Inc
|
|
6
|
+
Author-email: Temporal Technologies Inc <sdk@temporal.io>
|
|
7
|
+
License-Expression: MIT
|
|
8
|
+
License-File: LICENSE
|
|
9
|
+
Classifier: Development Status :: 4 - Beta
|
|
10
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
11
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
12
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
13
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
15
|
+
Classifier: Typing :: Typed
|
|
16
|
+
Requires-Dist: temporalio>=1.34.0,<2
|
|
17
|
+
Requires-Dist: langgraph>=1.2.0
|
|
18
|
+
Requires-Dist: langchain-core>=0.3.0
|
|
19
|
+
Requires-Dist: typing-extensions>=4.2.0,<5
|
|
20
|
+
Requires-Python: >=3.10
|
|
21
|
+
Project-URL: Homepage, https://github.com/temporalio/ai-integrations/tree/main/python/langgraph
|
|
22
|
+
Project-URL: Repository, https://github.com/temporalio/ai-integrations
|
|
23
|
+
Project-URL: Documentation, https://docs.temporal.io/develop/python/integrations/langgraph
|
|
24
|
+
Description-Content-Type: text/markdown
|
|
25
|
+
|
|
26
|
+
# LangGraph Plugin for Temporal Python SDK
|
|
27
|
+
|
|
28
|
+
> Release stage: [Public Preview](https://docs.temporal.io/develop/python/integrations/langgraph).
|
|
29
|
+
|
|
30
|
+
This Temporal [Plugin](https://docs.temporal.io/develop/plugins-guide) allows you to run [LangGraph](https://www.langchain.com/langgraph) nodes and tasks as Temporal Activities, giving your AI workflows durable execution, automatic retries, and timeouts. It supports both the LangGraph Graph API (``StateGraph``) and Functional API (``@entrypoint`` / ``@task``).
|
|
31
|
+
|
|
32
|
+
## Installation
|
|
33
|
+
|
|
34
|
+
```sh
|
|
35
|
+
uv add temporalio-langgraph
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
## Plugin Initialization
|
|
39
|
+
|
|
40
|
+
### Graph API
|
|
41
|
+
|
|
42
|
+
```python
|
|
43
|
+
from langgraph.graph import StateGraph
|
|
44
|
+
from temporalio.langgraph import LangGraphPlugin
|
|
45
|
+
|
|
46
|
+
g = StateGraph(State)
|
|
47
|
+
g.add_node("my_node", my_node, metadata={"execute_in": "activity"})
|
|
48
|
+
|
|
49
|
+
plugin = LangGraphPlugin(graphs={"my-graph": g})
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
### Functional API
|
|
53
|
+
|
|
54
|
+
```python
|
|
55
|
+
from temporalio.langgraph import LangGraphPlugin
|
|
56
|
+
|
|
57
|
+
plugin = LangGraphPlugin(
|
|
58
|
+
entrypoints={"my_entrypoint": my_entrypoint},
|
|
59
|
+
tasks=[my_task],
|
|
60
|
+
activity_options={"my_task": {"execute_in": "activity"}},
|
|
61
|
+
)
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
## Checkpointer
|
|
65
|
+
|
|
66
|
+
If your LangGraph code requires a checkpointer (for example, if you're using interrupts), use `InMemorySaver`.
|
|
67
|
+
Temporal handles durability, so third-party checkpointers (like PostgreSQL or Redis) are not needed.
|
|
68
|
+
|
|
69
|
+
```python
|
|
70
|
+
import langgraph.checkpoint.memory
|
|
71
|
+
import typing
|
|
72
|
+
|
|
73
|
+
from temporalio.langgraph import graph
|
|
74
|
+
from temporalio import workflow
|
|
75
|
+
|
|
76
|
+
@workflow.defn
|
|
77
|
+
class MyWorkflow:
|
|
78
|
+
@workflow.run
|
|
79
|
+
async def run(self, input: str) -> typing.Any:
|
|
80
|
+
g = graph("my-graph").compile(
|
|
81
|
+
checkpointer=langgraph.checkpoint.memory.InMemorySaver(),
|
|
82
|
+
)
|
|
83
|
+
|
|
84
|
+
...
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
## Execution Location
|
|
88
|
+
|
|
89
|
+
Every node (Graph API) and task (Functional API) must be labeled with `execute_in`, set to either `"activity"` or `"workflow"`. This is required per node/task; it cannot be set in `default_activity_options`.
|
|
90
|
+
|
|
91
|
+
```python
|
|
92
|
+
# Graph API
|
|
93
|
+
graph.add_node("my_node", my_node, metadata={"execute_in": "activity"})
|
|
94
|
+
graph.add_node("tool_node", tool_node, metadata={"execute_in": "workflow"})
|
|
95
|
+
|
|
96
|
+
# Functional API
|
|
97
|
+
plugin = LangGraphPlugin(
|
|
98
|
+
tasks=[my_task, tool_task],
|
|
99
|
+
activity_options={
|
|
100
|
+
"my_task": {"execute_in": "activity"},
|
|
101
|
+
"tool_task": {"execute_in": "workflow"},
|
|
102
|
+
},
|
|
103
|
+
)
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
## Activity Options
|
|
107
|
+
|
|
108
|
+
Options are passed through to [`workflow.execute_activity()`](https://python.temporal.io/temporalio.workflow.html#execute_activity), which supports parameters like `start_to_close_timeout`, `retry_policy`, `schedule_to_close_timeout`, `heartbeat_timeout`, and more.
|
|
109
|
+
|
|
110
|
+
### Graph API
|
|
111
|
+
|
|
112
|
+
Pass Activity options as node `metadata` when calling `add_node`:
|
|
113
|
+
|
|
114
|
+
```python
|
|
115
|
+
from datetime import timedelta
|
|
116
|
+
from temporalio.common import RetryPolicy
|
|
117
|
+
|
|
118
|
+
g = StateGraph(State)
|
|
119
|
+
g.add_node("my_node", my_node, metadata={
|
|
120
|
+
"execute_in": "activity",
|
|
121
|
+
"start_to_close_timeout": timedelta(seconds=30),
|
|
122
|
+
"retry_policy": RetryPolicy(maximum_attempts=3),
|
|
123
|
+
})
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
### Functional API
|
|
127
|
+
|
|
128
|
+
Pass Activity options to the `LangGraphPlugin` constructor, keyed by task function name:
|
|
129
|
+
|
|
130
|
+
```python
|
|
131
|
+
from datetime import timedelta
|
|
132
|
+
from temporalio.common import RetryPolicy
|
|
133
|
+
from temporalio.langgraph import LangGraphPlugin
|
|
134
|
+
|
|
135
|
+
plugin = LangGraphPlugin(
|
|
136
|
+
entrypoints={"my_entrypoint": my_entrypoint},
|
|
137
|
+
tasks=[my_task],
|
|
138
|
+
activity_options={
|
|
139
|
+
"my_task": {
|
|
140
|
+
"execute_in": "activity",
|
|
141
|
+
"start_to_close_timeout": timedelta(seconds=30),
|
|
142
|
+
"retry_policy": RetryPolicy(maximum_attempts=3),
|
|
143
|
+
},
|
|
144
|
+
},
|
|
145
|
+
)
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
### Runtime Context
|
|
149
|
+
|
|
150
|
+
LangGraph's run-scoped context (`context_schema`) is reconstructed on the Activity side, so nodes and tasks can read from and write to `runtime.context`:
|
|
151
|
+
|
|
152
|
+
```python
|
|
153
|
+
from langgraph.runtime import Runtime
|
|
154
|
+
from typing_extensions import TypedDict
|
|
155
|
+
|
|
156
|
+
from temporalio.langgraph import graph
|
|
157
|
+
|
|
158
|
+
class Context(TypedDict):
|
|
159
|
+
user_id: str
|
|
160
|
+
|
|
161
|
+
async def my_node(state: State, runtime: Runtime[Context]) -> dict:
|
|
162
|
+
return {"user": runtime.context["user_id"]}
|
|
163
|
+
|
|
164
|
+
# In the Workflow:
|
|
165
|
+
g = graph("my-graph").compile()
|
|
166
|
+
await g.ainvoke({...}, context=Context(user_id="alice"))
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
Your `context` object must be serializable by the configured Temporal payload converter, since it crosses the Activity boundary.
|
|
170
|
+
|
|
171
|
+
## Summaries
|
|
172
|
+
|
|
173
|
+
Summaries are short, human-readable labels that show up in the Temporal UI and CLI, making it easier to see what each step of a run is doing.
|
|
174
|
+
|
|
175
|
+
### Static summary
|
|
176
|
+
|
|
177
|
+
`summary` is an ordinary Activity option, so a fixed per-node label works today — pass it like any other option:
|
|
178
|
+
|
|
179
|
+
```python
|
|
180
|
+
g.add_node("plan", plan, metadata={"execute_in": "activity", "summary": "Planning step"})
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
It is attached to the node's scheduled-activity event (`execute_in="activity"` only).
|
|
184
|
+
|
|
185
|
+
### Dynamic summary (`summary_fn`)
|
|
186
|
+
|
|
187
|
+
To derive the label from the node's input at runtime, supply a `summary_fn`. It receives the node's `(args, kwargs)` and returns a summary string, or `None`/`""` for no summary. For a `StateGraph` node `args[0]` is the state; for a Functional `@task` it is the task's arguments.
|
|
188
|
+
|
|
189
|
+
```python
|
|
190
|
+
def summarize(args, kwargs) -> str | None:
|
|
191
|
+
state = args[0]
|
|
192
|
+
return f"stage={state['stage']} doc={state['doc_id']}"
|
|
193
|
+
|
|
194
|
+
# Graph API: per-node
|
|
195
|
+
g.add_node("plan", plan, metadata={"execute_in": "activity", "summary_fn": summarize})
|
|
196
|
+
|
|
197
|
+
# Functional API: per-task
|
|
198
|
+
plugin = LangGraphPlugin(
|
|
199
|
+
tasks=[plan],
|
|
200
|
+
activity_options={"plan": {"execute_in": "activity", "summary_fn": summarize}},
|
|
201
|
+
)
|
|
202
|
+
```
|
|
203
|
+
|
|
204
|
+
`summary_fn` is set per node/task (like the static `summary`), so different nodes — which receive different inputs — can compute their summaries independently. You can also put a `summary` or `summary_fn` in `default_activity_options` as a fallback for every node; a node/task that sets either form overrides the inherited default (you just can't set both forms at the same level).
|
|
205
|
+
|
|
206
|
+
- For `execute_in="activity"` nodes the result sets the activity `summary` (one per scheduled-activity event, visible in history).
|
|
207
|
+
- For `execute_in="workflow"` nodes there is no activity, so the result updates the workflow's current details via [`workflow.set_current_details()`](https://python.temporal.io/temporalio.workflow.html#set_current_details). This is a single workflow-level slot (last-writer-wins) reflecting the most recent workflow-bound node that defines a `summary_fn`; a `None`/`""` result clears it. It is queryable via `__temporal_workflow_metadata`.
|
|
208
|
+
|
|
209
|
+
`summary_fn` runs in workflow context on every replay, so it **must be deterministic and must not raise** (an exception fails the workflow task). Setting both a static `summary` and a `summary_fn` on the same node raises `ValueError`.
|
|
210
|
+
|
|
211
|
+
## Streaming
|
|
212
|
+
|
|
213
|
+
When `streaming_topic` is set on `LangGraphPlugin`, calls to `langgraph.config.get_stream_writer()` inside a node publish to the named topic on the workflow's [`WorkflowStream`](https://github.com/temporalio/sdk-python/tree/main/temporalio/contrib/workflow_streams). Activity-side nodes publish via `WorkflowStreamClient` (a signal carrying batched items, controlled by `streaming_batch_interval`); workflow-side nodes publish synchronously to the in-workflow stream (no signal). External subscribers consume the stream with `WorkflowStreamClient.create(...).topic(...).subscribe(...)`.
|
|
214
|
+
|
|
215
|
+
The workflow **must** construct `WorkflowStream()` in its `@workflow.init` (i.e. `__init__`)
|
|
216
|
+
|
|
217
|
+
```python
|
|
218
|
+
from datetime import timedelta
|
|
219
|
+
from typing import Any
|
|
220
|
+
|
|
221
|
+
from langgraph.config import get_stream_writer
|
|
222
|
+
from langgraph.graph import START, StateGraph
|
|
223
|
+
from typing_extensions import TypedDict
|
|
224
|
+
|
|
225
|
+
from temporalio import workflow
|
|
226
|
+
from temporalio.client import Client
|
|
227
|
+
from temporalio.langgraph import LangGraphPlugin, graph
|
|
228
|
+
from temporalio.contrib.workflow_streams import WorkflowStream, WorkflowStreamClient
|
|
229
|
+
from temporalio.worker import Worker
|
|
230
|
+
|
|
231
|
+
|
|
232
|
+
class State(TypedDict):
|
|
233
|
+
value: str
|
|
234
|
+
|
|
235
|
+
|
|
236
|
+
async def token_node(state: State) -> dict[str, str]:
|
|
237
|
+
writer = get_stream_writer()
|
|
238
|
+
for token in ["hello", " ", "world"]:
|
|
239
|
+
writer({"token": token})
|
|
240
|
+
writer({"done": True})
|
|
241
|
+
return {"value": "hello world"}
|
|
242
|
+
|
|
243
|
+
|
|
244
|
+
@workflow.defn
|
|
245
|
+
class StreamingWorkflow:
|
|
246
|
+
def __init__(self) -> None:
|
|
247
|
+
# Required when streaming_topic is set on the plugin.
|
|
248
|
+
_ = WorkflowStream()
|
|
249
|
+
self.app = graph("streaming").compile()
|
|
250
|
+
|
|
251
|
+
@workflow.run
|
|
252
|
+
async def run(self) -> str:
|
|
253
|
+
result = await self.app.ainvoke({"value": ""})
|
|
254
|
+
return result["value"]
|
|
255
|
+
|
|
256
|
+
|
|
257
|
+
async def main(client: Client) -> None:
|
|
258
|
+
g = StateGraph(State)
|
|
259
|
+
g.add_node("token_node", token_node, metadata={"execute_in": "activity"})
|
|
260
|
+
g.add_edge(START, "token_node")
|
|
261
|
+
|
|
262
|
+
async with Worker(
|
|
263
|
+
client,
|
|
264
|
+
task_queue="streaming-tq",
|
|
265
|
+
workflows=[StreamingWorkflow],
|
|
266
|
+
plugins=[
|
|
267
|
+
LangGraphPlugin(
|
|
268
|
+
graphs={"streaming": g},
|
|
269
|
+
default_activity_options={
|
|
270
|
+
"start_to_close_timeout": timedelta(seconds=10)
|
|
271
|
+
},
|
|
272
|
+
streaming_topic="tokens",
|
|
273
|
+
)
|
|
274
|
+
],
|
|
275
|
+
):
|
|
276
|
+
handle = await client.start_workflow(
|
|
277
|
+
StreamingWorkflow.run, id="streaming-wf", task_queue="streaming-tq"
|
|
278
|
+
)
|
|
279
|
+
|
|
280
|
+
ws_client = WorkflowStreamClient.create(client, handle.id)
|
|
281
|
+
async for item in ws_client.topic("tokens", type=dict).subscribe(from_offset=0):
|
|
282
|
+
print(item.data)
|
|
283
|
+
if item.data.get("done"):
|
|
284
|
+
break
|
|
285
|
+
|
|
286
|
+
print(await handle.result())
|
|
287
|
+
```
|
|
288
|
+
|
|
289
|
+
### What's covered, and what isn't
|
|
290
|
+
|
|
291
|
+
`streaming_topic` wires up exactly **one** LangGraph stream mode: `stream_mode="custom"`, i.e. values written through `get_stream_writer()`. The other modes — `"messages"`, `"values"`, `"updates"`, `"debug"` — are **not** captured by `streaming_topic`. They aren't produced by node-side writers; LangGraph's orchestrator emits them as it walks the graph. The documented pattern is to **bridge `astream()` in the workflow** and republish each yielded chunk to a `WorkflowStream` topic yourself:
|
|
292
|
+
|
|
293
|
+
```python
|
|
294
|
+
@workflow.defn
|
|
295
|
+
class AstreamBridge:
|
|
296
|
+
def __init__(self) -> None:
|
|
297
|
+
self.stream = WorkflowStream()
|
|
298
|
+
self.app = graph("g").compile()
|
|
299
|
+
|
|
300
|
+
@workflow.run
|
|
301
|
+
async def run(self) -> None:
|
|
302
|
+
topic = self.stream.topic("astream")
|
|
303
|
+
async for chunk in self.app.astream({...}, stream_mode="messages"):
|
|
304
|
+
topic.publish(chunk)
|
|
305
|
+
topic.publish({"done": True})
|
|
306
|
+
```
|
|
307
|
+
|
|
308
|
+
### Retry semantics
|
|
309
|
+
|
|
310
|
+
Streaming has **at-least-once** delivery per activity attempt. When an activity-wrapped node retries (transient failure, worker crash, etc.), the user function re-runs from scratch and re-publishes its writes — earlier publishes from the failed attempt are not rolled back. Subscribers should be ready to see duplicates and recover idempotently (e.g. dedupe on a sequence id you include in each chunk, or treat the stream as advisory and rely on the workflow's final result for state).
|
|
311
|
+
|
|
312
|
+
## Tracing
|
|
313
|
+
|
|
314
|
+
We recommend the [Temporal LangSmith Plugin](https://github.com/temporalio/ai-integrations/tree/main/python/langsmith) to trace your LangGraph Workflows and Activities.
|
|
315
|
+
|
|
316
|
+
## Stores are not supported
|
|
317
|
+
|
|
318
|
+
LangGraph's `Store` (e.g. `InMemoryStore` passed via `graph.compile(store=...)` or `@entrypoint(store=...)`) isn't accessible inside Activity-wrapped nodes: the Store holds live state that can't cross the Activity boundary, and Activities may run on a different worker than the Workflow. If you pass a store, the plugin logs a warning on first use and `runtime.store` is `None` inside nodes.
|
|
319
|
+
|
|
320
|
+
Use Workflow state for per-run memory, or an external database (Postgres/Redis/etc.) configured on each worker if you need shared memory across runs.
|
|
321
|
+
|
|
322
|
+
## Running Tests
|
|
323
|
+
|
|
324
|
+
Install dependencies:
|
|
325
|
+
|
|
326
|
+
```sh
|
|
327
|
+
make sync
|
|
328
|
+
```
|
|
329
|
+
|
|
330
|
+
Run the test suite:
|
|
331
|
+
|
|
332
|
+
```sh
|
|
333
|
+
make test
|
|
334
|
+
```
|
|
335
|
+
|
|
336
|
+
Tests start a local Temporal dev server automatically — no external server needed.
|
|
@@ -0,0 +1,311 @@
|
|
|
1
|
+
# LangGraph Plugin for Temporal Python SDK
|
|
2
|
+
|
|
3
|
+
> Release stage: [Public Preview](https://docs.temporal.io/develop/python/integrations/langgraph).
|
|
4
|
+
|
|
5
|
+
This Temporal [Plugin](https://docs.temporal.io/develop/plugins-guide) allows you to run [LangGraph](https://www.langchain.com/langgraph) nodes and tasks as Temporal Activities, giving your AI workflows durable execution, automatic retries, and timeouts. It supports both the LangGraph Graph API (``StateGraph``) and Functional API (``@entrypoint`` / ``@task``).
|
|
6
|
+
|
|
7
|
+
## Installation
|
|
8
|
+
|
|
9
|
+
```sh
|
|
10
|
+
uv add temporalio-langgraph
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
## Plugin Initialization
|
|
14
|
+
|
|
15
|
+
### Graph API
|
|
16
|
+
|
|
17
|
+
```python
|
|
18
|
+
from langgraph.graph import StateGraph
|
|
19
|
+
from temporalio.langgraph import LangGraphPlugin
|
|
20
|
+
|
|
21
|
+
g = StateGraph(State)
|
|
22
|
+
g.add_node("my_node", my_node, metadata={"execute_in": "activity"})
|
|
23
|
+
|
|
24
|
+
plugin = LangGraphPlugin(graphs={"my-graph": g})
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
### Functional API
|
|
28
|
+
|
|
29
|
+
```python
|
|
30
|
+
from temporalio.langgraph import LangGraphPlugin
|
|
31
|
+
|
|
32
|
+
plugin = LangGraphPlugin(
|
|
33
|
+
entrypoints={"my_entrypoint": my_entrypoint},
|
|
34
|
+
tasks=[my_task],
|
|
35
|
+
activity_options={"my_task": {"execute_in": "activity"}},
|
|
36
|
+
)
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
## Checkpointer
|
|
40
|
+
|
|
41
|
+
If your LangGraph code requires a checkpointer (for example, if you're using interrupts), use `InMemorySaver`.
|
|
42
|
+
Temporal handles durability, so third-party checkpointers (like PostgreSQL or Redis) are not needed.
|
|
43
|
+
|
|
44
|
+
```python
|
|
45
|
+
import langgraph.checkpoint.memory
|
|
46
|
+
import typing
|
|
47
|
+
|
|
48
|
+
from temporalio.langgraph import graph
|
|
49
|
+
from temporalio import workflow
|
|
50
|
+
|
|
51
|
+
@workflow.defn
|
|
52
|
+
class MyWorkflow:
|
|
53
|
+
@workflow.run
|
|
54
|
+
async def run(self, input: str) -> typing.Any:
|
|
55
|
+
g = graph("my-graph").compile(
|
|
56
|
+
checkpointer=langgraph.checkpoint.memory.InMemorySaver(),
|
|
57
|
+
)
|
|
58
|
+
|
|
59
|
+
...
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
## Execution Location
|
|
63
|
+
|
|
64
|
+
Every node (Graph API) and task (Functional API) must be labeled with `execute_in`, set to either `"activity"` or `"workflow"`. This is required per node/task; it cannot be set in `default_activity_options`.
|
|
65
|
+
|
|
66
|
+
```python
|
|
67
|
+
# Graph API
|
|
68
|
+
graph.add_node("my_node", my_node, metadata={"execute_in": "activity"})
|
|
69
|
+
graph.add_node("tool_node", tool_node, metadata={"execute_in": "workflow"})
|
|
70
|
+
|
|
71
|
+
# Functional API
|
|
72
|
+
plugin = LangGraphPlugin(
|
|
73
|
+
tasks=[my_task, tool_task],
|
|
74
|
+
activity_options={
|
|
75
|
+
"my_task": {"execute_in": "activity"},
|
|
76
|
+
"tool_task": {"execute_in": "workflow"},
|
|
77
|
+
},
|
|
78
|
+
)
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
## Activity Options
|
|
82
|
+
|
|
83
|
+
Options are passed through to [`workflow.execute_activity()`](https://python.temporal.io/temporalio.workflow.html#execute_activity), which supports parameters like `start_to_close_timeout`, `retry_policy`, `schedule_to_close_timeout`, `heartbeat_timeout`, and more.
|
|
84
|
+
|
|
85
|
+
### Graph API
|
|
86
|
+
|
|
87
|
+
Pass Activity options as node `metadata` when calling `add_node`:
|
|
88
|
+
|
|
89
|
+
```python
|
|
90
|
+
from datetime import timedelta
|
|
91
|
+
from temporalio.common import RetryPolicy
|
|
92
|
+
|
|
93
|
+
g = StateGraph(State)
|
|
94
|
+
g.add_node("my_node", my_node, metadata={
|
|
95
|
+
"execute_in": "activity",
|
|
96
|
+
"start_to_close_timeout": timedelta(seconds=30),
|
|
97
|
+
"retry_policy": RetryPolicy(maximum_attempts=3),
|
|
98
|
+
})
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
### Functional API
|
|
102
|
+
|
|
103
|
+
Pass Activity options to the `LangGraphPlugin` constructor, keyed by task function name:
|
|
104
|
+
|
|
105
|
+
```python
|
|
106
|
+
from datetime import timedelta
|
|
107
|
+
from temporalio.common import RetryPolicy
|
|
108
|
+
from temporalio.langgraph import LangGraphPlugin
|
|
109
|
+
|
|
110
|
+
plugin = LangGraphPlugin(
|
|
111
|
+
entrypoints={"my_entrypoint": my_entrypoint},
|
|
112
|
+
tasks=[my_task],
|
|
113
|
+
activity_options={
|
|
114
|
+
"my_task": {
|
|
115
|
+
"execute_in": "activity",
|
|
116
|
+
"start_to_close_timeout": timedelta(seconds=30),
|
|
117
|
+
"retry_policy": RetryPolicy(maximum_attempts=3),
|
|
118
|
+
},
|
|
119
|
+
},
|
|
120
|
+
)
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
### Runtime Context
|
|
124
|
+
|
|
125
|
+
LangGraph's run-scoped context (`context_schema`) is reconstructed on the Activity side, so nodes and tasks can read from and write to `runtime.context`:
|
|
126
|
+
|
|
127
|
+
```python
|
|
128
|
+
from langgraph.runtime import Runtime
|
|
129
|
+
from typing_extensions import TypedDict
|
|
130
|
+
|
|
131
|
+
from temporalio.langgraph import graph
|
|
132
|
+
|
|
133
|
+
class Context(TypedDict):
|
|
134
|
+
user_id: str
|
|
135
|
+
|
|
136
|
+
async def my_node(state: State, runtime: Runtime[Context]) -> dict:
|
|
137
|
+
return {"user": runtime.context["user_id"]}
|
|
138
|
+
|
|
139
|
+
# In the Workflow:
|
|
140
|
+
g = graph("my-graph").compile()
|
|
141
|
+
await g.ainvoke({...}, context=Context(user_id="alice"))
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
Your `context` object must be serializable by the configured Temporal payload converter, since it crosses the Activity boundary.
|
|
145
|
+
|
|
146
|
+
## Summaries
|
|
147
|
+
|
|
148
|
+
Summaries are short, human-readable labels that show up in the Temporal UI and CLI, making it easier to see what each step of a run is doing.
|
|
149
|
+
|
|
150
|
+
### Static summary
|
|
151
|
+
|
|
152
|
+
`summary` is an ordinary Activity option, so a fixed per-node label works today — pass it like any other option:
|
|
153
|
+
|
|
154
|
+
```python
|
|
155
|
+
g.add_node("plan", plan, metadata={"execute_in": "activity", "summary": "Planning step"})
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
It is attached to the node's scheduled-activity event (`execute_in="activity"` only).
|
|
159
|
+
|
|
160
|
+
### Dynamic summary (`summary_fn`)
|
|
161
|
+
|
|
162
|
+
To derive the label from the node's input at runtime, supply a `summary_fn`. It receives the node's `(args, kwargs)` and returns a summary string, or `None`/`""` for no summary. For a `StateGraph` node `args[0]` is the state; for a Functional `@task` it is the task's arguments.
|
|
163
|
+
|
|
164
|
+
```python
|
|
165
|
+
def summarize(args, kwargs) -> str | None:
|
|
166
|
+
state = args[0]
|
|
167
|
+
return f"stage={state['stage']} doc={state['doc_id']}"
|
|
168
|
+
|
|
169
|
+
# Graph API: per-node
|
|
170
|
+
g.add_node("plan", plan, metadata={"execute_in": "activity", "summary_fn": summarize})
|
|
171
|
+
|
|
172
|
+
# Functional API: per-task
|
|
173
|
+
plugin = LangGraphPlugin(
|
|
174
|
+
tasks=[plan],
|
|
175
|
+
activity_options={"plan": {"execute_in": "activity", "summary_fn": summarize}},
|
|
176
|
+
)
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
`summary_fn` is set per node/task (like the static `summary`), so different nodes — which receive different inputs — can compute their summaries independently. You can also put a `summary` or `summary_fn` in `default_activity_options` as a fallback for every node; a node/task that sets either form overrides the inherited default (you just can't set both forms at the same level).
|
|
180
|
+
|
|
181
|
+
- For `execute_in="activity"` nodes the result sets the activity `summary` (one per scheduled-activity event, visible in history).
|
|
182
|
+
- For `execute_in="workflow"` nodes there is no activity, so the result updates the workflow's current details via [`workflow.set_current_details()`](https://python.temporal.io/temporalio.workflow.html#set_current_details). This is a single workflow-level slot (last-writer-wins) reflecting the most recent workflow-bound node that defines a `summary_fn`; a `None`/`""` result clears it. It is queryable via `__temporal_workflow_metadata`.
|
|
183
|
+
|
|
184
|
+
`summary_fn` runs in workflow context on every replay, so it **must be deterministic and must not raise** (an exception fails the workflow task). Setting both a static `summary` and a `summary_fn` on the same node raises `ValueError`.
|
|
185
|
+
|
|
186
|
+
## Streaming
|
|
187
|
+
|
|
188
|
+
When `streaming_topic` is set on `LangGraphPlugin`, calls to `langgraph.config.get_stream_writer()` inside a node publish to the named topic on the workflow's [`WorkflowStream`](https://github.com/temporalio/sdk-python/tree/main/temporalio/contrib/workflow_streams). Activity-side nodes publish via `WorkflowStreamClient` (a signal carrying batched items, controlled by `streaming_batch_interval`); workflow-side nodes publish synchronously to the in-workflow stream (no signal). External subscribers consume the stream with `WorkflowStreamClient.create(...).topic(...).subscribe(...)`.
|
|
189
|
+
|
|
190
|
+
The workflow **must** construct `WorkflowStream()` in its `@workflow.init` (i.e. `__init__`)
|
|
191
|
+
|
|
192
|
+
```python
|
|
193
|
+
from datetime import timedelta
|
|
194
|
+
from typing import Any
|
|
195
|
+
|
|
196
|
+
from langgraph.config import get_stream_writer
|
|
197
|
+
from langgraph.graph import START, StateGraph
|
|
198
|
+
from typing_extensions import TypedDict
|
|
199
|
+
|
|
200
|
+
from temporalio import workflow
|
|
201
|
+
from temporalio.client import Client
|
|
202
|
+
from temporalio.langgraph import LangGraphPlugin, graph
|
|
203
|
+
from temporalio.contrib.workflow_streams import WorkflowStream, WorkflowStreamClient
|
|
204
|
+
from temporalio.worker import Worker
|
|
205
|
+
|
|
206
|
+
|
|
207
|
+
class State(TypedDict):
|
|
208
|
+
value: str
|
|
209
|
+
|
|
210
|
+
|
|
211
|
+
async def token_node(state: State) -> dict[str, str]:
|
|
212
|
+
writer = get_stream_writer()
|
|
213
|
+
for token in ["hello", " ", "world"]:
|
|
214
|
+
writer({"token": token})
|
|
215
|
+
writer({"done": True})
|
|
216
|
+
return {"value": "hello world"}
|
|
217
|
+
|
|
218
|
+
|
|
219
|
+
@workflow.defn
|
|
220
|
+
class StreamingWorkflow:
|
|
221
|
+
def __init__(self) -> None:
|
|
222
|
+
# Required when streaming_topic is set on the plugin.
|
|
223
|
+
_ = WorkflowStream()
|
|
224
|
+
self.app = graph("streaming").compile()
|
|
225
|
+
|
|
226
|
+
@workflow.run
|
|
227
|
+
async def run(self) -> str:
|
|
228
|
+
result = await self.app.ainvoke({"value": ""})
|
|
229
|
+
return result["value"]
|
|
230
|
+
|
|
231
|
+
|
|
232
|
+
async def main(client: Client) -> None:
|
|
233
|
+
g = StateGraph(State)
|
|
234
|
+
g.add_node("token_node", token_node, metadata={"execute_in": "activity"})
|
|
235
|
+
g.add_edge(START, "token_node")
|
|
236
|
+
|
|
237
|
+
async with Worker(
|
|
238
|
+
client,
|
|
239
|
+
task_queue="streaming-tq",
|
|
240
|
+
workflows=[StreamingWorkflow],
|
|
241
|
+
plugins=[
|
|
242
|
+
LangGraphPlugin(
|
|
243
|
+
graphs={"streaming": g},
|
|
244
|
+
default_activity_options={
|
|
245
|
+
"start_to_close_timeout": timedelta(seconds=10)
|
|
246
|
+
},
|
|
247
|
+
streaming_topic="tokens",
|
|
248
|
+
)
|
|
249
|
+
],
|
|
250
|
+
):
|
|
251
|
+
handle = await client.start_workflow(
|
|
252
|
+
StreamingWorkflow.run, id="streaming-wf", task_queue="streaming-tq"
|
|
253
|
+
)
|
|
254
|
+
|
|
255
|
+
ws_client = WorkflowStreamClient.create(client, handle.id)
|
|
256
|
+
async for item in ws_client.topic("tokens", type=dict).subscribe(from_offset=0):
|
|
257
|
+
print(item.data)
|
|
258
|
+
if item.data.get("done"):
|
|
259
|
+
break
|
|
260
|
+
|
|
261
|
+
print(await handle.result())
|
|
262
|
+
```
|
|
263
|
+
|
|
264
|
+
### What's covered, and what isn't
|
|
265
|
+
|
|
266
|
+
`streaming_topic` wires up exactly **one** LangGraph stream mode: `stream_mode="custom"`, i.e. values written through `get_stream_writer()`. The other modes — `"messages"`, `"values"`, `"updates"`, `"debug"` — are **not** captured by `streaming_topic`. They aren't produced by node-side writers; LangGraph's orchestrator emits them as it walks the graph. The documented pattern is to **bridge `astream()` in the workflow** and republish each yielded chunk to a `WorkflowStream` topic yourself:
|
|
267
|
+
|
|
268
|
+
```python
|
|
269
|
+
@workflow.defn
|
|
270
|
+
class AstreamBridge:
|
|
271
|
+
def __init__(self) -> None:
|
|
272
|
+
self.stream = WorkflowStream()
|
|
273
|
+
self.app = graph("g").compile()
|
|
274
|
+
|
|
275
|
+
@workflow.run
|
|
276
|
+
async def run(self) -> None:
|
|
277
|
+
topic = self.stream.topic("astream")
|
|
278
|
+
async for chunk in self.app.astream({...}, stream_mode="messages"):
|
|
279
|
+
topic.publish(chunk)
|
|
280
|
+
topic.publish({"done": True})
|
|
281
|
+
```
|
|
282
|
+
|
|
283
|
+
### Retry semantics
|
|
284
|
+
|
|
285
|
+
Streaming has **at-least-once** delivery per activity attempt. When an activity-wrapped node retries (transient failure, worker crash, etc.), the user function re-runs from scratch and re-publishes its writes — earlier publishes from the failed attempt are not rolled back. Subscribers should be ready to see duplicates and recover idempotently (e.g. dedupe on a sequence id you include in each chunk, or treat the stream as advisory and rely on the workflow's final result for state).
|
|
286
|
+
|
|
287
|
+
## Tracing
|
|
288
|
+
|
|
289
|
+
We recommend the [Temporal LangSmith Plugin](https://github.com/temporalio/ai-integrations/tree/main/python/langsmith) to trace your LangGraph Workflows and Activities.
|
|
290
|
+
|
|
291
|
+
## Stores are not supported
|
|
292
|
+
|
|
293
|
+
LangGraph's `Store` (e.g. `InMemoryStore` passed via `graph.compile(store=...)` or `@entrypoint(store=...)`) isn't accessible inside Activity-wrapped nodes: the Store holds live state that can't cross the Activity boundary, and Activities may run on a different worker than the Workflow. If you pass a store, the plugin logs a warning on first use and `runtime.store` is `None` inside nodes.
|
|
294
|
+
|
|
295
|
+
Use Workflow state for per-run memory, or an external database (Postgres/Redis/etc.) configured on each worker if you need shared memory across runs.
|
|
296
|
+
|
|
297
|
+
## Running Tests
|
|
298
|
+
|
|
299
|
+
Install dependencies:
|
|
300
|
+
|
|
301
|
+
```sh
|
|
302
|
+
make sync
|
|
303
|
+
```
|
|
304
|
+
|
|
305
|
+
Run the test suite:
|
|
306
|
+
|
|
307
|
+
```sh
|
|
308
|
+
make test
|
|
309
|
+
```
|
|
310
|
+
|
|
311
|
+
Tests start a local Temporal dev server automatically — no external server needed.
|