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.
@@ -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.