How Switchyard's Sub-Agent-Aware Routing Isolates Traffic for Parent and Delegated Agents

Switchyard's sub-agent-aware routing ensures parent-agent requests follow their configured routing algorithm while automatically diverting delegated sub-agent work to an isolated subagents table with independent model groups and classification policies.

NVIDIA-NeMo/Switchyard implements a sophisticated traffic isolation mechanism that cleanly separates routing decisions between parent agents and their delegated sub-agents. This architecture allows parent routes to maintain algorithms like passthrough or stage_router without interference, while ensuring any work marked as sub-agent delegation bypasses the parent logic entirely. According to the Switchyard source code, this separation is enforced through header detection and distinct TOML configuration namespaces.

How Parent Traffic Maintains Its Routing Policy

Parent routes in Switchyard retain complete control over their traffic through standard routing algorithms. When a request arrives without sub-agent markers, it processes through the parent’s configured logic—whether that is a simple passthrough or a complex stage_router implementation.

Sub-Agent Detection Headers

Switchyard identifies delegated work through the internal x-switchyard-is-subagent header or via OpenAI/Codex sub-agent markers. When present, these signals trigger a complete bypass of the parent’s routing logic. As documented in docs/routing_algorithms/subagent_routing.md, "Sub‑agent‑aware routing leaves parent‑agent traffic with its configured routing algorithm while routing delegated sub‑agent work separately"【/__modal/volumes/vo-cSqLfqnnIwYXEonuEJnnZa/repos/github.com/NVIDIA-NeMo/Switchyard/main/docs/routing_algorithms/subagent_routing.md#L3-L5】. The system immediately hands the request to the nested subagents table, ensuring zero algorithmic overlap.

Isolated Model Groups for Delegated Agents

The [routes.<parent>.subagents] TOML section defines a completely separate routing universe for delegated work. This isolation prevents any model leakage between parent and sub-agent contexts.

Independent Category Definitions

Sub-agent configurations declare their own model categories—typically judge, capable, efficient, and any—that operate independently from parent route definitions. Even if a parent route defines a category with an identical name, the sub-agent only considers models listed under its own table. As stated in the source documentation, "the parent never falls back to a model that belongs exclusively to a sub‑agent"【/__modal/volumes/vo-cSqLfqnnIwYXEonuEJnnZa/repos/github.com/NVIDIA-NeMo/Switchyard/main/docs/routing_algorithms/subagent_routing.md#L76-L79】.

Routing Decision Persistence

The sub-agent table supports persistent classification through the classify_trigger parameter. When set to "new_session", Switchyard reuses the initial classification for all subsequent requests sharing the same session and agent identity. This prevents re-classification on every turn while maintaining consistent routing for the delegated workflow. Alternatively, setting classify_trigger to "every_request" allows dynamic re-evaluation per request【/__modal/volumes/vo-cSqLfqnnIwYXEonuEJnnZa/repos/github.com/NVIDIA-NeMo/Switchyard/main/docs/routing_algorithms/subagent_routing.md#L81-L85】.

Configuring Sub-Agent Routing in Practice

The following TOML configurations demonstrate how parent and sub-agent routing coexist without sharing model groups.

Parent Route with Passthrough Algorithm

# Parent route – normal passthrough routing

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

# Sub‑agent routing – its own classifier and model groups

[routes.agent.subagents]
type = "llm_classifier"
mode = "custom"
models = {
  judge    = ["classifier"],
  capable  = ["reviewer"],
  efficient = ["worker"],
  any      = ["worker", "reviewer"]
}
default_target = "efficient"
classify_trigger = "new_session"
max_output_tokens = 64
prompt = """
Select exactly one target for the delegated task.

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

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

Parent Route with Stage Router

You can change the parent algorithm without affecting sub-agent behavior:

# Parent route now uses Stage Router

[routes.agent]
id = "agent"
type = "stage_router"
capable_target = "reviewer"
efficient_target = "worker"
picker = "efficient_first"
confidence_threshold = 0.7
context_window = 400000

# The nested sub‑agent table remains unchanged

These snippets illustrate how the parent’s algorithm and the sub‑agent’s classifier maintain strict separation of concerns.

Core Implementation Files

Switchyard’s sub-agent routing logic spans multiple crates in the repository:

• docs/routing_algorithms/subagent_routing.md — Describes the sub‑agent‑aware routing concept and TOML configuration format
• crates/libsy/src/algorithms/subagent.rs — Implements runtime logic for extracting sub‑agent model names and routing decisions
• crates/libsy/src/algorithms/util/subagent.rs — Contains utility functions for handling sub‑agent target names and routing tables
• crates/switchyard-runner/src/config.rs — Parses the subagents table from TOML and builds the routing configuration
• crates/switchyard-py/src/libsy_bindings.rs — Exposes the sub‑agent routing API to Python bindings via subagent_models parameters

Summary

• Parent traffic isolation: Parent routes maintain their configured algorithms (passthrough, stage_router) without processing sub-agent requests, which are detected via the x‑switchyard‑is‑subagent header or OpenAI/Codex markers.
• Independent sub-agent policies: The [routes.<parent>.subagents] table defines isolated model groups (judge, capable, efficient, any) that never overlap with parent categories.
• Persistent classification: The classify_trigger parameter controls whether routing decisions persist for an entire session ("new_session") or re-evaluate per request ("every_request").
• Clean architectural separation: Source files like crates/libsy/src/algorithms/subagent.rs enforce strict boundaries between parent and delegated agent traffic.

Frequently Asked Questions

How does Switchyard detect sub-agent traffic?

Switchyard detects sub-agent delegation through the internal x-switchyard-is-subagent header or standard OpenAI/Codex sub-agent markers. When these signals are present, the system bypasses the parent route's algorithm and immediately routes the request to the isolated subagents configuration table.

Can sub-agent model groups overlap with parent route categories?

No. Even if a parent route defines a category with the same name as a sub-agent group (such as capable or efficient), the systems remain isolated. The sub-agent only considers models listed under its own [routes.<parent>.subagents] table, and the parent never falls back to models exclusive to the sub-agent configuration.

What is the purpose of the classify_trigger parameter in sub-agent routing?

The classify_trigger parameter controls classification frequency. Setting it to "new_session" ensures Switchyard reuses the initial routing decision for all subsequent requests sharing the same session and agent identity, reducing overhead. Setting it to "every_request" allows dynamic re-classification on each turn.

Which source files implement the sub-agent routing runtime logic?

The runtime implementation resides in crates/libsy/src/algorithms/subagent.rs, which handles model name extraction and routing decisions, and crates/libsy/src/algorithms/util/subagent.rs, which manages target name utilities. Configuration parsing occurs in crates/switchyard-runner/src/config.rs, while Python API bindings are defined in crates/switchyard-py/src/libsy_bindings.rs.

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