PydanticAI: Graph Support
Typed, multi-step workflows with pydantic_graph: GraphBuilder steps, decisions, parallel map/join, BaseNode classes, iteration and Mermaid rendering — combined with PydanticAI agents.
Verified against pydantic-ai 2.68.0, which pins the matching pydantic-graph release (checked 2026-11-19). Every example on this page was run against that release.
Graphs live in the separate pydantic_graph package, installed with pydantic-ai.
When to use a graph
Section titled “When to use a graph”Most applications do not need one. An Agent already runs a loop of model calls and tool calls, and ordinary Python (if, await, asyncio.gather) composes several agents perfectly well. Reach for pydantic_graph when you want:
- an explicit, typed state machine: a type checker (pyright, mypy) checks that each edge’s source output fits its destination’s input, and
build()checks the structure (every node reachable, no dead ends); - fan-out / fan-in over a list with a defined join;
- a diagram of the workflow generated from the code (
graph.render()); - step-by-step control of execution (
graph.iter()).
PydanticAI’s own agent loop is implemented on pydantic_graph; that is what agent.iter() exposes as UserPromptNode → ModelRequestNode → CallToolsNode → End.
What changed in V2
Section titled “What changed in V2”| V1 | V2 |
|---|---|
from pydantic_graph.beta import GraphBuilder | from pydantic_graph import GraphBuilder |
Graph(nodes=[...]) built from BaseNode classes | Build with GraphBuilder; add BaseNode classes with builder.node(NodeClass) |
pydantic_graph.persistence (FullStatePersistence, FileStatePersistence, iter_from_persistence) | Removed — no replacement in pydantic_graph. For agent-run persistence see Durable execution |
pydantic_graph.mermaid | Removed — use graph.render() |
StateT/DepsT/RunEndT default to None | Default to object (type-checking only) |
Core vocabulary
Section titled “Core vocabulary”| Concept | API | Notes |
|---|---|---|
| Builder | GraphBuilder(state_type=, deps_type=, input_type=, output_type=) | Collects steps and edges; build() validates the structure and returns a Graph. |
| Step | @builder.step on async def f(ctx: StepContext[State, Deps, Input]) -> Output | ctx.state (mutable, shared), ctx.deps, ctx.inputs (the previous step’s output). |
| Stream step | @builder.stream on an async generator | Each yielded item can be sent down its own branch with .map(). |
| Edge | builder.edge_from(a).to(b) / builder.add_edge(a, b) | Output type of a must fit the input type of b — checked by your type checker, not at run time. |
| Start / end | builder.start_node, builder.end_node | The graph’s inputs= flows out of the start node; whatever reaches the end node is the result. |
| Decision | builder.decision().branch(builder.match(T).to(step)) | Routes on the type of the value (with an optional matches= predicate). |
| Fan-out / fan-in | .map() on an edge, builder.join(reducer, ...) | One parallel branch per item, collected by a reducer such as reduce_list_append. |
| Legacy nodes | BaseNode subclasses + builder.node(Cls) | Edges come from the run() return annotation. |
1. Steps, state and a decision — routing a support ticket
Section titled “1. Steps, state and a decision — routing a support ticket”Each step is an async function. A decision node routes the triage result to one of two desks; the agents use TestModel here so the example runs offline — swap in a real model string.
import asynciofrom dataclasses import dataclass, fieldfrom typing import Literal
from pydantic import BaseModelfrom pydantic_ai import Agentfrom pydantic_ai.models.test import TestModelfrom pydantic_graph import GraphBuilder, StepContext, reduce_list_append
@dataclassclass TicketState: log: list[str] = field(default_factory=list)
class Triage(BaseModel): category: Literal['billing', 'technical'] summary: str
triage_agent = Agent(TestModel(), output_type=Triage, instructions='Classify the support ticket.')reply_agent = Agent(TestModel(), instructions='Draft a short, polite reply.')
g = GraphBuilder(state_type=TicketState, input_type=str, output_type=str)
@g.stepasync def triage(ctx: StepContext[TicketState, None, str]) -> Triage: result = await triage_agent.run(ctx.inputs) ctx.state.log.append(f'triaged as {result.output.category}') return result.output
@g.stepasync def billing(ctx: StepContext[TicketState, None, Triage]) -> str: ctx.state.log.append('billing desk') return (await reply_agent.run(f'Billing issue: {ctx.inputs.summary}')).output
@g.stepasync def technical(ctx: StepContext[TicketState, None, Triage]) -> str: ctx.state.log.append('tech desk') return (await reply_agent.run(f'Technical issue: {ctx.inputs.summary}')).output
g.add( g.edge_from(g.start_node).to(triage), g.edge_from(triage).to( g.decision() .branch(g.match(Triage, matches=lambda t: t.category == 'billing').to(billing)) .branch(g.match(Triage).to(technical)) ), g.edge_from(billing, technical).to(g.end_node),)graph = g.build()
async def main(): state = TicketState() reply = await graph.run(state=state, inputs='I was charged twice this month.') print(reply) print(state.log) print(graph.render())
asyncio.run(main())Output (with TestModel):
success (no tool calls)['triaged as billing', 'billing desk']stateDiagram-v2 triage state decision <<choice>> billing technical
[*] --> triage triage --> decision decision --> billing decision --> technical billing --> [*] technical --> [*]Notes:
builder.match()takes a type (a class, orLiteral[...]for string values) — not a raw value. Usematches=for anything finer, as above. Branches are tried in order.graph.render()returns a MermaidstateDiagram-v2; paste it into any Mermaid renderer.- Steps share
ctx.state; the value passed along an edge is the step’s return value.
2. Parallel fan-out and join — summarising several documents
Section titled “2. Parallel fan-out and join — summarising several documents”.map() on an edge sends each element of an iterable down its own branch; a join collects the branches back together with a reducer.
import asynciofrom pydantic_ai import Agentfrom pydantic_ai.models.test import TestModelfrom pydantic_graph import GraphBuilder, StepContext, reduce_list_append
summariser = Agent(TestModel(custom_output_text='summary'), instructions='Summarise in one sentence.')
g = GraphBuilder(input_type=list[str], output_type=list[str])
@g.stepasync def split(ctx: StepContext[None, None, list[str]]) -> list[str]: return [doc.strip() for doc in ctx.inputs if doc.strip()]
@g.stepasync def summarise(ctx: StepContext[None, None, str]) -> str: result = await summariser.run(ctx.inputs) return f'{ctx.inputs[:12]}… → {result.output}'
collect = g.join(reduce_list_append, initial_factory=list[str])
g.add( g.edge_from(g.start_node).to(split), g.edge_from(split).map().to(summarise), # one parallel branch per document g.edge_from(summarise).to(collect), # fan back in g.edge_from(collect).to(g.end_node),)graph = g.build()
print(asyncio.run(graph.run(inputs=['First report text', 'Second report text', ' '])))['First report… → summary', 'Second repor… → summary']Built-in reducers: reduce_list_append, reduce_list_extend, reduce_dict_update, reduce_sum, reduce_null, and ReduceFirstValue (first result wins; the reducer context can cancel the sibling branches). A custom reducer is any (current, item) -> new_current function, optionally taking a ReducerContext first.
3. BaseNode classes — the explicit state-machine style
Section titled “3. BaseNode classes — the explicit state-machine style”If you prefer each node to be a class whose run() return annotation declares where it can go next, subclass BaseNode and add the classes with builder.node(...). The start edge needs a node instance, passed as the graph input.
from __future__ import annotationsimport asynciofrom dataclasses import dataclassfrom pydantic_graph import BaseNode, End, GraphBuilder, GraphRunContext
@dataclassclass CountState: count: int = 0
@dataclassclass Increment(BaseNode[CountState, None, int]): async def run(self, ctx: GraphRunContext[CountState, None]) -> Check: ctx.state.count += 1 return Check()
@dataclassclass Check(BaseNode[CountState, None, int]): async def run(self, ctx: GraphRunContext[CountState, None]) -> Increment | End[int]: if ctx.state.count >= 3: return End(ctx.state.count) return Increment()
g = GraphBuilder(state_type=CountState, input_type=Increment, output_type=int)g.add( g.node(Increment), g.node(Check), g.edge_from(g.start_node).to(Increment),)graph = g.build()
state = CountState()print(asyncio.run(graph.run(state=state, inputs=Increment())), state)
async def show_steps(): async with graph.iter(state=CountState(), inputs=Increment()) as run: async for tasks in run: # each step yields the tasks about to run (or the end marker) if isinstance(tasks, list): print([str(t.node_id) for t in tasks]) print('output:', run.output)asyncio.run(show_steps())3 CountState(count=3)['Increment']['Check']['Increment']['Check']['Increment']['Check']output: 3from __future__ import annotations lets nodes reference classes defined later in the file. The return annotation is what the builder reads to create edges, so it must be accurate: Increment | End[int] means “go to Increment or finish with an int”.
4. Driving a graph step by step
Section titled “4. Driving a graph step by step”graph.iter(...) is an async context manager yielding a GraphRun. Iterating it yields, at each step, the list of GraphTasks about to run (each has a node_id and inputs), and finally an EndMarker; run.output holds the result. Use it for progress reporting, or to stop early by breaking out of the loop. If a node raises, the next iteration re-raises the error; run.override_next(...) lets a supervisor redirect the graph to other tasks (or an EndMarker) instead.
graph.run(...) has a synchronous twin, graph.run_sync(...), for scripts. graph.render(title=..., direction=...) sets the Mermaid diagram’s title and layout direction.
5. Streaming steps — fan out as items arrive
Section titled “5. Streaming steps — fan out as items arrive”@g.stream turns an async generator into a step. Mapped with .map(), each yielded item starts its own branch as soon as it is produced, so slow producers (paginated APIs, search results, an agent streaming a list) overlap with the work done on each item:
import asyncio
from pydantic_graph import GraphBuilder, StepContext, reduce_list_append
g = GraphBuilder(input_type=list[str], output_type=list[str])
@g.streamasync def fetch_pages(ctx: StepContext[None, None, list[str]]): for url in ctx.inputs: await asyncio.sleep(0.01) # stand-in for an HTTP request yield f'<html>{url}</html>'
@g.stepasync def extract_title(ctx: StepContext[None, None, str]) -> str: return ctx.inputs.removeprefix('<html>').removesuffix('</html>').upper()
collect = g.join(reduce_list_append, initial_factory=list[str])
g.add( g.edge_from(g.start_node).to(fetch_pages), g.edge_from(fetch_pages).map().to(extract_title), g.edge_from(extract_title).to(collect), g.edge_from(collect).to(g.end_node),)graph = g.build()
print(sorted(graph.run_sync(inputs=['a.example', 'b.example'])))['A.EXAMPLE', 'B.EXAMPLE']Branches finish in whatever order they finish, so sort (or key) the joined result if order matters.
6. Agents inside steps
Section titled “6. Agents inside steps”A step is plain async code, so an agent call is just await agent.run(...) (example 1). A few practical rules:
- Pass
depsthrough: give the graph adeps_type, then callagent.run(..., deps=ctx.deps)inside steps. - Keep usage together: create one
RunUsage()and passusage=to eachagent.runcall if you want a single total for the whole graph, andusage_limits=to cap it. - Structured hand-offs: give each agent an
output_typethat matches the next step’s input type, so the builder’s type checking covers the hand-off. - Instrumentation:
GraphBuilder(auto_instrument=True)(the default) instruments the graph run when Logfire / OpenTelemetry is configured, so graph and agent spans appear in one trace.
Gotchas
Section titled “Gotchas”- Types are the routing table — for the type checker.
build()checks the graph’s structure: edges from the start node and to the end node exist, every node is reachable and none is a dead end (passvalidate_graph_structure=Falseto skip). It does not compare types: a step returningdictwired to a step expectingTriagebuilds and runs, and fails only when the second step uses its input. Run pyright or mypy over graph code to catch those mismatches. Decisions are the exception —match()tests the value’s type at run time to choose a branch. match()needs a type:builder.match('billing')fails; usebuilder.match(Literal['billing'])ormatches=.- No built-in persistence. If the process dies mid-graph, the run is gone. Put the graph inside a durable workflow (Temporal / DBOS / Prefect) if it must survive restarts.
- State is shared across parallel branches. Branches created by
.map()run concurrently and see the samectx.state; prefer returning values to a join over mutating shared state.
Reference
Section titled “Reference”GraphBuilder,Graph,GraphRun,GraphTask,EndMarker,ErrorMarker,StepContext,BaseNode,End,GraphRunContext, reducers,GraphSetupError,GraphRuntimeError—pydantic_graph(top-level exports)- Edge-path builders and markers —
pydantic_graph.paths - Decisions —
pydantic_graph.decision; joins and reducers —pydantic_graph.join - Lower-level types (
Path,Fork,Join, ID types) are in the upstream graph docs and thepydantic_graphdocstrings