How to Build a Workflow Routing Agent (2026 Tutorial)

This is a hands-on tutorial for building a workflow Routing Agent — an agent that can classify an incoming request and send it to the right workflow. It maps directly to our Workflow Routing Agent blueprint, so you can read the build here and then grab the full runnable kit (system prompt, tools, and a one-command starter) when you're ready. It's written for teams with multiple workflows or agents that need requests dispatched correctly.

When you have many workflows, queues, or downstream agents, getting each request to the right one is brittle with rules and silently wrong when an edge case slips through. Classify an incoming request and send it to the right workflow is the kind of high-volume, judgment-light-but-context-heavy work an agent handles well — provided you build it with the right boundary. Throughout, the single most important design rule is this: the agent's worst-case action is misrouting a high-risk request silently instead of escalating it, and that action stays behind a human gate. Everything else follows from that.

What you're building

The agent is a control loop, not a single prompt. It takes an input, reasons about what to do, calls tools to gather evidence and act, observes the results, and continues until it reaches a conclusion or hits a stopping condition. The stack we use in the blueprint is Claude, LangGraph, OpenAI — but the design transfers to any framework, because what matters is the shape of the loop and the boundary around it, not the library.

Concretely, the finished agent will accept its input, enrich it with real context from your systems, reason over that evidence, and produce a structured, reviewable output — with anything irreversible or high-risk routed to a human rather than executed silently.

The tools the agent needs

An agent is only as capable as the tools you give it, and only as safe as the contracts on those tools. This blueprint uses 8 tools: get_request, classify_intent, match_route, confidence_score, check_risk, route_or_escalate, request_clarification, log_routing. Notice the split — most are read tools that gather evidence (the safe, high-volume work), and the few that act are exactly the ones that belong behind a gate. That division is deliberate: give the agent broad read access to do the tedious enrichment, and narrow, gated write access so it can't cause harm it can't undo.

Each tool needs a strict contract — a well-defined input and output — because loose tool definitions are where agents go off the rails, calling the wrong action or passing invalid arguments. Define them tightly before you wire up any reasoning.

Step by step

1. Start with the boundary. Before writing the system prompt, write down the worst-case action (misrouting a high-risk request silently instead of escalating it) and decide which tools are gated. This one decision shapes the whole build.

2. Ground the agent in real context. Wire the read tools first and confirm the agent can pull the evidence it needs — the diff, the alert, the schema, the contract, whatever the input demands. An agent reasoning over stale or missing context will produce confident nonsense, so get retrieval solid before anything else.

3. Write the system prompt as an operating manual. Name the tools and the decision criteria, not just the goal. Tell the agent how to weigh evidence, when to act, when to ask, and — critically — when to stop and escalate. The blueprint's system prompt is 500–700 words for exactly this reason: an agent that acts needs explicit operating rules, not a one-line instruction.

4. Gate the irreversible step. Split every consequential capability into a reversible "propose" step the agent owns and an irreversible "commit" step a human approves. The agent does all the work right up to the edge of consequence; a person crosses it.

5. Add confidence and escalation. Have the agent score its own confidence and escalate when it's low, when the input is ambiguous, or when the stakes are high. An agent that knows when not to act is more valuable than one that always has an answer.

6. Instrument it. Log every decision — the inputs, the tool calls, the reasoning, the output — so you can evaluate whether the agent was right, not just whether it ran. Most production agents have observability but skip evaluation, and that gap is where failures live.

The guardrails that make it production-ready

The difference between this agent and a flashy demo is entirely in the boundaries. It never takes its worst-case action autonomously. It authenticates with its own identity and the least privilege it needs. It scores confidence and escalates ambiguity instead of guessing. And every decision is logged and reviewable. The blueprint encodes all of this in an AgentAz™ governance section — explicit Trust Levels, a worst-case action, and a human-in-the-loop gate — so the safety isn't an afterthought bolted on, it's the specification.

If you want the deeper reasoning behind these boundaries, see our guide to designing safe AI agents, and for how the pieces fit together architecturally, the agent engineering stack.

Get the kit

This tutorial walks the design; the Workflow Routing Agent blueprint gives you the rest — the full system prompt, all 8 tool contracts, worked examples (including the hard cases where the agent correctly refuses or escalates), Basic/Advanced/Enterprise tiers, and a runnable run.py starter that executes the real loop with one command and an API key, on Anthropic or OpenAI. Read it, adapt it to your systems, and ship it behind the gate. For the broader production checklist, see building production-ready AI agents.