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

> Discover how Switchyard's sub-agent-aware routing isolates traffic, keeping parent agent requests distinct from delegated sub-agent work for enhanced control and performance.

- Repository: [NVIDIA-NeMo/Switchyard](https://github.com/NVIDIA-NeMo/Switchyard)
- Tags: deep-dive
- Published: 2026-09-12

---

**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`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/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

```toml

# 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:

```toml

# 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`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/docs/routing_algorithms/subagent_routing.md)** — Describes the sub‑agent‑aware routing concept and TOML configuration format
- **[`crates/libsy/src/algorithms/subagent.rs`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/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`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/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`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/crates/switchyard-runner/src/config.rs)** — Parses the `subagents` table from TOML and builds the routing configuration
- **[`crates/switchyard-py/src/libsy_bindings.rs`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/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`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/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`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/crates/libsy/src/algorithms/subagent.rs)**, which handles model name extraction and routing decisions, and **[`crates/libsy/src/algorithms/util/subagent.rs`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/crates/libsy/src/algorithms/util/subagent.rs)**, which manages target name utilities. Configuration parsing occurs in **[`crates/switchyard-runner/src/config.rs`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/crates/switchyard-runner/src/config.rs)**, while Python API bindings are defined in **[`crates/switchyard-py/src/libsy_bindings.rs`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/crates/switchyard-py/src/libsy_bindings.rs)**.