Skip to main content

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 needUseWhy
One persona that answers or chats, maybe with toolsA single agentCheapest to build and run. A graph adds latency and review surface for no gain.
An LLM that decides at run time which specialist to callAn agent with sub_agentsEach 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 stepsAn 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 pipeDo not spend model calls on plumbing. See Build any workflow.
A product feature with rows, sign-off queues and hours-long reviewsA graph plus a service of your ownThe 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.

Reviewer loop: drafter to reviewer, approve to final, revise back to drafter at most twice, then fallback to a human

Design first​

Write down, before you open the Studio:

QuestionAnswer 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​

  1. Open Tiet · Agentic, Agents, Agent Graphs, and select New graph. Name it Portal reply drafter, then Create. Create a version 1.0.0 with New version if the Studio did not.
  2. 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 input query (type text, required) and two Example presets (a refill question and an urgent symptom).
  3. Add five nodes with + Node, choosing Inline node each time: triage, draft, review, escalate, finalize. Give each its Display name.
  4. On triage: Routing tab, mode single, routes routine and urgent with descriptions. Model tab, a small fast model. Prompt tab, the template from the JSON. On General, click Set as entry.
  5. On draft and finalize: model and prompt only. On finalize click Mark as exit.
  6. On review: mode single, routes approve and revise, and a stronger model than the drafter. Use a different model from the drafter so one model does not approve its own work.
  7. On escalate: switch on Human-in-the-loop. Keep an inline model and prompt; the Studio and the publish check still ask for them.
  8. Draw the edges with the edge tools. Choose Route and drag from the triage route handles to draft (routine) and escalate (urgent). Choose Fallback and connect triage to escalate. Chain connects draft to review. From review, Route approve to finalize and revise back to draft; click the revise edge and set Max Traversals to 2. Fallback from review to escalate. Chain escalate to finalize.
  9. Click Validate. You want "Entry & exit defined", "All 5 nodes reachable" and "All routes resolve", with no errors.
  10. Click Save, then Publish.

Run it​

  1. Click Run. In Run graph, choose the preset "Refill question" and run.
  2. Watch Events. The expected path is triage (route routine), draft, review, then finalize. If the reviewer asks for a rewrite you see draft and review again.
  3. Open Step Inspector on draft. Check Resolved prompt: the message and category are filled in. On the first pass you will also see a step.unresolved_vars event for draft that lists feedback and text. 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.
  4. Run the "Urgent symptom" preset. The run goes to escalate and pauses with status paused. 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 to finalize and ends.
  5. To test the loop on purpose, set the reviewer's prompt to reject everything. After two rewrites the revise edge is used up, no route matches, and the fallback edge sends the run to escalate.

Why it is built this way​

  • The reviewer returns JSON with route and feedback. route is consumed by the engine; the reply text in text is untouched, so finalize still 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.
  • escalate needs no reasoning, but the person's words become text, so finalize handles both paths with one prompt.

Next steps​

Something unclear? Send documentation feedback by email.