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

> Learn to configure sub-agent routing in Switchyard using the subagents table in your TOML. Route child tasks to specialized classifiers without altering parent-agent policies.

- Repository: [NVIDIA-NeMo/Switchyard](https://github.com/NVIDIA-NeMo/Switchyard)
- Tags: how-to-guide
- Published: 2026-08-22

---

**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`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/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](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/docs/routing_algorithms/subagent_routing.md), 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:

```toml

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

```toml
[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`](https://github.com/NVIDIA-NeMo/Switchyard/blob/main/switchyard_rust/libsy.py) expose the Rust algorithms to your application code.

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