Skip to main content

Agent graph patterns

Use these patterns after completing your first graph. Refer to schema and governance when configuring the graph.

Design patterns​

Pick the pattern that matches how the information and the risk flow. Decompose by information: give each worker a scoped slice of the data, because agreement between agents that saw everything is weak evidence.

Router​

Router: classifier with single routing sends the request to one specialist, with a fallback to a general node

Use when requests fall into a few kinds and each needs different instructions or tools. Keep the classifier cheap and give every route a precise description. Always add a fallback edge.

Specialist and reviewer loop​

The graph in the tutorial. Use when a draft has checkable rules. Bound the loop on the edge, on the nodes and on the run, and give the exhausted case somewhere to go. An alternative with the same effect is a verification gate on the drafter with a __verify_failed__ edge to a remediation node.

Plan and execute (hub and spoke)​

Plan and execute: planner routes to workers, each worker returns to the planner

Use when the number and order of steps is not known in advance. A planner with routing_mode: single has one route per worker plus a done route; every worker has a deterministic edge back. The seeded graph meda-clinical-encounter.json has this shape: a plan node with eight routes, workers that return to it, per_node_max_visits of 24 on plan, max_total_steps 60, and a judge gate on the medication worker whose __verify_failed__ edge also returns to the planner. Because the planner can run many times, its visit cap is the most important guard in the graph.

Map and reduce with a join​

Map and reduce: split fans out to three workers, join edges feed one reducer

Use when independent pieces can be analysed separately and then combined. The split node has several outgoing deterministic edges (with fan_out_mode: all, the default, all of them fire). Each worker returns JSON with its own keys, and uses a join edge to the reducer. The reducer starts once, when all join edges have arrived. The seeded handoff-icu-pause.json joins six critique nodes into one qa node this way. By default scheduling is serial: the branches run one after another. Set scheduling.mode to parallel with max_parallel_workers of at least 2 to run them together; parallel branches work on copies of the state and are merged together after all succeed; two branches that write the same key with different values are a conflict error.

Escalation to a human​

Escalation: a failed verification routes to a human node, then a proposal node, then the final node

Use when a failed check or an urgent case needs a person. Route to a human_in_the_loop node from a __verify_failed__ edge, a fallback edge or a conditional edge such as state.urgent == true. Put the side effect (fhir.propose or a notification) in a node after the person, so nothing is written before they decide.

The ten most common mistakes​

The error text is what the publish check or Validate returns. The first nine were reproduced by running the real validator on the tutorial graph with one change each.

#MistakeError textFix
1No step limitguards.max_total_steps must be > 0Set Max Steps (for example 12).
2No entry or exit, or a wrong identry_node_id is required, at least one exit_node_id is required, entry_node_id "nope" does not match any nodeOn General, Set as entry and Mark as exit.
3A model node with no model or promptnode "draft" ("Drafter"): no model resolvable — set model_config_ref, inline_model_config, or agent_id ... and ... no prompt resolvable — set inline_prompt.template, prompt_ref.id, or agent_id ...Set the model on the Model tab and the prompt on the Prompt tab. A human-in-the-loop node needs them too.
4A gate with no failure routenode "draft" ("Drafter") has a verification gate but no outgoing "__verify_failed__" route edge for failed verdictsAdd a route edge named __verify_failed__ to a remediation node.
5A broken joinedge "j1": join edges require source "triage" to have routing_mode "none"; edge "j1": join edges cannot carry a condition (a false condition would deadlock the barrier); node "review" is the target of a single join edge — a barrier needs ≥2 join parents (use kind "deterministic" for a plain edge)Join only from none nodes, without a condition, with two or more parents.
6Model settings on a deterministic nodenode "finalize" ("Finalize"): handler_type is set — deterministic nodes must not declare model/prompt/agent config; also deterministic nodes cannot declare tool_refsRemove the model, prompt and tool settings, or drop handler_type.
7A route with no edge, or an edge to nothingLint: node "review" declares route "revise" but no route edge wires it (unwired_route); Studio: "Unresolved routes"Draw the edge or delete the route. Lint does not block publish, but the route would go nowhere.
8A prompt key that nothing providesLint: reference "patient_age" in node "draft" field "inline_prompt.template" is not defined at this point in the flow (unresolved_prompt_reference). At run time it prints <no value> and emits step.unresolved_vars.Add it to input_schema, have an upstream node return it, or fix the typo.
9A loop with no boundRun time: node "x" exceeded max_visits=N, or the run stops at max_total_stepsSet max_traversals on the back edge and per_node_max_visits. Studio warns "Loop guard advised".
10Wrong limits and settingsnode "draft" ("Drafter"): at most 3 fallback_models; fallback_models[0] needs an id and a version; tool_refs[0] has no tool id; pick a tool or remove the entry; max_tool_rounds must be between 1 and 20 (0 uses the default 5); scheduling.max_parallel_workers must be >= 2 in parallel mode; guards.max_active_nodes must not exceed guards.max_total_steps; compliance.data_classification must be none, pseudonymised, or phi; execution_mode "rlm" requires rlm.context_state_keys; duplicate node id "draft"; edge "e1": target_node_id "ghost" not foundFix the named field.

Two mistakes produce no error: a router prompt that does not make the choice clear (the model returns an undeclared route name, so fallback fires), and workers that return plain text (they overwrite text, or fail with a state conflict in parallel mode). Give routes clear descriptions and give each worker its own JSON key.

note

output_schema on a node is not enforced at run time. Its properties names tell the editor and the lint which keys the node produces, so a downstream {{.key}} is accepted. It does not make the model obey the schema; say what you need in the prompt.

Something unclear? Send documentation feedback by email.