Trigger, Context, Model, Tools, Review
The five parts every agent workflow is built from, and why drawing them explicitly prevents most of the fragility that shows up in production.
An agent is a system, not a prompt
The single biggest mistake engineers make is treating an agent as a clever prompt. In production it is a system with distinct parts, and each part fails differently. A webhook drops, a CRM read times out, the model returns malformed JSON, a tool call hallucinates an ID, a reviewer never sees the draft. Those are five different bugs in five different places, and if your design is one undifferentiated blob you cannot tell them apart. Draw all five parts before you write code, or you will patch the gaps under pressure later.
The five parts
- Trigger: the event that starts a run, such as a webhook, a queued job, a new ticket, or a schedule. The trigger defines how much you control input quality and how bursty your load is.
- Context gathering: the step that assembles the facts the model needs, from retrieval, database reads, and prior state. Most wrong answers trace back to missing or stale context, not the model.
- Model call: the reasoning step where the model decides what to do next given the context and the instructions. This is where you set the system prompt, the output schema, and the temperature.
- Tools and actions: the functions the agent can call to read or change the world. Each tool is an API boundary you must validate on both sides.
- Review and output: where a human or a rule inspects the result before anything irreversible happens, and where the final output is emitted.
The five parts as code
In LangGraph the map becomes literal: each part is a node, each arrow is an edge, and the state object is the contract between them. Here is the skeleton of a support triage agent with the five parts made explicit:
from typing import TypedDict
from langgraph.graph import StateGraph, START, END
class TriageState(TypedDict):
ticket_id: str # set by the trigger
ticket_body: str
customer: dict # filled by context gathering
recent_tickets: list[dict]
articles: list[dict]
draft: dict | None # filled by the model call
status: str # gathered, drafted, approved, escalated
def gather_context(state: TriageState) -> dict:
customer = crm.get_customer_by_ticket(state["ticket_id"])
recent = tickets.last_n(customer["id"], n=5)
articles = kb.search(state["ticket_body"], top_k=3)
return {"customer": customer, "recent_tickets": recent,
"articles": articles, "status": "gathered"}
builder = StateGraph(TriageState)
builder.add_node("gather_context", gather_context)
builder.add_node("classify_and_draft", classify_and_draft) # model call
builder.add_node("human_review", human_review) # review gate
builder.add_edge(START, "gather_context")
builder.add_edge("gather_context", "classify_and_draft")
builder.add_edge("classify_and_draft", "human_review")
builder.add_edge("human_review", END)
graph = builder.compile()
Notice what this buys you. Context gathering is a plain function you can unit test without a model. The model call reads only what is in state, so you can inspect exactly what the model saw. The review node is a real place in the graph, not a hope.
The trigger is an API endpoint, so treat it like one
The trigger is where untrusted input enters. Validate it at the door and hand off to a queue, so a burst of webhooks does not translate directly into a burst of model calls:
from fastapi import FastAPI
from pydantic import BaseModel, Field
class TicketWebhook(BaseModel):
ticket_id: str = Field(pattern="^tkt_[a-z0-9]+$")
subject: str = Field(max_length=500)
body: str = Field(max_length=20000)
app = FastAPI()
@app.post("/webhooks/ticket")
async def on_ticket(payload: TicketWebhook):
run_id = f"triage-{payload.ticket_id}"
queue.enqueue("triage", run_id=run_id, payload=payload.model_dump())
return {"queued": run_id}
Pydantic rejects malformed payloads before a single token is spent, and the run_id derived from the ticket gives you a stable handle for tracing and idempotency later in the course.
The model call gets an output contract
Never let the model return free text into a pipeline. Constrain the reasoning step to a schema so downstream code can rely on its shape:
from pydantic import BaseModel, Field
from openai import OpenAI
class TriageDecision(BaseModel):
urgency: str = Field(pattern="^(low|normal|high|urgent)$")
category: str
reply_draft: str
needs_human: bool
client = OpenAI()
def classify_and_draft(state: TriageState) -> dict:
completion = client.chat.completions.parse(
model="gpt-4.1-mini",
messages=[
{"role": "system", "content": SYSTEM_PROMPT},
{"role": "user", "content": build_user_message(state)},
],
response_format=TriageDecision,
temperature=0,
)
decision = completion.choices[0].message.parsed
return {"draft": decision.model_dump(), "status": "drafted"}
Each part fails differently
The reason the map matters operationally is that each box has its own failure modes and its own controls. This table is worth keeping next to your architecture diagram:
| Part | Typical failure | Engineering control |
|---|---|---|
| Trigger | Malformed payload, duplicate delivery, burst load | Schema validation, dedupe on run_id, queue between trigger and agent |
| Context gathering | Timeout, empty result, stale data | Per-call timeouts, defined behavior on missing data, freshness checks |
| Model call | Malformed output, wrong decision, drift after model update | Structured output schema, temperature 0 for routing, eval set on every change |
| Tools | Hallucinated arguments, side effects on retry | Argument validation, narrow tools, idempotency keys |
| Review | Rubber-stamping, queue backlog, missing context | Full context in the approval card, edit-rate metrics, escalation SLA |
A worked example, end to end
For the triage agent above: the trigger is the validated webhook. Context gathering pulls the customer record, the last five tickets, and the top three matching help articles, each read with its own timeout. The model call classifies urgency and drafts a reply constrained to the TriageDecision schema. The tools are read-only account lookup plus a draft-create action, with sending gated. Review is a human approving the draft inside the human_review node. Each edge in the graph is a place a run can stall, so each gets a timeout and a defined fallback.
Context gathering deserves more than one function
Of the five parts, context gathering is the one engineers under-build, because in a demo it is three happy-path reads. In production it is three network calls to systems you do not own, and the question that decides whether your agent is trustworthy is: what should happen when one of them fails?
The default - let the exception bubble and fail the run - is defensible and often wrong. A support agent that cannot reach the knowledge base can still draft a reply; it just must not pretend it consulted an article. What is never acceptable is the silent version, where a read returns an empty list, the model receives no articles, and the draft is confidently made up.
The fix is to make degradation explicit in the state, so the model and the reviewer can both see it:
def gather_context(state: TriageState) -> dict:
out = {"status": "gathered", "degraded": []}
try:
out["customer"] = crm.get_customer_by_ticket(
state["ticket_id"], timeout=2.0)
except (TimeoutError, CrmError):
# A missing customer changes what the agent may claim, so this
# is recorded, not swallowed.
out["customer"] = {}
out["degraded"].append("customer_record_unavailable")
try:
out["articles"] = kb.search(state["ticket_body"], top_k=3, timeout=1.5)
except (TimeoutError, KbError):
out["articles"] = []
out["degraded"].append("knowledge_base_unavailable")
return out
Then build_user_message states the degradation in plain language to the model - "The knowledge base was unavailable for this ticket. Do not cite help articles." - and the review card shows the same list to the human. Three small consequences follow, and all three matter more than the code:
- Every timeout is a number you chose. Without an explicit timeout you inherit the client library's default, which is frequently minutes. An agent that hangs for two minutes on a dead CRM read is an outage that looks like a slow model.
- "Degraded" is a countable event. Once it is a field, you can alert on the rate. Most teams discover their CRM is flaky only after an agent has been quietly guessing for a month.
- The reviewer sees why a draft is thin. Which is the difference between a reviewer who trusts the queue and one who rubber-stamps it.
Tools: the boundary where damage happens
Context gathering reads. Tools change things, so this is the part that turns a bad decision into a bad outcome. Three controls do most of the work.
Validate arguments in the tool, not in the prompt. A model asked to pass a valid ID will usually pass a valid ID. "Usually" is not a control:
class RefundArgs(BaseModel):
order_id: str = Field(pattern="^ord_[a-z0-9]{8}$")
amount_cents: int = Field(gt=0, le=50_00) # hard ceiling, in code
reason: str = Field(min_length=10, max_length=500)
def issue_refund(args: RefundArgs, run_id: str) -> dict:
order = orders.get(args.order_id) # must exist
if order is None:
return {"ok": False, "error": "No such order. Do not retry."}
if args.amount_cents > order.paid_cents:
return {"ok": False,
"error": f"Refund exceeds amount paid ({order.paid_cents})."}
return payments.refund(order, args.amount_cents,
idempotency_key=f"{run_id}:{args.order_id}")
Three things in that snippet are worth copying. The ceiling lives in the schema, where no prompt edit can raise it. The failure returns a sentence the agent can act on rather than raising, so the agent can explain itself instead of dying mid-run. And the idempotency key is derived from the run, so a retry after a network blip does not refund twice - which is the single most expensive bug in this category and the reason retries and idempotency get a full lesson later.
Split read from write. Keep read-only tools and mutating tools in separate registries and let the graph decide which set is available at each node. A drafting node that physically cannot send an email is a stronger guarantee than any instruction that it must not.
Keep tools narrow. A single update_order(order_id, fields) tool that accepts an arbitrary dictionary is a hole with a docstring in front of it. cancel_order, change_delivery_date, and update_shipping_address are three tools that are individually reviewable, individually loggable, and individually revocable.
Designing the review gate so it is not theatre
A review box on the diagram is easy. A review step people actually perform is not, and a rubber-stamped queue is worse than no review at all, because it manufactures the appearance of oversight.
Four properties separate real review from theatre:
- The reviewer sees what the model saw. Not just the draft - the customer record, the articles retrieved, and the degradation list. Reviewing an output without its inputs is proofreading, not reviewing.
- Editing is as easy as approving. If approve is one click and editing means opening another system, you have designed a queue that gets approved.
- Edit rate is measured. The proportion of drafts a reviewer changes is the single most useful number in the whole system. Near 100% means the agent is not ready. Near 0% means either it is excellent or nobody is reading, and you can tell which by sampling. Track it from day one, because it is also the number that tells you when the gate can be relaxed.
- Not everything is reviewed. Review scales badly, so gate on the irreversible and the expensive. Sending a reply to a customer, issuing a refund, changing a delivery address: yes. Adding an internal tag: no. A review gate on everything gets abandoned within a fortnight, and then nothing is reviewed.
The way to phase it, if you are putting an agent in front of real work for the first time: review everything for the first stretch while you gather edit-rate data, then relax the gate one category at a time, keeping the irreversible actions gated permanently. That sequencing is also what makes the change legible to whoever owns the risk, which is usually not you.
Draw it before you build it
The practical version of this lesson takes twenty minutes and a sheet of paper. Five boxes, and against each one write a single sentence:
- Trigger. What starts a run, how many per hour at peak, and what a duplicate delivery looks like.
- Context. Every system read, its timeout, and what the agent is allowed to claim when that read fails.
- Model. The output schema, and one sentence on how you will know if a model update changed its behaviour.
- Tools. Each one marked read or write, with the ceiling on any write stated as a number.
- Review. Which actions are gated, who is on the other side, and how long they have before the run stalls.
If any of those sentences cannot be written, that is the part of the system that will page you first. This is the same exercise we run at the start of a build for a client - it is deliberately boring, and it surfaces more real risk per hour than any other activity in the project.
Setup: versions, install, and the whole thing in one file
The snippets above are deliberately partial so the five parts stay visible. Here is the runnable version. Versions are the current releases as of August 2026 - pin them, because both libraries move fast and a graph written against one major version does not necessarily import on the next.
# Python 3.10 or later is required by langgraph
python -m venv .venv && source .venv/bin/activate
pip install "langgraph==1.2.10" "openai==2.53.0" "pydantic==2.13.4"
export OPENAI_API_KEY=sk-...
# triage.py - run with: python triage.py
import os
from typing import TypedDict
from langgraph.graph import StateGraph, START, END
from openai import OpenAI
from openai import LengthFinishReasonError, ContentFilterFinishReasonError
from pydantic import BaseModel, Field, ValidationError
client = OpenAI() # reads OPENAI_API_KEY from the environment
# ---- 1. the state: the contract between every node -------------------
class TriageState(TypedDict, total=False):
ticket_id: str
ticket_body: str
customer: dict
articles: list
degraded: list
draft: dict
status: str
# ---- 2. the model's output contract ----------------------------------
class TriageDecision(BaseModel):
urgency: str = Field(pattern="^(low|normal|high|urgent)$")
category: str
reply_draft: str = Field(max_length=1500)
needs_human: bool
SYSTEM_PROMPT = (
"You triage support tickets. Classify urgency and category, and "
"draft a reply. Never promise a refund or a delivery date. If the "
"context is missing anything you would need, set needs_human=true "
"and say what is missing in reply_draft."
)
# ---- 3. context gathering: stubbed here, network calls in reality ----
def gather_context(state: TriageState) -> dict:
out: dict = {"status": "gathered", "degraded": []}
try:
out["customer"] = {"id": "cus_1", "plan": "pro", "since": "2024-02"}
except Exception:
out["customer"] = {}
out["degraded"].append("customer_record_unavailable")
try:
out["articles"] = [{"title": "Refund policy", "id": "kb_12"}]
except Exception:
out["articles"] = []
out["degraded"].append("knowledge_base_unavailable")
return out
def build_user_message(state: TriageState) -> str:
parts = [f"TICKET: {state['ticket_body']}",
f"CUSTOMER: {state.get('customer') or 'unknown'}",
f"ARTICLES: {state.get('articles') or 'none available'}"]
if state.get("degraded"):
parts.append(
"DEGRADED: " + ", ".join(state["degraded"]) +
". Do not claim to have consulted anything in that list."
)
return "\n\n".join(parts)
# ---- 4. the model call, constrained to the schema --------------------
def classify_and_draft(state: TriageState) -> dict:
try:
completion = client.chat.completions.parse(
model="gpt-4.1-mini",
messages=[
{"role": "system", "content": SYSTEM_PROMPT},
{"role": "user", "content": build_user_message(state)},
],
response_format=TriageDecision,
temperature=0,
)
except LengthFinishReasonError:
# The model ran out of output tokens mid-object, so there is no
# valid parse. Escalating beats retrying an identical call.
return {"status": "escalated",
"draft": {"needs_human": True,
"reply_draft": "Output truncated; needs a human."}}
except ContentFilterFinishReasonError:
return {"status": "escalated",
"draft": {"needs_human": True,
"reply_draft": "Content filtered; needs a human."}}
decision = completion.choices[0].message.parsed
if decision is None: # refusal or empty parse
return {"status": "escalated",
"draft": {"needs_human": True, "reply_draft": "No parse."}}
return {"draft": decision.model_dump(), "status": "drafted"}
# ---- 5. the review gate ----------------------------------------------
def human_review(state: TriageState) -> dict:
draft = state.get("draft") or {}
print("--- REVIEW CARD ---")
print("degraded:", state.get("degraded"))
print("urgency :", draft.get("urgency"))
print("draft :", draft.get("reply_draft"))
return {"status": "approved" if not draft.get("needs_human")
else "escalated"}
builder = StateGraph(TriageState)
builder.add_node("gather_context", gather_context)
builder.add_node("classify_and_draft", classify_and_draft)
builder.add_node("human_review", human_review)
builder.add_edge(START, "gather_context")
builder.add_edge("gather_context", "classify_and_draft")
builder.add_edge("classify_and_draft", "human_review")
builder.add_edge("human_review", END)
graph = builder.compile()
if __name__ == "__main__":
result = graph.invoke({
"ticket_id": "tkt_9f2",
"ticket_body": "I was charged twice this month and I want it fixed.",
})
print("final status:", result["status"])
Run python triage.py and you get a review card and a final status. It is a toy - the context functions are stubs and the review gate prints instead of waiting for a person - but every one of the five parts is a named thing you can replace independently, which is the entire architectural claim of this lesson made executable.
Debugging: the four failures this code actually produces
Notice that the model call catches two named exceptions rather than a bare Exception. They are not hypothetical - they are the two documented ways a structured-output call fails without producing a parse, and each needs a different response.
| What you see | What happened | The right response |
|---|---|---|
LengthFinishReasonError | The response hit the output-token limit part-way through the object, so there is nothing valid to parse | Do not retry unchanged - it will truncate again. Raise the output limit, or shorten what you ask for. The max_length on reply_draft exists to make this rare |
ContentFilterFinishReasonError | The response was stopped by the content filter | Escalate to a human. A retry produces the same result, and an agent that quietly drops these tickets is worse than one that flags them |
message.parsed is None | The model refused, or returned something that did not parse into the schema | Check for it explicitly. This is the case people forget, and it is the one that produces 'NoneType' object has no attribute 'model_dump' three lines later |
Pydantic ValidationError at the trigger | A malformed webhook payload was rejected at the door | This is the system working. Return a 4xx and log the payload - do not loosen the schema to make the error go away |
The third row deserves a note because it is a general principle rather than a library detail. A structured-output helper turns "the model said something weird" into a typed failure at a known line, which is exactly the trade you want: you have moved an unpredictable failure out of your business logic and into one place with a name. The mistake is then wrapping that call in a bare except Exception: pass, which throws the benefit away and reintroduces the silent-wrongness problem the schema was there to prevent.
Two more failures worth pre-empting, because both look like bugs in your graph and are not:
- A node returns the whole state instead of a partial update. Nodes return the keys they changed, and the framework merges them. Returning the entire state object works until two nodes write the same key, at which point you get a last-writer-wins bug that is very hard to see in a diff. Return only what you changed - every function above does.
- The state grows without limit. Anything you put in state travels through every subsequent node and, if you are persisting runs, into storage. Putting a full API response into state because it was convenient is how a triage run ends up carrying half a megabyte of JSON. Store the three fields you need and a reference to the rest.
Testing the five parts, one layer at a time
The architectural payoff is that each part becomes testable without the others. Most teams skip straight to end-to-end tests, which are slow, flaky, and tell you only that something is wrong. Four tests, in ascending cost, catch nearly everything:
# 1. Context gathering - no model, no network, fastest of all.
def test_degradation_is_recorded_not_swallowed(monkeypatch):
monkeypatch.setattr(kb, "search", raise_timeout)
out = gather_context({"ticket_id": "tkt_1", "ticket_body": "x"})
assert out["articles"] == []
assert "knowledge_base_unavailable" in out["degraded"]
# 2. Prompt assembly - still no model. This is the test that
# catches the degradation never reaching the model at all,
# which is a silent, expensive bug.
def test_degradation_appears_in_the_prompt():
msg = build_user_message({
"ticket_body": "x", "degraded": ["knowledge_base_unavailable"],
})
assert "DEGRADED" in msg
# 3. Tool argument validation - no model. Assert the ceiling
# holds, because this is the control that stops a bad
# decision becoming a bad outcome.
def test_refund_ceiling_is_enforced():
with pytest.raises(ValidationError):
RefundArgs(order_id="ord_abcd1234", amount_cents=999_00,
reason="customer asked nicely")
# 4. Only now, one end-to-end run against a recorded fixture,
# asserting the SHAPE of the decision rather than its words.
def test_end_to_end_returns_a_valid_decision(recorded_response):
result = graph.invoke({"ticket_id": "tkt_1", "ticket_body": "..."})
assert result["draft"]["urgency"] in {"low", "normal", "high", "urgent"}
Note what test four does not do: it never asserts on the exact wording of the draft. Asserting the text of a model's output produces a test suite that fails every time anything changes and teaches you nothing when it does. Assert the shape, the bounds, and the routing decision - the things your downstream code actually depends on - and leave quality measurement to an eval set, which is a different tool for a different question.
Tests one to three need no API key, run in milliseconds, and cover the three parts where production failures actually concentrate. If you write only one of the four, write test two: a degradation flag that is recorded but never reaches the prompt is the exact bug that produces a confident, well-formed, entirely fabricated answer.
Common mistakes
- Collapsing context gathering into the prompt, so you cannot see or fix what the model actually read.
- Leaving tools undefined until late, then bolting on broad access that is hard to secure.
- Designing with no review box because the demo looked clean on tidy input.
- Letting the trigger call the model synchronously, so a webhook burst becomes an outage.
What you should be able to do now
- Draw any agent workflow as trigger, context, model call, tools, and review on one page.
- Express that map as a LangGraph StateGraph with one node per part and a typed state.
- Validate trigger payloads with Pydantic before any model call happens.
- Constrain every model call to a structured output schema.
- Name the top failure mode and control for each of the five parts of your own workflow.
Where this goes next
This lesson and State and handoffs are the free part of the course. They cover the architecture and the state model, which together are what let you reason about an agent instead of hoping about it. Draw your own five boxes before going further - the exercise above is genuinely the highest-value twenty minutes in the whole subject.
The paid lessons are the production engineering. Retries and idempotency so a network blip does not double-charge a customer. Evaluation sets, so a model or prompt change can be shown to help rather than assumed to. Tracing and structured logging that make a failed run reconstructable months later. Cost controls and budget ceilings per run. Prompt-injection defence at the tool boundary, which is where untrusted content meets real permissions. Deployment, rollback, and the on-call runbook for an agent that has started behaving oddly at 3am. Every lesson ships runnable code and the repo.
If your situation is "this needs to exist and work" rather than "I want to learn to build it", that is what we do as project work - see AI automation services, or start with the free automation audit, which is a straight assessment of which process is worth an agent and which one wants a boring script instead. The human in the loop, idempotency and eval glossary entries cover three terms this lesson leaned on.
Enter your email below and the two free lessons arrive with the code from them - the StateGraph skeleton, the validated webhook, the schema-constrained model call - so you can start from something that runs.
Key takeaways
What to remember from this lesson
- An agent is a system, not a prompt. Trigger, context gathering, model call, tools, and review each fail differently and each needs its own control.
- Drawn as a LangGraph StateGraph, context gathering becomes a plain function you can unit test with no model, and review becomes a real node rather than a hope.
- The trigger is an untrusted API endpoint. Validate the payload with a schema at the door, then enqueue - so a webhook burst does not become a burst of model calls.
- Never let a model return free text into a pipeline. A structured output schema plus temperature 0 for routing is what makes downstream code safe to write.
- Most wrong answers trace to missing or stale context, not to the model. That is why context gathering deserves its own box with its own timeouts.
Try it yourself
Validate the trigger before anything expensive runs
The trigger is an untrusted API endpoint. Below is a fixture of three webhook payloads a dental practice's phone system would post on a missed call - one good, two malformed. Write the door check that turns a raw payload into a run, or rejects it with a reason. Nothing here calls a model; that is the point.
Check yourself
Which of the five parts is broken
The agent answers confidently with a price that has not been correct for six months. Which part of the system do you look at first?
A webhook burst delivers 400 events in a minute and your provider bill spikes. What is the structural fix?
Why is 'the model returns free text that downstream code parses' considered a design bug rather than a parsing inconvenience?
Answer every question to mark.
Exercise
Draw your workflow as five boxes, then make it compile
- 1Take a workflow you want to automate and write the five parts on one page: trigger, context gathering, model call, tools, review. Name the specific event, sources, decision, actions, and reviewer.
- 2For each box, write its top failure mode and the engineering control you would use, following the table in the lesson. Five rows.
- 3Define a TypedDict state whose fields say which box fills them, the way TriageState marks the trigger, context, and model-call fields.
- 4Build the StateGraph with one node per part and wire START through to END. Implement only the context-gathering node for real; stub the rest to return a fixed dict.
- 5Write a Pydantic model for your trigger payload with at least one constrained field (a pattern or a max_length), and confirm it rejects a deliberately malformed payload before any model call.
- 6Write the output schema for your model call with at least one enum-style constrained field and a boolean that decides whether a human is needed.
- 7Run the graph end to end with the stubs in place and confirm it reaches END.
You are done when Your graph compiles and runs to END with stubbed nodes, your trigger model raises on a payload you deliberately malformed, and you have a five-row failure/control table where every row names a control you have actually specified rather than intend to add.
Companion files
The five-part skeleton as runnable code
The LangGraph StateGraph, the validated FastAPI webhook, and the schema-constrained model call as separate files - the starting point for the exercise above rather than a snippet to retype.
The free-preview pack includes 6 files of runnable code and config for Trigger, Context, Model, Tools, Review, plus the other free lessons of this course. No email needed.
Free preview pack - 16 KB zipCheck yourself
Answer before you reveal
The agent gives a wrong answer. Which box is the first suspect, and why not the model?Show answer
Context gathering. Most wrong answers trace to missing or stale context - a timed-out read, an empty retrieval, or a stale record - and if context lives inside the prompt you cannot see what the model actually read.
Why put a queue between the trigger and the agent rather than calling the model from the webhook handler?Show answer
Because a burst of webhooks otherwise becomes a burst of model calls, and that is an outage. The handler validates and enqueues, returning fast; the run happens behind the queue where you control concurrency.
What does deriving run_id from the ticket rather than generating it randomly buy you later?Show answer
A stable handle for tracing and idempotency - a duplicate delivery lands on the same run instead of spawning a second one, and anyone can find the run for a given ticket in one query.
