Agent graph reference
Controls, schema fields, execution lifecycle and limits for Graph Agent Studio. For a guided example, start with Build your first agent graph.
Tour of Graph Agent Studio
Open it from Tiet · Agentic, then Agents, then the Agent Graphs tab (the tab shows the number of graphs, for example "Agent Graphs (3)"; its address is /studio/graphs). Pick a graph in the list or create one with the New graph button (title "New graph", dialog "New Graph", field placeholder "e.g. QA + Writer Pipeline", button Create).
Toolbar
| Control | What it does |
|---|---|
| New graph / New version (icon buttons) | Create a graph, or a new version (placeholder 1.0.0). |
| + Node (label "Node", tooltip "Add a node") | Add a node. Disabled on a published version: "Published versions are immutable — fork a draft first". |
| Draft (tooltip "Draft this graph from a description") | AI drafts a graph from a description you type. Review the result before you trust it. |
| Save | Shows Unsaved, Saved or Save error. On a published version the tooltip says "Published versions are immutable — Save will create a new draft (forks the current version)". |
| Publish | Publishes the version. Tooltip: "Publish this version (required to run)". Disabled if already published. |
| Validate | Tooltip: "Validate graph structure (entry/exit, reachability, routes, loops)". Shows errors and warnings in the editor. |
| Run (split button) | Run ("Execute the full graph") and, in the caret menu, Debug step-by-step ("Pause at each node"). Disabled until a version is published. A dialog titled "Run graph" or "Debug run" asks for the input (a Form from your input_schema, or Raw JSON, and a Preset list if you saved examples). |
| Pause, Cancel | Appear while a run is active. |
Superusers also see a Catalog button that shares a published graph with every organization.
Left panel: Nodes and Palette
Nodes lists the nodes of the open version with a search box. Palette lists what you can drop on the canvas:
| Section | Entries |
|---|---|
| Core | Existing Agent, Inline LLM, Tool Agent, Planner |
| Routing | Router (single route, two routes pre-filled), Multi Router (several routes, fan-out), Verifier Gate (verification gate plus the __verify_failed__ route) |
| Runtime | Human Review (human-in-the-loop checkpoint), Memory Agent, Attachment Reader |
| Deterministic | One entry per deterministic handler the server reports, named by its handler_type |
Edge tools
Above the canvas you choose how the next connection you draw behaves:
| Tool | Meaning (tooltip) |
|---|---|
| Auto | Infer route or fallback from the source port |
| Chain | Deterministic edge |
| Parallel | Fan-out edge with graph fan_out_mode=all |
| Cycle | Bounded back edge with max traversals |
| Route | Route edge from a named route |
| Fallback | Fallback edge |
| Join | Join edge for fan-in |
| Condition | Deterministic edge that opens the condition editor |
Clicking an edge opens its dialog: Source node, Target node, Kind (Deterministic, Route, Fallback, Join), Route Name, a condition, Transform, Priority and Max Traversals. The canvas also has zoom, Fit view, Auto-arrange nodes, and an edge Routing switch (Smart or Curved).
Node inspector
Click a node to open the inspector in the right panel. Its tabs are General, Model, Prompt, Tools, Memory, Routing and Verify.
| Tab | What you set |
|---|---|
| General | Display name, description, Set as entry / Entry node, Mark as exit / Exit node, toggles Human-in-the-loop, Receive attachments, Memory, the Memory backend (Inherit, Flat, Memora, shown with the Memory toggle), the Prompt-injection defence choice (Inherit, Platform directive, Custom directive, Off), Max retries, Timeout (ms). |
| Model | Language model, Max tokens, Streaming; for RLM and ParSer nodes the execution mode and their fields. |
| Prompt | System Prompt (a Go template over shared state). |
| Tools | Add tool from the organization's tool catalog, Add skill. |
| Memory | The memory-control editor (tab label "Memory"). |
| Routing | Routing mode (none, single, multi) and the route list (name plus a description shown to the model). |
| Verify | Verification gate with Mode (judge, grounded, consensus), Evidence state keys, Verifiers, Pass threshold, Min confidence, Verifier model, Candidate key, Rubric. |
When you add a node you either reference an existing agent, create a New agent, or choose Inline node ("A node with its own inline prompt + model — no agent record needed"). A deterministic node (from the Deterministic palette section) has no model, prompt or tools.
Right panel
Tabs: Info, Usage, History, API, Assistant.
- Info: graph name and description, Guards (Max Steps, Fan-Out Mode, Scheduling, Workers), Prompt-injection defence (Boundary directive), Runtime patterns (which edge kinds the graph uses), Medical inference (Expose to inference, Default engine).
- Usage: Intended use, Intended users, Run inputs (your
input_schema), Example presets. - History: past runs with their steps and tool calls.
- API: ready-made
curl, TypeScript and Python snippets, and a button to create a token scoped tograph:<id>:execute. - Assistant: a copilot that answers questions or generates a graph for a task.
Bottom panel and debug
Bottom tabs: Events (n), Step Output, Step Inspector, Trace, Variables. The Step Inspector shows Input, Output, Resolved prompt, Thinking, the verification record and Tool calls (n). Trace links to the Trace Explorer (full span tree, cost, retries, nested runs).
In a debug run the debug panel has Continue (F5), Step over (F10), Step into (F11) and Stop, plus three tabs: Overrides (Override route, Mock tool call, edit the input and Apply & Continue), Step Inspector (with Rerun step) and Breakpoints. Breakpoint kinds are before_node, after_prompt_render, before_tool_call, after_tool_call and after_node; leave the node ID blank to stop at all nodes.
A run that reaches a human-in-the-loop node opens a dialog titled Human Review Required with a Payload (JSON) field and Skip and Submit buttons.
Anatomy of a graph
The Studio edits one JSON document, the definition. You can read and write it through the API (the version endpoint accepts {"version": "1.0.0", "definition": {...}}). Everything below is a field of that document.
Top-level fields
| Field | Meaning | Rule |
|---|---|---|
entry_node_id | First node to run | Required, must match a node. |
exit_node_ids | Nodes where the run can end | At least one; each must match a node. The answer is the exit node's text. |
nodes, edges | The graph | Ids unique; every edge needs an id and existing source and target. |
guards | Hard limits (below) | max_total_steps is required and must be greater than 0. |
fan_out_mode | all (default), first, by_priority | How several matching non-route edges from one node behave. first and by_priority fire the lowest priority number. |
scheduling | mode serial (default) or parallel, max_parallel_workers | Serial needs workers 0. Parallel needs at least 2 and not more than the active-node limit. |
compliance | regulated, affects_clinical_output, data_classification (none, pseudonymised, phi), research_only | No block means "clinical" (safety and governance). |
input_schema | Typed run inputs: key, label, type (string, text, number, boolean, json), required, default, description, enum | Drives the run form. Empty means one free-text query. |
examples | Saved input presets (name, description, input) | Shown as Preset in the run dialog. |
intended_use | statement, intended_users | Documentation, versioned with the graph, not enforced. |
metadata | owner, tags, protocol_ref, schedule_permission | Not used by the engine. |
variables, shared_state_schema | Declarations of what flows through the graph | Declaration only. A variable needs a lower-case name, a description, a known type and source. |
prompt_defense | Graph-level default for the injection defence | A node can override it. On by default. |
Node kinds
Every node has id, name (both required), an optional description and canvas position. The kind is decided by what else you set.
1. Model node (LLM). The default. It needs a model and a prompt, each from exactly one place:
| Need | Options |
|---|---|
| Model | inline_model_config (provider, model_name, temperature, max_tokens), or model_config_ref (id, version), or agent_id (the agent's own model). |
| Prompt | inline_prompt.template, or prompt_ref (id, version), or agent_id (the agent's prompt, used as written, followed by ## Input and the previous text). |
Other fields: tool_refs (id, version, optional allowed_urls), skill_slugs and skill_refs, max_tool_rounds (default 5, at most 20), fallback_models (safety and governance), retry_policy (max_attempts, backoff_ms, retry_on), timeout_ms, thinking_tokens (a ceiling, not a switch), routing_mode and routes, verification, checks, memory_config, record_only, accept_attachments, inherit_agent_tools, access_requests, retry_safe, output_schema (see the note in common graph mistakes).
2. Deterministic node. Set handler_type and handler_config. The engine runs registered code instead of a model. It must not declare a model, prompt, agent, tool_refs, max_tool_rounds, fallback_models, checks or verification. It still gets retries, a timeout, a Step row, breakpoints and events. Built-in handler types:
handler_type | Does | Effect class |
|---|---|---|
fhir.read | FHIR search or read. A search needs at least one filter. | read |
fhir.propose | Creates or updates FHIR resources only in a draft or proposed state. A PUT needs ifMatch. | propose |
fhir.write | Any FHIR operation | write (autonomous runs only) |
notify.send | Slack or webhook message | write |
script.run | A fixed Python script. It reads its inputs as context and assigns a dict to output. | read |
The server also registers domain handlers (for example record.build, record.snapshot, signal.infer). The Deterministic palette section lists what your server offers.
A bridged handler is configured like this (from the design notes):
{"id": "fhir_slots", "name": "Find slots", "handler_type": "fhir.read",
"handler_config": {"config": {"operation": "search", "resource_type": "Slot"},
"inputs": {"search_params": "val.slot_search"},
"optional_inputs": {}, "values": {}, "output_key": "slots"}}
inputs maps a handler port to a shared-state path; a missing path fails the step. The result is merged into shared state under output_key. Handlers that propose or write run once and ignore retry_policy.
3. RLM node. execution_mode: "rlm" plus rlm.context_state_keys (required, no empty or repeated keys). The model works over large inputs in a code environment instead of reading them in the prompt. It cannot be combined with handler_type.
4. ParSer node. execution_mode: "parser" plus a parser block (context keys or attachment sources, a reader model, turn and chunk limits). Cheap reader models quote from long records. Publish refuses a graph whose guards.max_model_calls cannot cover one activation. The seeded example is parser-long-record-qa.json in the tietai-hydra-platform repository.
5. Human-in-the-loop node. human_in_the_loop: true. The run pauses until a person submits a JSON payload, which becomes the node's output. It still needs a model and prompt to pass validation (they are not used while it waits), and it cannot have a verification gate.
Edges
| Field | Meaning |
|---|---|
kind | deterministic (default; always fires, optionally guarded by condition), route (fires when the source's output picks route_name), fallback (fires when no route edge matched), join (barrier). |
route_name | Required for route edges. |
condition | A guard evaluated after the kind matches. Syntax: dot paths over output. (the node that just ran) and state. (shared state), ==, !=, <, >, <=, >=, &&, ` |
transform | { key: path, ... }, maps source output to target input. Empty passes the output through. |
priority | Lower number wins when fan_out_mode is first or by_priority. |
max_traversals | How often this edge may fire in one run. 0 is unlimited. |
Join edges make a barrier: the target runs once, when every join edge into it has arrived. The engine keeps arrivals across pauses and restarts. Rules checked at publish: the source node must have routing_mode none or empty, a join edge cannot have a condition, and a join target needs at least two join parents.
Routing modes
routing_mode | The model must return | Edges that fire |
|---|---|---|
none (or empty) | nothing special | The non-route edges whose condition holds. |
single | JSON with "route": "<name>" | The route edge with that route_name. |
multi | JSON with "route": ["a", "b"] | Every route edge named in the list. |
You do not need to describe the format in your prompt: when a node has routes, the engine appends ROUTING INSTRUCTIONS to the rendered prompt, listing each route and its description. Write good route descriptions; they are the instruction. If no route edge matches (the model returned an unknown name, or the matching edge has used all its max_traversals), fallback edges fire. An optional route_reason string is recorded with the decision. A route edge and a declared route should match: the Studio Validate reports "Unresolved routes" for an edge whose route is not declared, and a declared route with no edge is a lint error (unwired_route). The one exception is __verify_failed__, which you do not need to declare.
Shared state
All nodes read and write one JSON object, the shared state.
- Your
initial_inputkeys seed it (queryis the default key). - When a node finishes, its output is merged in by top-level key. If the model returned a JSON object, each key becomes a state key. Otherwise its text goes under
text. A later node that writes the same key replaces it. - A prompt reads any key as
{{.key}}(Gotext/template). A missing key prints<no value>; test with{{if .key}}...{{end}}when a key is optional. - The run's answer is the exit node's
text.
Two consequences matter when you design: a node that returns only routing JSON (route, feedback) leaves the previous text in place, and two nodes that both return plain text overwrite each other's text. In parallel scheduling, two branches writing the same key with different values fail the run with parallel branch state conflict for key "text" from nodes [...]. Give each parallel worker its own JSON key. The engine owns response_language, __verification_failure__, __attachments__ and __attachment_refs__, and it derives the attachment flags has_attachments, has_image_attachments, has_dicom_attachments, has_signal_attachments and has_lab_documents from the request's files before the first node runs; do not write them, but do route on them in edge conditions (for example state.has_dicom_attachments == true). A DICOM file also counts as an image for has_image_attachments, yet an LLM node never receives its pixel data (only a one-line note with its header facts), so send DICOM straight to a DICOM-capable deterministic node, with that edge given a lower priority number than the image edges so it wins.
Guards
| Guard | Meaning |
|---|---|
max_total_steps | Required, greater than 0. Hard cap on node activations in a run. |
per_node_max_visits | Map of node id to maximum visits. |
max_model_calls | Cap on model requests, including retries, tool rounds and verifier calls. |
max_total_tokens, max_cost_usd | Token and cost ceilings. Cost needs complete model pricing. |
max_retry_attempts | Retries after the first attempt across the run. |
max_active_nodes | Queued fan-out width. Must not exceed max_total_steps. |
max_tool_result_bytes | Archives large tool results and shows the model a digest. Off by default. |
untrusted_fence, repeat_advisory, wrap_up_turn | Opt-in protections, off by default. wrap_up_turn makes one extra model call when a node uses all its tool rounds. repeat_advisory warns the model when it repeats an identical tool call. |
max_child_executions, max_recursion_depth | Limits for nested runs. |
A run that passes per_node_max_visits fails with node "x" exceeded max_visits=N. Cycles are allowed; these guards are what stop them. The Studio Validate warns "Loop guard advised: The graph contains a cycle — Max Steps (N) will bound it".
Draft, publish, run, replay
| Stage | What happens |
|---|---|
| Draft | Mutable. Saving a draft does not validate it. Errors appear when you publish or click Validate. |
| Publish | Runs Validate() and the invariant policy. An error returns status 422 with the message. Publishing can also be refused by a compliance gate (409, "compliance gate: ...") or, when permission review is enforced, by a review that asks you to confirm that the version widens what the graph can reach or do. A published version never changes. |
| New version | Saving on a published version forks a draft. Pick a new semver for it. |
| Run | Needs a published version. You choose the version; the run records it. |
| Replay | POST .../executions/{id}/replay with a step_id (and optional input or state overrides) creates a child run that starts at that step with the saved state. rewind moves the same run back to a step. The Studio has no replay button for graphs; use the API. Rerun step in the debug panel is the interactive version. |
What is pinned
model_config_ref,prompt_refandtool_refscarryidandversion. Aprompt_refversion can belatest; the engine resolves it once at run start, stores the result asresolved_prompt_versions, and a replay uses that map as is.inline_promptandinline_model_configare part of the published definition, so they are frozen with it.- A node that only names an
agent_iduses that agent's deployed configuration. Agents have their own versions (draft, deploy, frozen once deployed). Tool and skill assignments on an agent are not versioned, and a bareskill_slugsentry follows the live skill. Useskill_refswith a version to pin it. - A replay runs under the same autonomy ceiling as the original.
What replay guarantees: the same graph version, the same pinned prompt versions, the same starting state. What it does not: identical output. Model output can vary between runs, and tools may return new data.
Safety and governance
Autonomy ceiling
Every run has a ceiling that limits what its tools and handlers may do:
| Ceiling | Allows | Chosen when |
|---|---|---|
research_only | read | compliance.research_only is true. Such a run cannot be bound to a conversation or consult. |
propose | read and propose | The graph is regulated, affects clinical output, or has no compliance block (no block counts as clinical). |
autonomous | everything | A compliance block that is neither regulated nor clinical. |
A nested run takes the stricter of its own and its parent's ceiling. The propose ceiling is only enforced when the server runs with HYDRA_AUTONOMY_ENFORCEMENT=enforce. By default it runs in audit mode: would-be denials are recorded and allowed. The pilot-clinical profile requires enforce. A denial emits step.tool_denied. Ask your administrator which mode your environment uses before you rely on the ceiling.
Side-effect classes
Handlers are classified by effect: fhir.read and script.run read; fhir.propose proposes; fhir.write and notify.send write. Under a propose ceiling a graph can propose a draft or proposed FHIR resource but not write a final one. Put each side effect in its own node after the node that decides, never in the same step as the model. Propose and write handlers run once and ignore retries, so a lost response cannot repeat a change.
Verification gates
Set verification on a model node to check its output before it reaches shared state:
| Mode | Checks |
|---|---|
judge | A verifier scores the candidate against your rubric. |
grounded | Every claim must be supported by the shared-state keys listed in grounding_state_keys (empty means the whole state). |
consensus | verifiers independent verifiers (default 3, at most 7) vote. pass_threshold (default 0.5) is the share that must pass. |
Other fields: min_confidence, candidate_key (default text), verifier_model (use a different model from the node), categorize, expose_candidate_on_failure. A failing verdict retries the node up to retry_policy.max_attempts. Then the candidate is withheld: none of its keys are written, the engine writes a __verification_failure__ record (node, attempts, mode, confidence, rationale, unsupported claims, a hash of the candidate), and the node's __verify_failed__ route fires. The node must have an outgoing route edge named __verify_failed__ or publish fails. A gate is not allowed on a deterministic or human-in-the-loop node. expose_candidate_on_failure is allowed only if every __verify_failed__ target is a deterministic or human-in-the-loop node, so no model can polish a rejected answer into a final one.
Human pause
human_in_the_loop parks the run (execution.paused, reason human_in_the_loop) until a payload arrives (POST .../executions/{id}/human_input with node_id and payload, which is what Submit does). Know the limits:
- The wait is held in one server process and has no wait limit of its own. A server restart can lose it.
- With
HYDRA_GRAPH_DURABLE_RUNS=true(off by default) and a node markedretry_safe, runs survive restarts for tool-approval and access-request pauses. Ask your administrator whether it is on. - For hours-long reviews (sign-off queues), keep the review as a record in a service of your own and start a second graph run when it is done.
Other controls
fallback_models: up to 3{id, version}model refs, tried in order when the call fails with rate limit, timeout or 5xx, transport error, payment required or model not found. Never on auth errors or bad requests. You choose them; the workflow engine never swaps models silently. Each hop is checked against the PHI egress policy. Recorded asstep.model_fallback. Standard model nodes only.checks: rules on a node's tool calls (deny a call whose arguments match, or require an earlier successful call).record_only: limits a drafter to terminology tools so it cannot read live FHIR.- Mandatory invariant block: for clinical activations the engine appends a
<mandatory_invariant_core>block as the last section of every model node's prompt. You cannot write that tag in a prompt (publish returns 422 with the messageprompt contains the reserved <mandatory_invariant_core> tag).invariant_exemptionneeds a reason of at least 20 characters and a reference, and is refused under the pilot-clinical profile. Do not try to reproduce or weaken the block in your own prompt. - Prompt-injection defence: on by default. Input is treated as data; suspicious input emits
step.prompt_injection. - Spend:
max_model_calls,max_total_tokensandmax_cost_usdstop a run that costs more than you planned.
Clinical checklist before you publish
compliancefilled in honestly; no block means clinical.intended_usestates who uses the output and that a clinician reviews it.- Every model output that matters has a gate, a deterministic check, a reviewer or a person.
- Every loop has
max_traversals,per_node_max_visitsandmax_total_steps. - Side effects are in their own deterministic nodes.
- You ran it on synthetic data, in debug mode, and read every Resolved prompt.
Reading a run
Every run produces an ordered event log. Open Events (n) in the bottom panel, or read it through GET .../executions/{id}/events and the stream .../stream.
| Event | Meaning |
|---|---|
graph.execution.started, execution.completed | Run boundaries. |
step.started, step.completed, step.failed, step.retried | One node activation. A retry means the first attempt failed or its output was empty or unusable. |
step.tool_called, step.tool_returned | A tool call and its result. |
execution.paused, execution.resumed, execution.cancelled | Human pause, resume, cancel. |
execution.paused_at_breakpoint | A debug breakpoint was hit. |
step.verified | A verification verdict. |
step.tool_denied, step.check_denied, step.approval_required | A governance control stopped a tool call. |
step.model_fallback | A fallback model was used. |
step.unresolved_vars | A prompt referenced a key that was missing. It printed <no value>. |
step.rounds_exhausted, step.repeat_advisory, execution.budget_exhausted | A loop or spend limit. |
step.invariant_core, step.phi_egress, step.prompt_injection | Safety controls recorded their decision. |
execution.replayed, execution.rewound | A replay or rewind started. |
Run status goes pending, running, paused, then succeeded, failed or cancelled.
When an answer is wrong, work backwards:
- Find the first step that failed or that produced the wrong value. Step Inspector shows Input and Output.
- Read its Resolved prompt. Is every
{{.key}}filled? Is a<no value>in there? - Read Output. Did a router return a route name you did not declare?
- Read Tool calls. Did a call return an error or an empty result?
- Open Trace for cost, retries and nested runs.
- Fix the prompt in a new version, publish it, and run the same input again. Compare the runs in History.
Test before you publish
- Validate, then fix every error. Read the warnings.
- Run with Debug step-by-step. Set
after_prompt_renderbreakpoints to read each prompt, use Override route to force a branch, and Mock tool call to avoid real tools. - Test every edge, not just the happy path: force each route, force a revise loop to its limit, return an empty tool result.
- Save your test inputs as Example presets so every version is run against the same cases.
Limits
- Graph Agent Studio labels are fixed English text in the source; they are not translated.
- There is no Studio button for replay or rewind; use the API or Rerun step in debug.
- There is no dedicated retrieval (RAG) node. Use skills, memory settings, RLM or ParSer nodes for long documents, or a handler that fetches data into shared state.
- Runtime enforcement of
max_child_executionsandmax_recursion_depthis described in the source as not active in one policy slice; do not rely on them to stop nested runs. - The human pause is in-process (safety and governance).
- The autonomy ceiling is advisory (audit mode) unless your server runs with
HYDRA_AUTONOMY_ENFORCEMENT=enforce.
Something unclear? Send documentation feedback by email.