How to Configure Sub-Agent Routing in Switchyard: A Complete Guide

Switchyard enables independent routing strategies for delegated sub-agent work through a dedicated subagents table in your TOML configuration, allowing parent-agent policies to remain unchanged while directing child tasks to specialized classifiers.

NVIDIA-NeMo/Switchyard provides a sophisticated routing layer that separates parent-agent traffic from delegated sub-agent tasks. When configuring sub-agent routing in Switchyard, you define a nested routing policy that intercepts requests marked as sub-agent work and applies a distinct classification algorithm. This architecture ensures that harness-delegated tasks route to appropriate specialized targets—such as workers or reviewers—without affecting the primary agent's traffic flow.

Understanding the Sub-Agent Routing Architecture

The implementation consists of two core components working in tandem to delegate and classify sub-agent requests.

The Rust core handles request interception and forwarding. In crates/libsy/src/algorithms/subagent.rs, the SubagentRouter struct wraps the parent routing algorithm and inspects incoming request metadata. When a request contains sub-agent markers, the router forwards it to a nested classifier defined in SubagentRouterConfig (lines 18-30). The actual routing decision occurs in SubagentRouter::route (lines 99-108), which evaluates the classification result against available targets.

The configuration layer exposes these capabilities through TOML schemas. You define sub-agent policies under a [routes.agent.subagents] table within your standard route configuration. According to the Sub-Agent-Aware Routing documentation, this layer supports custom LLM classifiers, passthrough targets, and classification triggers while maintaining strict separation from parent routing logic.

TOML Configuration Schema and Options

When configuring sub-agent routing, you must adhere to specific constraints regarding parent route compatibility and classifier behavior.

Supported Parent Route Types

Sub-agent routing attaches only to specific parent algorithms. The current implementation supports:

• passthrough routes that forward traffic to a single target
• stage_router configurations that handle multi-stage processing

Other routing algorithm types do not expose the subagents configuration table.

Classifier Modes and Triggers

The sub-agent classifier operates in custom mode exclusively, validating responses against a JSON schema you provide. You control when classification occurs using the classify_trigger parameter:

• new_session: Caches the routing decision for the duration of the session_id + agent_id pair
• every_request: Re-evaluates the target for every individual request

Note that user_turn triggers are not supported for sub-agent routing.

Message Hash Fallback Limitations

Unlike standard routing algorithms, sub-agent routing explicitly disables message hash fallback. This design choice ensures that child identity derives exclusively from harness metadata rather than content hashing, preventing incorrect cache hits when multiple sub-agents process similar prompts.

Practical Configuration Examples

The following examples demonstrate complete TOML configurations for common sub-agent routing scenarios.

Custom LLM Classifier for Intelligent Routing

This configuration creates a parent passthrough route with an intelligent sub-agent classifier that selects between "worker" and "reviewer" targets based on task type:

# Parent route handles normal traffic

[routes.agent]
id = "agent"
type = "passthrough"
target = "parent"
context_window = 400000
tool_calling = true
reasoning = true

# Sub-agent routing with custom LLM classifier

[routes.agent.subagents]
type = "llm_classifier"
mode = "custom"
classifier_target = "classifier"
targets = ["worker", "reviewer"]
default_target = "worker"
classify_trigger = "new_session"
max_output_tokens = 64
prompt = """
Select exactly one target for the delegated task.

- Select "reviewer" for code review, critique, auditing, or correctness analysis.
- Select "worker" for implementation, research, explanation, and other delegated work.

Return only JSON matching the response schema.
"""
response_schema = '''
{
  "type": "object",
  "properties": { "target": {"type": "string", "enum": ["worker", "reviewer"]} },
  "required": ["target"],
  "additionalProperties": false
}
'''
policy = { type = "target_selector", selector = "/target" }

Fixed-Target Sub-Agent Routing

For scenarios requiring static target assignment without classification:

[routes.agent.subagents]
type = "passthrough"
target = "worker"

Invoking Sub-Agent Routes via Python Bindings

To trigger sub-agent routing programmatically, populate specific metadata fields when constructing requests. The Python bindings in switchyard_rust/libsy.py expose the Rust algorithms to your application code.

import switchyard.libsy as sy

# Construct request with sub-agent metadata markers

request = {
    "llm_request": {
        "model": "openrouter/agent",
        "messages": [{"role": "user", "content": "Please review this code"}],
    },
    "metadata": {
        "session_id": "session-1",
        "agent_id": "child-1",
        "is_subagent": True,
        "is_delegated_work": True,
    },
}

# Execute through Switchyard (actual client construction varies by environment)

outcome = sy.llm_classifier(...).run_stream(request)
print(outcome.selected_model_id)  # Outputs: "reviewer" or "worker"

The metadata fields is_subagent and is_delegated_work signal the SubagentRouter to apply the nested classification policy rather than the parent route's default behavior.

Summary

• Sub-agent routing uses a dedicated subagents table under parent route definitions to handle delegated work separately from primary traffic.
• The Rust implementation in crates/libsy/src/algorithms/subagent.rs provides SubagentRouter and SubagentRouterConfig for request interception and classification.
• Only passthrough and stage_router parent types support sub-agent configuration.
• Classifiers run in custom mode with JSON schema validation, supporting new_session or every_request triggers.
• Message hash fallback is disabled for sub-agents to ensure metadata-driven routing decisions.
• Python clients must include is_subagent: True and is_delegated_work: True in request metadata to activate sub-agent routing logic.

Frequently Asked Questions

What parent route types support sub-agent routing in Switchyard?

Only passthrough and stage_router algorithms expose the subagents configuration table. Other routing types in Switchyard do not support nested sub-agent policies.

How does the sub-agent classifier differ from standard routing classifiers?

Sub-agent classifiers operate within a SubagentRouter wrapper that intercepts metadata-marked requests before they reach the parent algorithm. They require custom mode with explicit JSON schemas and do not support user_turn triggers, unlike standard classifiers which offer broader trigger options.

Can I use message hash fallback for sub-agent routing decisions?

No. The implementation explicitly disables message hash fallback for sub-agents in crates/libsy/src/algorithms/subagent.rs to prevent caching based on content similarity. Child identity must derive from harness metadata fields like agent_id and session_id.

What metadata is required to trigger sub-agent routing?

Requests must include is_subagent: True and is_delegated_work: True in the metadata object, along with valid session_id and agent_id values. These markers enable the SubagentRouter::route method to identify delegated work and apply the appropriate nested classification policy.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}