Why Your "All-Powerful" Agent Fails — Scene Routing That Splits One Agent into 6 Experts

The Pain: Your agent has 20+ tools and can theoretically do anything. In practice it constantly uses the wrong one — user asks about shipping cost, agent searches contacts.
What You'll Learn: Scene routing — use a router layer to split a "jack-of-all-trades" agent into 6 scene experts, each seeing only its own tools.

1. The Problem: Looking for a Hammer in the Kitchen

Imagine walking into the kitchen to find a hammer, then the garage to find a knife. Each room has the tools it needs — but if you pile all tools in the living room, when you look for a hammer you see knives, wrenches, screwdrivers, drills... and pick wrong.

Early agent architecture was exactly this. I configured 20+ tools: email search, SQLite queries, PDF generation, contact search, quote calculation, shipping queries... Theoretically it could do anything. In practice, it constantly called the wrong tool in the wrong scenario.

Classic failures:

• User asks "How much for this flight's shipping?", agent searches contacts
• User asks "Check the status of this shipment", agent generates a quote

The reason is simple: too many tools. The LLM's reasoning path jumps between multiple tool domains, fragmenting context, and finally choosing wrong.

Core insight: LLM tool-call accuracy is inversely proportional to visible tool count. More tools = exponentially higher mis-selection rate.

2. Core Idea: Scene Isolation

The core idea of scene routing: don't let one agent handle all scenes.

First, a router layer determines the scene type of the current task, then injects scene-specific SOP, toolset, and knowledge base.

This mirrors microservices — you don't need one monolith handling all requests; you route through an API gateway to the corresponding backend service. Scene routing is the agent's "API gateway".

A logistics AI assistant handles: email, quoting, reports, contacts, finance, knowledge queries. If all tools are open to the LLM, every call picks from 30+ tools, with high mis-selection rates.

Solution: task_dispatcher.classify() classifies requests into 6 scenes, each with its own tool whitelist, schema enforcement, and SOP injection.

Immediate results: context length -60%, tool-call accuracy +40%. Because the LLM no longer chooses among irrelevant tools — it only sees the 5-6 tools in its scene.

3. Technical Implementation

3.1 First Gate: task_dispatcher.classify()

All user requests enter through the classifier:

def classify(request_text: str) -> SceneContext:
    # Step 1: regex exact match (covers 90%)
    scene_id = regex_match(request_text)
    if scene_id:
        return SceneContext(scene_id=scene_id)

    # Step 2: semantic fuzzy match (covers remaining 10%)
    scene_id = semantic_match(request_text)
    if scene_id:
        return SceneContext(scene_id=scene_id)

    # Fallback: general conversation
    return SceneContext(scene_id="general")

The result is a structured SceneContext containing: scene_id, sop_path, and tool whitelist.

3.2 SCENE_CONFIG: Scene Configuration File

Each scene has its own config:

SCENE_CONFIG = {
    "email": {
        "tools": ["imap_fetch", "smtp_send", "contact_lookup"],
        "sop": "sops/email_sop.md",
        "schema": "schemas/email_schema.json",
        "gates": ["check_email_format", "check_signature"],
    },
    "quoting": {
        "tools": ["rate_query", "quote_template", "history_lookup"],
        "sop": "sops/quoting_sop.md",
        "schema": "schemas/quote_schema.json",
        "gates": ["check_profit_margin", "check_currency"],
    },
    # ... 6 scenes
}

Key: tools not in the whitelist are never loaded. Email scene can't write DB; finance scene can't send email. Isolated, independent.

Verified: after scene isolation, tool mis-selection dropped from 15% to under 2% (from actual runtime logs).

3.3 inject-sop: Load Scene SOP Before Execution

SOP injection is key. Once the scene is determined, inject-sop injects the scene's SOP into LLM context.

Different scenes inject different SOPs: email scene gets "email writing SOP", quoting gets "quoting SOP", report gets "report SOP".

SOP isn't injected once. inject-sop checks the context window and re-injects at key points, preventing dilution by long conversations.

4. The Six Scenes

Scene	Tools	Description
email	IMAP/SMTP	Read, classify, reply, forward
quoting	rate DB / templates	Shipping queries, quotes
report	unrestricted	In-transit, daily, monthly
contact	contact DB	Client/agent lookup
finance	finance DB / templates	AR/AP, statistics
knowledge	KB retrieval	Industry Q&A

5. Pros and Cons

Pros

• Clean context — LLM sees only scene-relevant tools and knowledge
• Tool-call accuracy +90%+
• Consistent output — fixed schema per scene
• Debug-friendly — issues located at scene level
• Easy to extend — new scene = new SCENE_CONFIG

Cons

• Multi-scene tasks can't auto-split
• Scene boundaries hard to define precisely
• High routing failure cost — wrong classification cascades
• Complex config — 6 scenes need 6 configs + 6 SOPs

6. Where You Are Now

You're no longer the optimist who gives an agent all tools expecting full-stack genius. You're becoming a system designer who uses scene isolation to constrain agent behavior boundaries.

Like a company needs sales, tech, finance departments, an agent system needs "departments" too. Scene routing makes each agent scene do one thing and do it well. It sacrifices the illusion of "universality" for the reality of "reliability."

Next: How does the router avoid missing anything? Regex + semantic dual-layer classification, pushing accuracy from 80% to 100%.