Home › Claude › Agent › Route

🔀 Route: send each request to the right place

A coding question, a request for a poem and a 40-page contract need very different handling. Routing works out what kind of request has arrived and passes it to the tool, workflow or specialised agent best suited to it.

• Beginner
• ⏱ 20 min
• General workflow pattern

What is it?

Routing is a two-part process: first classify the request (decide what type it is), then dispatch it (hand it to the matching handler). Each handler can have its own instructions, tools, skills or even its own model.

Intent

What the user is trying to achieve, such as "fix my code" or "write an email".

Classification

Sorting something into one of a fixed set of categories.

Route / handler

The destination that deals with one category: a tool, a workflow or a specialised agent.

Confidence

How sure the classifier is about its choice.

Fallback route

The safe default used when no route fits or confidence is low, for example "ask a clarifying question".

Why is it important?

• Specialisation: one prompt that tries to handle every kind of request does each of them less well. Separate handlers can each be tuned for their job.
• Cost and speed: simple requests can go to a cheaper, faster model or straight to a tool, and only hard ones go to the most capable model.
• Safety: sensitive requests, such as refunds or account changes, can always be sent down a path that includes human review.
• Easier maintenance: improving the "coding" route can't accidentally break the "writing" route.

Real-world analogy

How does it work?

1. Define the routes: a short, fixed list of categories with clear descriptions.
2. Classify: use simple rules (keywords, form fields) or ask Claude to choose one category.
3. Check the decision: is the category valid? Is the confidence high enough? Is required information missing?
4. Dispatch to the chosen handler, or to the fallback.
5. Respond and log which route was used, so you can measure accuracy later.

What can a router base its decision on?

Workflow diagram

Try it: watch the router decide

Practical example: a help-desk assistant

Code example

Version 1: rule-based router. This runs with plain Python, with no API key and no AI. Rules are fast and free, but brittle.

# simple_router.py: route requests using keyword rules. Run: python simple_router.py
ROUTES = {
    "coding":   ["code", "bug", "error", "python", "function", "crash"],
    "research": ["research", "find", "studies", "trends", "latest"],
    "writing":  ["write", "draft", "email", "letter", "poem"],
    "document": ["pdf", "contract", "document", "attached"],
}

def route(request: str, has_attachment: bool = False) -> str:
    words = request.lower()
    scores = {name: sum(k in words for k in keys) for name, keys in ROUTES.items()}
    best = max(scores, key=scores.get)
    if scores[best] == 0:
        return "fallback"                       # nothing matched: ask the user to clarify
    if best == "document" and not has_attachment:
        return "missing_info"                   # right route, but the file is missing
    return best

for text, attached in [("My Python code has a bug", False),
                       ("Summarise this contract", False),
                       ("Help me with the thing", False)]:
    print(f"{text!r:35} -> {route(text, attached)}")

'My Python code has a bug'          -> coding
'Summarise this contract'           -> missing_info
'Help me with the thing'            -> fallback

Version 2: Claude as the classifier. Claude understands meaning, not just keywords. Structured outputs guarantee that the reply is valid JSON in the shape we ask for. It needs pip install anthropic and the ANTHROPIC_API_KEY environment variable on your computer or server.

# claude_router.py: Claude classifies, our code checks and dispatches.
import json
import anthropic

client = anthropic.Anthropic()
ROUTES = ["research", "coding", "writing", "document_analysis", "unclear"]

def classify(request: str) -> dict:
    response = client.messages.create(
        model="claude-opus-5-5",
        max_tokens=4096,
        system=("You route requests for a help desk. Pick exactly one route. "
                "Use 'unclear' when the request is ambiguous. "
                "If key information is missing (e.g. a document that was not attached), describe it in missing_info."),
        messages=[{"role": "user", "content": request}],
        output_config={
            "effort": "low",                         # classification is easy: think briefly
            "format": {"type": "json_schema", "schema": {
                "type": "object",
                "properties": {
                    "route": {"type": "string", "enum": ROUTES},   # only these values are allowed
                    "confidence": {"type": "number"},              # 0.0 to 1.0
                    "missing_info": {"type": "string"},            # "" if nothing is missing
                },
                "required": ["route", "confidence", "missing_info"],
                "additionalProperties": False,
            }},
        },
    )
    return json.loads(next(b.text for b in response.content if b.type == "text"))

# Handlers: in a real app each would call its own prompt, tools or agent.
HANDLERS = {
    "research": lambda r: f"[research agent] searching sources for: {r}",
    "coding": lambda r: f"[coding agent] debugging: {r}",
    "writing": lambda r: f"[writing agent] drafting: {r}",
    "document_analysis": lambda r: f"[document agent] analysing: {r}",
}

def handle(request: str) -> str:
    decision = classify(request)
    print("decision:", decision)
    if decision["missing_info"]:
        return f"Before I start, could you provide: {decision['missing_info']}?"
    if decision["route"] == "unclear" or decision["confidence"] < 0.6:
        return "Could you tell me a bit more? Is this about research, code, writing or a document?"
    return HANDLERS[decision["route"]](request)

print(handle("My Python script crashes with a KeyError on line 12"))
print(handle("Can you sort this out?"))

decision: {'route': 'coding', 'confidence': 0.95, 'missing_info': ''}
[coding agent] debugging: My Python script crashes with a KeyError on line 12
decision: {'route': 'unclear', 'confidence': 0.3, 'missing_info': ''}
Could you tell me a bit more? Is this about research, code, writing or a document?

Step-by-step explanation

1. Version 1 counts keyword matches for each route with sum(k in words for k in keys) and picks the highest score using max(..., key=scores.get).
2. A score of zero means nothing matched, so it returns "fallback". A document request with no attachment returns "missing_info".
3. Version 2 puts the routing rules in the system prompt, which is standing instructions that apply to the whole conversation.
4. output_config.format with a json_schema forces the reply into our shape. The enum means Claude can only choose one of our five routes.
5. "effort": "low" tells Claude it doesn't need to think deeply, which makes classification faster and cheaper.
6. handle() checks the decision before acting: missing information → ask for it, unclear or low confidence → clarify, otherwise call the matching handler.
7. HANDLERS is a dictionary of destinations. Adding a new route means adding one entry to ROUTES and one handler.

Handling unclear requests, missing information and fallbacks

• Always include an "unclear" option. If the classifier has to choose a real route, it will guess.
• Set a confidence threshold such as 0.6. Below it, ask instead of guessing. Self-reported confidence is only a rough guide, so test it on real examples.
• Ask one specific question ("Is this about code or writing?"), not "Please clarify".
• Check for missing inputs, such as files, order numbers or dates, before starting expensive work.
• Have a general fallback handler for anything left over, and log these cases. They show you which new routes you need.

Routing and orchestration compared

Use cases

• Customer service: billing, technical support, refunds, general questions
• Choosing a model: easy questions to a fast, cheap model, hard ones to the most capable model
• Multi-purpose assistants with research, coding and writing modes
• Safety paths: sensitive topics always routed to careful handling or a human

Advantages and limitations

Best practices

• Start with 3–5 clearly different routes and describe each in one sentence.
• Constrain the classifier's answer to a fixed list, for example with an enum in structured outputs.
• Use code rules for obvious cases (an attachment means a document) and Claude for the rest.
• Keep a test set of real requests with the correct route, and re-check accuracy after changes.
• Log every routing decision.

Knowledge check

Mini project

Key takeaways

• Routing = classify + dispatch. Each request goes to the one handler that suits it best.
• Base routes on intent, task type, conditions or required capabilities.
• Always provide an "unclear" option, a confidence check and a fallback.
• Routing picks who; orchestration plans how and coordinates many.
• It's a general pattern. Claude is often the classifier inside it.

Further learning

• Building effective agents, the "Routing" section (Anthropic engineering blog)
• Structured outputs (official docs)
• Prompt engineering overview (official docs)