Describing a team of agents and how work passes between them.
Sourced
Concept at a glance
The handoff can be model-selected, but code still limits which destinations exist.
A focused engineering & technical work example. Additional perspectives appear where they provide a useful contrast.
Representing agent roles and the permitted handoffs or transitions between them.
Follow a task through a network of agent roles and explicit handoffs. Inspect which state is shared, who chooses the next route, and how the system handles a return to an earlier stage.
Investigate an incident and prepare a reviewed remediation plan.
Role graph, handoff packet, reviewer rejection, bounded retry, and a human-approved remediation plan.
The setting makes the example concrete. Carry the underlying pattern into your own work; adapt the sources, tools, and level of oversight to your task.
Investigate an incident and prepare a reviewed remediation plan.
Authored case. Select any record below; nothing is sent to a model.What changed: Establish the facts supplied for this version of the task.
A role diagram is not an execution policy. State ownership and transition conditions need to be specified separately.
Describe your task to your own model and use Agent graphs as a reference. Ask whether it fits, which alternatives meet the same automation needs, and how you would implement and check the result.
Agent graphs is level 6 read as a graph: nodes are agents, not fixed steps; edges are handoffs between them. State sharing and checkpointing depend on the implementation; they are not automatic properties of an agent graph. It is the third page in the site’s graph engineering thread, after knowledge graphs, which connect information, and workflow graphs, which connect work in code.
The useful distinction is how work is delegated and who chooses subsequent actions. A workflow can also use model-based classification or contain an agent. In the supervisor example here, one node uses a model, and its output selects which node runs next from an explicit list of names. OpenAI’s Agents SDK documents the same arrangement: “If you have multiple possible destinations, register one handoff per destination and let the model choose among them.”[1] Nothing else about the shape changes: code still runs every node, still checkpoints state after each one, and a hop cap still stops the graph the model cannot see past.
This page provides primary references and illustrative examples. The examples are scripted, not measured model runs; source references do not establish the correctness of every implementation or outcome.
This separate, scripted trace illustrates the code example discussed in the implementation details. Use it to inspect individual steps, inputs, and outputs.
A supervisor's own output picks the next agent from an allowlist, hop by hop, until it has enough to write.
This is a scripted illustration, not a recorded model run. Its timing and token figures are not measured performance.
"What is the maximum vent run for the DR-520, and does anything supersede the manual's figure?"
There is nothing on this page for you to turn on. Agent graphs run inside a product’s own orchestration layer, assembled by whoever built it, and no product offers one as a feature with a name and a settings page. If you are choosing a product rather than writing one, the page you want is always-on assistants, and a lead and its workers is the version of this shape you can actually watch happen.
The names here belong to developers. LangGraph, Microsoft Agent Framework, CrewAI and Google’s Agent Development Kit are all registered against this technique, and an open protocol exists for the case where agents built on different ones of them have to hand work to each other. Agent2Agent (A2A) states its purpose as “Connect agents built on different platforms (LangGraph, CrewAI, Semantic Kernel, custom solutions) to create powerful, composite AI systems.”[2] Its own site says A2A was “Originally developed by Google and now donated to the Linux Foundation”[2], and is at version 1.0. Microsoft’s own framework documentation names the shape plainly: “graph-based workflows supporting sequential, concurrent, handoff, and group collaboration patterns; includes checkpointing, streaming, human-in-the-loop, and time-travel”[3]: checkpointing and handoff, named together, are exactly the two things that separate a graph of agents from a plain loop.
One consequence does reach you, and it is the only thing here to act on. When a multi-step assistant’s tone or accuracy changes partway through one answer, a handoff happened. Ask the vendor whether the product labels them: “When more than one agent works on a request, does the answer or the log say which one produced which part?” A product that tells you gives you something to check. A product where the handoff is invisible gives you an answer whose author you cannot identify, which is worth weighing before you buy, not after a wrong answer you cannot trace.
The example extends the idea in workflow graphs’ own runner without editing that file: nodes are plain functions over shared state, and the runner checkpoints after every node. The only change is that one node, the supervisor, is not a fixed code rule; it is a model call, and the loop acts on whatever node name that call’s output names.
def run(
question: str,
model: Model,
embedder: Embedder | None,
tracer: Tracer,
*,
corpus_dir: Path = DEFAULT_CORPUS_DIR,
max_research_hops: int = MAX_RESEARCH_HOPS,
) -> Answer:
del embedder # retrieval here is keyword search, like workflow_graphs
sections = load_sections(corpus_dir)
findings: list[tuple[str, str]] = []
hops = 0
while True:
if hops >= max_research_hops:
tracer.record(
kind="code", decided_by="code", title="Hop cap reached",
detail=f"{hops} research hops >= {max_research_hops}; forcing write",
)
choice = "write"
else:
choice = _supervisor_choose(question, findings, model, tracer)
if choice not in ALLOWED_HANDOFFS:
tracer.record(
kind="code", decided_by="code", title="Handoff blocked",
detail=f"{choice!r} is not in the allowlist {sorted(ALLOWED_HANDOFFS)}; forcing write",
)
choice = "write"
if choice == "write":
answer_text = _node_write(question, findings, model, tracer)
break
hops += 1
_node_research(question, sections, findings, tracer)
citations = sorted({cite for cite, _ in findings})
return Answer.from_text(answer_text, retrieved_sources=citations)Code never hands that name straight to a node without checking it first. ALLOWED_HANDOFFS plays
the role OpenAI’s own is_enabled handoff switch does: “a boolean or a function that returns a
boolean, allowing you to dynamically enable or disable the handoff at runtime”[1], here
fixed rather than dynamic: a name the model returns that is not research or write is caught
before the graph acts on it, recorded as a Handoff blocked step, and the run is forced to write
instead. tests/test_example_agent_graphs.py scripts exactly this: the model answers
delete_database, and the test checks the run never treats that as a research hop, cites nothing,
and still returns an answer rather than failing.
research and write are ordinary code, the same as any node in a workflow graph. research
re-searches the whole corpus for the original question, skipping any section already found, so a
second hop turns up the next-best match instead of repeating the first: the reason this run needs
three hops to gather the manual’s figure, the bulletin that revises it, and the revised number
itself, in that order. MAX_RESEARCH_HOPS (4 by default) caps how many times the supervisor may
send the team back to research; past the cap, code forces write on its own without asking the
model again, unlike a blocked handoff, which does still get one more supervisor call afterward.
Run it yourself:
python -m examples.agent_graphs --model stub:scriptedEvery step the trace names Supervisor picks the next agent is decided_by: "model"; every checkpoint, the
blocked-handoff step and the hop-cap step are decided_by: "code". This is the same distinction workflow graphs’ own page draws, with one more place a
model, not code, now gets to choose.
Try workflow graphs first if every transition rule can be written down before the graph runs: most graphs can, and a fixed rule costs nothing to evaluate and is wrong the same way every time it is wrong.
Try a single agent instead if one model, one loop and one context window is enough: a graph of separate agents is only worth its extra machinery once the task needs more than one agent’s own context to hold.
Move up to agent graphs once a node’s own output has to pick which agent runs next, not just what a fixed step does. This is the same reason workflow graphs justifies moving up from a plain chain, one level higher.
Illustrative, not measured: no result file exists for this technique yet, so every number below is a worked example. See docs/EVALS.md for how a real run is recorded and scored.
agent_graphs answers the same question-about-the-documents task rag and single_agent are
scored on (the write node’s final answer cites the sections the research node actually found), so
it fits the site’s 60-question set the same way: exact or rubric match, citation hit rate, plus a
number specific to this shape: hops used per question against the cap, which shows directly
whether a question needed one pass through the graph or several.
scripts/eval_run.py counts agent_graphs among the examples the question set can score (see
docs/EVALS.md). No result file exists for it yet, so this page cannot say a number for any of
it. Run python scripts/eval_run.py --example agent_graphs --model <spec> --dry to project the
cost of a real run first; that projection assumes the full hop cap, which is the ceiling, not
what a typical question costs.
Hops used per question against the cap, the share of runs where a handoff was blocked as outside the allowlist, and how often the hop cap fires before the supervisor chooses to write on its own.
Cost tracks hops, not a fixed step count: a question the graph resolves in one research hop costs two calls, and one that needs the full hop cap costs several times that, for the same question, the way a single agent's cost tracks how many actions it takes.
The supervisor keeps handing off to research without making progress, silently spending the whole hop cap on a question the graph's two agents were never going to resolve, or a handoff target the model invented gets blocked and the run ships a thinner answer than the question needed.
Every supervisor decision with its full output text, every checkpoint's state, any blocked-handoff event, and which cap (if any) forced the stop, so a bad answer traces back to a specific handoff rather than an unexplained partial result.
Watch a multi-step assistant handle a task that plausibly needs more than one kind of expertise (research plus writing, say). Does anything in its reply say a different specialist or stage handled part of it, or is the switch invisible?
Run python -m examples.agent_graphs --model stub:scripted from the repo root. The supervisor sends the team to research three times, each hop surfacing a section the last one did not, then hands off to write, and the answer cites the service bulletin that supersedes the manual. Run it again with --model stub to see why the scripted sequence exists: the echo is not one of the two agent names, so the first hop goes nowhere and the run ends with no citations at all.
Pick one of the failure modes above and try to script a StubModel response that causes it on purpose, using the pattern in tests/test_example_agent_graphs.py.
7 current examples · Products, tools, and models that demonstrate this concept. A selection, not a ranking.
Graph framework
Maker’s documentation Checked 09/19/2026Agent framework
Maker’s documentation Checked 09/18/2026Agent framework
Maker’s documentation Checked 09/19/2026Multi-agent framework
Maker’s documentation Checked 09/19/2026Multi-agent framework
Maker’s documentation Checked 09/19/2026Protocol between agents
Maker’s documentation Checked 09/18/2026Agent harness SDK
Checked 09/19/2026A supervisor sends the task to a researcher, then chooses whether more research or a writing pass is needed.
Names listed 09/19/2026. 223 of 223 registry entries have been checked against the maker's own page; the registry marks the rest as unchecked.
Last reviewed 09/19/2026. Pages unreviewed for 90 days are flagged for another pass. Markdown version of this page