Skip to content
PaPy

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.

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.

V1V2
from pydantic_graph.beta import GraphBuilderfrom pydantic_graph import GraphBuilder
Graph(nodes=[...]) built from BaseNode classesBuild 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.mermaidRemoved — use graph.render()
StateT/DepsT/RunEndT default to NoneDefault to object (type-checking only)

ConceptAPINotes
BuilderGraphBuilder(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]) -> Outputctx.state (mutable, shared), ctx.deps, ctx.inputs (the previous step’s output).
Stream step@builder.stream on an async generatorEach yielded item can be sent down its own branch with .map().
Edgebuilder.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 / endbuilder.start_node, builder.end_nodeThe graph’s inputs= flows out of the start node; whatever reaches the end node is the result.
Decisionbuilder.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 nodesBaseNode 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 asyncio
from dataclasses import dataclass, field
from typing import Literal
from pydantic import BaseModel
from pydantic_ai import Agent
from pydantic_ai.models.test import TestModel
from pydantic_graph import GraphBuilder, StepContext, reduce_list_append
@dataclass
class 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.step
async 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.step
async 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.step
async 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, or Literal[...] for string values) — not a raw value. Use matches= for anything finer, as above. Branches are tried in order.
  • graph.render() returns a Mermaid stateDiagram-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 asyncio
from pydantic_ai import Agent
from pydantic_ai.models.test import TestModel
from 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.step
async def split(ctx: StepContext[None, None, list[str]]) -> list[str]:
return [doc.strip() for doc in ctx.inputs if doc.strip()]
@g.step
async 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 annotations
import asyncio
from dataclasses import dataclass
from pydantic_graph import BaseNode, End, GraphBuilder, GraphRunContext
@dataclass
class CountState:
count: int = 0
@dataclass
class Increment(BaseNode[CountState, None, int]):
async def run(self, ctx: GraphRunContext[CountState, None]) -> Check:
ctx.state.count += 1
return Check()
@dataclass
class 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: 3

from __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”.

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.stream
async 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.step
async 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.

A step is plain async code, so an agent call is just await agent.run(...) (example 1). A few practical rules:

  • Pass deps through: give the graph a deps_type, then call agent.run(..., deps=ctx.deps) inside steps.
  • Keep usage together: create one RunUsage() and pass usage= to each agent.run call if you want a single total for the whole graph, and usage_limits= to cap it.
  • Structured hand-offs: give each agent an output_type that 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.

  • 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 (pass validate_graph_structure=False to skip). It does not compare types: a step returning dict wired to a step expecting Triage builds 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; use builder.match(Literal['billing']) or matches=.
  • 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 same ctx.state; prefer returning values to a join over mutating shared state.
  • 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 the pydantic_graph docstrings