Build your first agent graph
Build a five-node reply-drafting example with a router, a bounded reviewer loop and a human handoff. You will learn how to connect nodes, publish a version and inspect the path taken by a run.
Before you start: you need permission to read and edit agent graphs and access to the models used by the example. Use synthetic messages throughout this tutorial. Allow about an hour.
For every control and schema field, see Agent graph reference. For other layouts and common mistakes, see Agent graph patterns.
Decide: graph, agent or workflow
| You need | Use | Why |
|---|---|---|
| One persona that answers or chats, maybe with tools | A single agent | Cheapest to build and run. A graph adds latency and review surface for no gain. |
| An LLM that decides at run time which specialist to call | An agent with sub_agents | Each sub-agent is exposed to the parent as a tool. Four agents in the seeded catalog declare sub_agents (for example clinical-workflow-orchestrator); they are agents, not graphs. |
| A fixed or branching multi-stage flow where you must show every intermediate step, use a different model per stage, pin prompts, add a reviewer, or put deterministic steps between model steps | An agent graph (this page) | One Step row per activation, pinned versions, gates, replay. |
| Data movement and transformation with no reasoning (ETL, HL7 to FHIR) | A workflow or pipe | Do not spend model calls on plumbing. See Build any workflow. |
| A product feature with rows, sign-off queues and hours-long reviews | A graph plus a service of your own | The engine's human pause lives in one process (safety and governance). Use it for minutes, not days. |
Rule of thumb from the design guide: if a clinician or auditor will ever ask "why did it say that?", use a graph. If one agent does the job, do not.
A graph can still use workflow nodes: the bridged handlers fhir.read, fhir.propose, fhir.write, notify.send and script.run run pipeline nodes (or a fixed script) as deterministic steps (graph anatomy).
Tutorial: a reply drafter with a router and a reviewer loop
You will build a five-node graph for a clinic: it reads a patient portal message, routes urgent ones to a nurse, drafts a reply for routine ones, has a reviewer check it (up to two rewrites), and hands over to a nurse if the reviewer keeps refusing.
Design first
Write down, before you open the Studio:
| Question | Answer for this graph |
|---|---|
| What must be true of every reply? | No diagnosis, no medication doses, no promises about timing, under 120 words. |
| Who decides what? | A router decides urgency. A different, stronger model reviews. A person handles anything urgent or anything the loop cannot settle. |
| What is deterministic? | Nothing here. A real clinic graph would add a fhir.read node to fetch context rather than let a model fetch it. |
| What are the loops and how are they bounded? | draft and review can repeat: max_traversals 2 on the revise edge, per_node_max_visits 3, max_total_steps 12. |
| What is the safety class? | It affects clinical communication, so affects_clinical_output is true. The engine treats it as clinical (safety and governance). |
The definition
Download the complete example definition. The retained backend audit checked this definition with the same Validate() and Lint() used at publish time. Select models available in your organization and validate again before publishing on your deployment.
View the complete JSON definition
{
"entry_node_id": "triage",
"exit_node_ids": [
"finalize"
],
"guards": {
"max_total_steps": 12,
"max_model_calls": 14,
"max_retry_attempts": 4,
"per_node_max_visits": {
"draft": 3,
"review": 3
}
},
"compliance": {
"regulated": false,
"affects_clinical_output": true,
"data_classification": "none"
},
"metadata": {
"owner": "Demo Hospital",
"tags": [
"tutorial",
"portal-reply"
]
},
"intended_use": {
"statement": "Drafts a reply to a patient portal message for clinic staff to review before anything is sent.",
"intended_users": [
"Clinic nurse"
]
},
"input_schema": [
{
"key": "query",
"label": "Patient message",
"type": "text",
"required": true,
"description": "The text of the portal message. Use synthetic text only."
}
],
"examples": [
{
"name": "Refill question",
"input": {
"query": "Hello, this is Test Patient A. Can I get my usual refill sent to the pharmacy on Main Street?"
}
},
{
"name": "Urgent symptom",
"input": {
"query": "Test Patient B here. Since this morning I have chest pain that spreads to my arm."
}
}
],
"nodes": [
{
"id": "triage",
"name": "Triage",
"description": "Decides whether the message is routine or urgent.",
"routing_mode": "single",
"routes": [
{
"name": "routine",
"description": "Administrative or non-urgent question that a nurse can answer in writing."
},
{
"name": "urgent",
"description": "Any symptom that could need same-day clinical attention."
}
],
"inline_model_config": {
"provider": "google",
"model_name": "gemini-2.5-flash",
"temperature": 0.1
},
"inline_prompt": {
"template": "You triage patient portal messages for Demo Hospital.\nMessage: {{.query}}\n\nReturn JSON with the key \"category\" (one short label such as refill, appointment, results, symptom) and choose the route. When in doubt, choose urgent."
},
"output_schema": {
"type": "object",
"properties": {
"route": {
"type": "string"
},
"category": {
"type": "string"
}
}
},
"retry_policy": {
"max_attempts": 2,
"backoff_ms": 500
}
},
{
"id": "draft",
"name": "Drafter",
"description": "Writes the reply, and rewrites it when the reviewer asks for changes.",
"routing_mode": "none",
"inline_model_config": {
"provider": "google",
"model_name": "gemini-2.5-flash",
"temperature": 0.3
},
"inline_prompt": {
"template": "Write a short reply (under 120 words, plain text) to this patient portal message for a nurse to review.\nMessage: {{.query}}\nCategory: {{.category}}\n{{if .feedback}}\nA reviewer rejected the previous draft.\nReviewer feedback: {{.feedback}}\nPrevious draft: {{.text}}\nRewrite the draft and fix every point.\n{{end}}\nRules: no diagnosis, no medication doses, no promises about timing."
},
"retry_policy": {
"max_attempts": 2,
"backoff_ms": 500
}
},
{
"id": "review",
"name": "Reviewer",
"description": "Checks the draft against the rules and approves it or asks for a rewrite.",
"routing_mode": "single",
"routes": [
{
"name": "approve",
"description": "The draft follows every rule."
},
{
"name": "revise",
"description": "The draft breaks a rule; explain what to fix in \"feedback\"."
}
],
"inline_model_config": {
"provider": "google",
"model_name": "gemini-2.5-pro",
"temperature": 0
},
"inline_prompt": {
"template": "You review a draft reply to a patient portal message.\nMessage: {{.query}}\nDraft: {{.text}}\n\nRules: no diagnosis, no medication doses, no promises about timing, under 120 words.\nReturn JSON with the keys \"route\" and \"feedback\". Put the specific problems in \"feedback\" when you choose revise, and an empty string when you choose approve."
},
"output_schema": {
"type": "object",
"properties": {
"route": {
"type": "string"
},
"feedback": {
"type": "string"
}
}
},
"retry_policy": {
"max_attempts": 2,
"backoff_ms": 500
}
},
{
"id": "escalate",
"name": "Nurse takes over",
"description": "Pauses the run until a nurse supplies the reply text.",
"routing_mode": "none",
"human_in_the_loop": true,
"inline_model_config": {
"provider": "google",
"model_name": "gemini-2.5-flash"
},
"inline_prompt": {
"template": "Human review step. The reply is supplied by a person: {{.query}}"
}
},
{
"id": "finalize",
"name": "Finalize",
"description": "Applies the clinic sign-off format to the approved text.",
"routing_mode": "none",
"inline_model_config": {
"provider": "google",
"model_name": "gemini-2.5-flash",
"temperature": 0
},
"inline_prompt": {
"template": "Return the reply below unchanged, followed on a new line by: \"Reviewed by clinic staff before sending.\"\n\n{{.text}}"
}
}
],
"edges": [
{
"id": "e1",
"source_node_id": "triage",
"target_node_id": "draft",
"kind": "route",
"route_name": "routine"
},
{
"id": "e2",
"source_node_id": "triage",
"target_node_id": "escalate",
"kind": "route",
"route_name": "urgent"
},
{
"id": "e3",
"source_node_id": "triage",
"target_node_id": "escalate",
"kind": "fallback"
},
{
"id": "e4",
"source_node_id": "draft",
"target_node_id": "review",
"kind": "deterministic"
},
{
"id": "e5",
"source_node_id": "review",
"target_node_id": "finalize",
"kind": "route",
"route_name": "approve"
},
{
"id": "e6",
"source_node_id": "review",
"target_node_id": "draft",
"kind": "route",
"route_name": "revise",
"max_traversals": 2
},
{
"id": "e7",
"source_node_id": "review",
"target_node_id": "escalate",
"kind": "fallback"
},
{
"id": "e8",
"source_node_id": "escalate",
"target_node_id": "finalize",
"kind": "deterministic"
}
]
}
Build it in the Studio
- Open Tiet · Agentic, Agents, Agent Graphs, and select New graph. Name it
Portal reply drafter, then Create. Create a version1.0.0with New version if the Studio did not. - On the Info tab set the description, under Guards set Max Steps to
12. Open Usage and fill Intended use and Intended users, add a run inputquery(type text, required) and two Example presets (a refill question and an urgent symptom). - Add five nodes with + Node, choosing Inline node each time:
triage,draft,review,escalate,finalize. Give each its Display name. - On
triage: Routing tab, modesingle, routesroutineandurgentwith descriptions. Model tab, a small fast model. Prompt tab, the template from the JSON. On General, click Set as entry. - On
draftandfinalize: model and prompt only. Onfinalizeclick Mark as exit. - On
review: modesingle, routesapproveandrevise, and a stronger model than the drafter. Use a different model from the drafter so one model does not approve its own work. - On
escalate: switch on Human-in-the-loop. Keep an inline model and prompt; the Studio and the publish check still ask for them. - Draw the edges with the edge tools. Choose Route and drag from the
triageroute handles todraft(routine) andescalate(urgent). Choose Fallback and connecttriagetoescalate. Chain connectsdrafttoreview. Fromreview, Routeapprovetofinalizeandreviseback todraft; click thereviseedge and set Max Traversals to2. Fallback fromreviewtoescalate. Chainescalatetofinalize. - Click Validate. You want "Entry & exit defined", "All 5 nodes reachable" and "All routes resolve", with no errors.
- Click Save, then Publish.
Run it
- Click Run. In Run graph, choose the preset "Refill question" and run.
- Watch Events. The expected path is
triage(routeroutine),draft,review, thenfinalize. If the reviewer asks for a rewrite you seedraftandreviewagain. - Open Step Inspector on
draft. Check Resolved prompt: the message and category are filled in. On the first pass you will also see astep.unresolved_varsevent fordraftthat listsfeedbackandtext. That is expected here, because the{{if .feedback}}block reads keys that only exist after a reviewer rejection. The text inside the block is not sent. - Run the "Urgent symptom" preset. The run goes to
escalateand pauses with statuspaused. Submit a payload such as{"text": "Synthetic review complete. Route this test message to the demonstration review queue."}in Human Review Required. The run continues tofinalizeand ends. - To test the loop on purpose, set the reviewer's prompt to reject everything. After two rewrites the
reviseedge is used up, no route matches, and the fallback edge sends the run toescalate.
Why it is built this way
- The reviewer returns JSON with
routeandfeedback.routeis consumed by the engine; the reply text intextis untouched, sofinalizestill reads the drafter's text. - The loop is bounded three ways: the edge, the node and the whole run. Use all three.
- The fallback edges mean no model mistake can leave the run with nowhere to go.
escalateneeds no reasoning, but the person's words becometext, sofinalizehandles both paths with one prompt.
Next steps
- Agent graph reference: controls, schema, lifecycle, governance and execution inspection.
- Agent graph patterns: routing, review loops, joins and common mistakes.
Something unclear? Send documentation feedback by email.