Switchyard lets LLM applications route traffic across models and providers while preserving native OpenAI and Anthropic API compatibility - enabling flexible model selection, benchmarking, and cost/performance optimization.
Rust
feat(libsy): generalize subagent awareness to all algos + subagent UX improvement (#505)
Ayush Agarwala8c4d2ed201e
diff --git a/crates/libsy/src/algorithms.rs b/crates/libsy/src/algorithms.rsindex 2470738ac..fa3453ab9 100644--- a/crates/libsy/src/algorithms.rs+++ b/crates/libsy/src/algorithms.rs@@ -13,6 +13,7 @@ pub mod noop;pub mod passthrough;pub mod rand;pub mod stage;+pub mod subagent;pub mod util;diff --git a/crates/libsy/src/algorithms/passthrough.rs b/crates/libsy/src/algorithms/passthrough.rsindex 6f9952f64..bd2fa5994 100644--- a/crates/libsy/src/algorithms/passthrough.rs+++ b/crates/libsy/src/algorithms/passthrough.rs@@ -1,102 +1,26 @@// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.// SPDX-License-Identifier: Apache-2.0-//! Direct parent routing with an optional delegated-work classifier cascade.+//! Single-target routing for direct model calls and integration diagnostics.use std::sync::Arc;use switchyard_protocol::{ModelId, Request};-use super::fall_through::{DefaultTarget, FallThrough};-use super::util::affinity::{AffinityRouter, ClassifyTrigger};-use super::util::subagent::{SubagentGate, SubagentOverride};-use crate::core::algorithm::{self, Algorithm, Driver};-use crate::core::classifier::Classifier;-use crate::core::state::State;-use crate::{LibsyError, Result, RoutingOutcome};+use crate::core::algorithm::{Algorithm, Driver};+use crate::{Result, RoutingOutcome};-/// Routes parent traffic directly and optionally classifies delegated sub-agent work.+/// Routing algorithm that always selects one configured target.pub struct Passthrough {- parent_target: ModelId,- route: FallThrough<State>,-}--/// Runtime components for classifying and retaining delegated sub-agent work.-pub struct PassthroughSubagentConfig {- /// Targets the delegated-work classifier may select.- pub targets: Vec<ModelId>,- /// Classifier invoked for the first request from each identified child.- pub classifier: Arc<dyn Classifier<State>>,- /// Child target used when `classifier` abstains.- pub default_target: ModelId,- /// Controls whether each child is classified once or on every request.- pub classify_trigger: ClassifyTrigger,- /// Unsupported for child routing because child identity must come from harness metadata.- pub message_hash_fallback: bool,-}--/// Complete construction settings for [`Passthrough`].-pub struct PassthroughConfig {- /// Target used for parent and harness-maintenance traffic.- pub parent_target: ModelId,- /// Optional delegated-work decision gate.- pub subagent: Option<PassthroughSubagentConfig>,+ target: ModelId,}impl Passthrough {- /// Creates direct parent routing, optionally with a decision gate for sub-agents.- ///- /// When configured, the sub-agent classifier runs once per identified child. Its first- /// decision is retained by `session + agent`; an abstaining classifier uses the child- /// default. Root and harness-maintenance traffic continue to the parent target.- ///- /// # Errors- ///- /// Returns an error when the configured child default is not a child target.- pub fn new(config: PassthroughConfig) -> Result<Self> {- let parent_target = config.parent_target;- let route = match config.subagent {- None => FallThrough::new_with_state(vec![parent_target.clone()])- .with_name("passthrough")- .with_classifier(Arc::new(DefaultTarget::new(parent_target.clone()))),- Some(subagent) => {- algorithm::ensure_model_is_target(&subagent.targets, &subagent.default_target)?;- if subagent.message_hash_fallback {- return Err(LibsyError::AlgorithmError {- message: "sub-agent routing cannot use message_hash_fallback".to_string(),- });- }- let mut targets = subagent.targets;- if !targets.contains(&parent_target) {- targets.push(parent_target.clone());- }- let mut route = FallThrough::new_with_state(targets).with_name("passthrough");- match subagent.classify_trigger {- ClassifyTrigger::EveryRequest => {}- ClassifyTrigger::NewSession => {- let affinity = Arc::new(AffinityRouter::for_subagents());- route = route- .with_processor(affinity.clone())- .with_classifier(affinity);- }- ClassifyTrigger::UserTurn => {- return Err(LibsyError::AlgorithmError {- message: "sub-agent routing cannot use classify_trigger = user_turn"- .to_string(),- });- }- }- route- .with_classifier(Arc::new(SubagentGate::new(subagent.classifier)))- .with_classifier(Arc::new(SubagentOverride::new(subagent.default_target)))- .with_classifier(Arc::new(DefaultTarget::new(parent_target.clone())))- }- };-- Ok(Self {- parent_target,- route,- })+ /// Creates an algorithm that always selects `target`.+ pub fn new(target: impl Into<ModelId>) -> Self {+ Self {+ target: target.into(),+ }}}@@ -106,100 +30,24 @@ impl Algorithm for Passthrough {"passthrough"}- async fn route(self: Arc<Self>, driver: Driver, request: Request) -> Result<RoutingOutcome> {- let mut outcome = self.route.execute(driver, request).await?;- // Parent traffic preserves passthrough's no-fallback contract. Child traffic may- // fall back only within the child target set, never into the parent route.- if outcome.selected_model_id == self.parent_target {- outcome.fallback_models.clear();- } else {- outcome- .fallback_models- .retain(|target| *target != self.parent_target);- }- Ok(outcome)+ async fn route(self: Arc<Self>, _driver: Driver, request: Request) -> Result<RoutingOutcome> {+ tracing::info!(target = %self.target, "passthrough selected target");+ Ok(RoutingOutcome::route_to(+ self.target.clone(),+ Vec::new(),+ request,+ ))}}#[cfg(test)]mod tests {use std::sync::Arc;- use std::sync::atomic::{AtomicUsize, Ordering};- use async_trait::async_trait;- use parking_lot::Mutex;- use serde_json::json;-- use super::{Passthrough, PassthroughConfig, PassthroughSubagentConfig};+ use super::Passthrough;use crate::core::algorithm::Algorithm;- use crate::core::classifier::{Classification, Classifier, Score};- use crate::core::testing::{echo, reply, test_drive};- use crate::{- ClassifyTrigger, CustomClassifierConfig, CustomClassifierPolicy, Driver,- LlmClassifierConfig, LlmTaskClassifier, State,- };- use switchyard_protocol::{- ContentBlock, InstructionBlock, Message, Metadata, ModelId, Request, Response, Role,- completion_text, text_request,- };-- struct ScriptedClassifier {- calls: AtomicUsize,- }-- #[async_trait]- impl Classifier<State> for ScriptedClassifier {- async fn score(- &self,- _state: &mut State,- _request: &mut Request,- _driver: Option<&Driver>,- ) -> crate::Result<(Classification, Option<Response>)> {- let scores = match self.calls.fetch_add(1, Ordering::Relaxed) {- 0 => vec![Score {- confidence: 1.0,- target: ModelId::from("worker"),- }],- 1 => vec![Score {- confidence: 1.0,- target: ModelId::from("reviewer"),- }],- _ => Vec::new(),- };- Ok((Classification::Scores(scores), None))- }- }-- fn request(metadata: Option<Metadata>) -> Request {- Request {- llm_request: text_request(Some("auto".to_string()), "hi"),- raw_request: None,- metadata,- }- }-- fn child(agent_id: &str) -> Request {- request(Some(Metadata {- session_id: Some("session-1".to_string()),- agent_id: Some(agent_id.to_string()),- is_subagent: true,- is_delegated_work: true,- ..Metadata::default()- }))- }-- fn configured(classifier: Arc<dyn Classifier<State>>) -> crate::Result<Arc<Passthrough>> {- Ok(Arc::new(Passthrough::new(PassthroughConfig {- parent_target: ModelId::from("parent"),- subagent: Some(PassthroughSubagentConfig {- targets: vec![ModelId::from("worker"), ModelId::from("reviewer")],- classifier,- default_target: ModelId::from("worker"),- classify_trigger: ClassifyTrigger::NewSession,- message_hash_fallback: false,- }),- })?))- }+ use crate::core::testing::{echo, test_drive};+ use switchyard_protocol::{Request, completion_text, text_request};#[tokio::test]async fn test_passthrough() -> crate::Result<()> {@@ -209,10 +57,7 @@ mod tests {raw_request: None,metadata: None,};- let algorithm: Arc<dyn Algorithm> = Arc::new(Passthrough::new(PassthroughConfig {- parent_target: ModelId::from(MODEL_ID),- subagent: None,- })?);+ let algorithm: Arc<dyn Algorithm> = Arc::new(Passthrough::new(MODEL_ID));let (selected_model, response) = test_drive(algorithm, request, echo()).await?;assert_eq!(@@ -226,112 +71,4 @@ mod tests {assert_eq!(selected_model, MODEL_ID);Ok(())}-- #[tokio::test]- async fn routes_parent_and_children_with_affinity_and_default() -> crate::Result<()> {- let classifier = Arc::new(ScriptedClassifier {- calls: AtomicUsize::new(0),- });- let router = configured(classifier.clone())?;-- let (parent, _) = test_drive(router.clone(), request(None), echo()).await?;- let (first, _) = test_drive(router.clone(), child("child-1"), echo()).await?;- let (same_child, _) = test_drive(router.clone(), child("child-1"), echo()).await?;- let (sibling, _) = test_drive(router.clone(), child("child-2"), echo()).await?;- let (defaulted, _) = test_drive(router.clone(), child("child-3"), echo()).await?;- let maintenance = request(Some(Metadata {- session_id: Some("session-1".to_string()),- agent_id: Some("child-1".to_string()),- is_subagent: true,- is_delegated_work: false,- ..Metadata::default()- }));- let (maintenance, _) = test_drive(router, maintenance, echo()).await?;-- assert_eq!(parent, "parent");- assert_eq!(first, "worker");- assert_eq!(same_child, "worker");- assert_eq!(sibling, "reviewer");- assert_eq!(defaulted, "worker");- assert_eq!(maintenance, "parent");- assert_eq!(classifier.calls.load(Ordering::Relaxed), 3);- Ok(())- }-- #[tokio::test]- async fn custom_classifier_receives_only_the_delegated_prompt() -> crate::Result<()> {- let classifier = LlmTaskClassifier::new(LlmClassifierConfig::Custom {- judge_target: ModelId::from("judge"),- targets: vec![- ("worker".to_string(), ModelId::from("worker")),- ("reviewer".to_string(), ModelId::from("reviewer")),- ],- default_target: "worker".to_string(),- config: CustomClassifierConfig::new(- "classify the delegated task",- json!({- "type": "object",- "properties": {- "target": {"type": "string", "enum": ["worker", "reviewer"]}- },- "required": ["target"],- "additionalProperties": false- }),- CustomClassifierPolicy::target_selector("/target"),- ),- })?;- let router = configured(Arc::new(classifier))?;- let mut request = child("child-1");- request.llm_request.instructions = vec![InstructionBlock {- role: Role::System,- content: Message::text(Role::System, "child system instructions").content,- }];- request.llm_request.messages = vec![- Message::text(Role::User, "harness context"),- Message {- role: Role::User,- content: vec![- ContentBlock::Text {- text: "<system-reminder>tool context</system-reminder>".to_string(),- },- ContentBlock::Text {- text: "review this parser".to_string(),- },- ],- },- ];- let calls = Arc::new(Mutex::new(Vec::new()));- let served_calls = calls.clone();-- let (selected, _) = test_drive(router, request, move |target, request| {- let calls = served_calls.clone();- async move {- let completion = if target == "judge" {- r#"{"target":"reviewer"}"#- } else {- "child answer"- };- calls.lock().push((target, request));- Ok(reply(completion))- }- })- .await?;-- assert_eq!(selected, "reviewer");- let calls = calls.lock();- assert_eq!(calls.len(), 2);- assert_eq!(calls[0].0, "judge");- assert_eq!(- calls[0].1.llm_request.instructions[0].content,- Message::text(Role::System, "classify the delegated task").content- );- assert_eq!(- calls[0].1.llm_request.messages,- vec![Message::text(Role::User, "review this parser")]- );- assert_eq!(calls[1].0, "reviewer");- assert_eq!(calls[1].1.llm_request.instructions.len(), 1);- assert_eq!(calls[1].1.llm_request.messages.len(), 2);- Ok(())- }}diff --git a/crates/libsy/src/algorithms/subagent.rs b/crates/libsy/src/algorithms/subagent.rsnew file mode 100644index 000000000..bb918f05e--- /dev/null+++ b/crates/libsy/src/algorithms/subagent.rs@@ -0,0 +1,304 @@+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.+// SPDX-License-Identifier: Apache-2.0++//! Delegated sub-agent routing around an arbitrary parent algorithm.++use std::sync::Arc;++use switchyard_protocol::{Metadata, ModelId, Request};++use super::fall_through::{DefaultTarget, FallThrough};+use super::util::affinity::{AffinityRouter, ClassifyTrigger};+use super::util::subagent::SubagentGate;+use crate::core::algorithm::{self, Algorithm, Driver};+use crate::core::classifier::Classifier;+use crate::core::state::State;+use crate::{LibsyError, Result, RoutingOutcome};++/// Runtime components for delegated sub-agent routing.+pub struct SubagentRouterConfig {+ /// Targets the delegated-work classifier may select.+ pub targets: Vec<ModelId>,+ /// Classifier invoked for delegated work according to `classify_trigger`.+ pub classifier: Arc<dyn Classifier<State>>,+ /// Child target used when `classifier` abstains.+ pub default_target: ModelId,+ /// Controls whether each child is classified once or on every request.+ pub classify_trigger: ClassifyTrigger,+ /// Unsupported for child routing because child identity must come from harness metadata.+ pub message_hash_fallback: bool,+}++impl SubagentRouterConfig {+ /// Routes delegated work directly to one fixed target.+ pub fn fixed_target(target: impl Into<ModelId>) -> Self {+ let target = target.into();+ Self {+ targets: vec![target.clone()],+ classifier: Arc::new(DefaultTarget::new(target.clone())),+ default_target: target,+ classify_trigger: ClassifyTrigger::EveryRequest,+ message_hash_fallback: false,+ }+ }+}++/// Routes delegated work independently while preserving the parent algorithm for other traffic.+pub struct SubagentRouter {+ parent: Arc<dyn Algorithm>,+ subagent: FallThrough<State>,+}++impl SubagentRouter {+ /// Wraps `parent` with the configured delegated-work route.+ ///+ /// # Errors+ ///+ /// Returns an error when the child default is not a child target or when the affinity+ /// settings cannot identify delegated children safely.+ pub fn new(parent: Arc<dyn Algorithm>, config: SubagentRouterConfig) -> Result<Self> {+ algorithm::ensure_model_is_target(&config.targets, &config.default_target)?;+ if config.message_hash_fallback {+ return Err(LibsyError::AlgorithmError {+ message: "sub-agent routing cannot use message_hash_fallback".to_string(),+ });+ }++ let mut subagent = match config.classify_trigger {+ ClassifyTrigger::EveryRequest => {+ FallThrough::new_with_state(config.targets).with_name("subagent")+ }+ ClassifyTrigger::NewSession => {+ let affinity = Arc::new(AffinityRouter::for_subagents());+ FallThrough::new_with_state(config.targets)+ .with_name("subagent")+ .with_processor(affinity.clone())+ .with_classifier(affinity)+ }+ ClassifyTrigger::UserTurn => {+ return Err(LibsyError::AlgorithmError {+ message: "sub-agent routing cannot use classify_trigger = user_turn"+ .to_string(),+ });+ }+ };+ subagent = subagent+ .with_classifier(Arc::new(SubagentGate::new(config.classifier)))+ .with_classifier(Arc::new(DefaultTarget::new(config.default_target)));++ Ok(Self { parent, subagent })+ }+}++#[async_trait::async_trait]+impl Algorithm for SubagentRouter {+ fn name(&self) -> &str {+ self.parent.name()+ }++ async fn route(self: Arc<Self>, driver: Driver, request: Request) -> Result<RoutingOutcome> {+ if request+ .metadata+ .as_ref()+ .is_some_and(Metadata::is_subagent_work)+ {+ self.subagent.execute(driver, request).await+ } else {+ self.parent.clone().route(driver, request).await+ }+ }+}++#[cfg(test)]+mod tests {+ use std::sync::Arc;+ use std::sync::atomic::{AtomicUsize, Ordering};++ use async_trait::async_trait;+ use parking_lot::Mutex;+ use serde_json::json;+ use switchyard_protocol::{+ ContentBlock, InstructionBlock, Message, Metadata, ModelId, Request, Response, Role,+ text_request,+ };++ use super::{SubagentRouter, SubagentRouterConfig};+ use crate::algorithms::passthrough::Passthrough;+ use crate::core::algorithm::Algorithm;+ use crate::core::classifier::{Classification, Classifier, Score};+ use crate::core::testing::{echo, reply, test_drive};+ use crate::{+ ClassifyTrigger, CustomClassifierConfig, CustomClassifierPolicy, Driver,+ LlmClassifierConfig, LlmTaskClassifier, State,+ };++ struct ScriptedClassifier {+ calls: AtomicUsize,+ }++ #[async_trait]+ impl Classifier<State> for ScriptedClassifier {+ async fn score(+ &self,+ _state: &mut State,+ _request: &mut Request,+ _driver: Option<&Driver>,+ ) -> crate::Result<(Classification, Option<Response>)> {+ let scores = match self.calls.fetch_add(1, Ordering::Relaxed) {+ 0 => vec![Score {+ confidence: 1.0,+ target: ModelId::from("worker"),+ }],+ 1 => vec![Score {+ confidence: 1.0,+ target: ModelId::from("reviewer"),+ }],+ _ => Vec::new(),+ };+ Ok((Classification::Scores(scores), None))+ }+ }++ fn request(metadata: Option<Metadata>) -> Request {+ Request {+ llm_request: text_request(Some("auto".to_string()), "hi"),+ raw_request: None,+ metadata,+ }+ }++ fn child(agent_id: &str) -> Request {+ request(Some(Metadata {+ session_id: Some("session-1".to_string()),+ agent_id: Some(agent_id.to_string()),+ is_subagent: true,+ is_delegated_work: true,+ ..Metadata::default()+ }))+ }++ fn parent() -> Arc<dyn Algorithm> {+ Arc::new(Passthrough::new("parent"))+ }++ fn configured(classifier: Arc<dyn Classifier<State>>) -> crate::Result<Arc<SubagentRouter>> {+ Ok(Arc::new(SubagentRouter::new(+ parent(),+ SubagentRouterConfig {+ targets: vec![ModelId::from("worker"), ModelId::from("reviewer")],+ classifier,+ default_target: ModelId::from("worker"),+ classify_trigger: ClassifyTrigger::NewSession,+ message_hash_fallback: false,+ },+ )?))+ }++ #[tokio::test]+ async fn routes_parent_and_children_with_affinity_and_default() -> crate::Result<()> {+ let classifier = Arc::new(ScriptedClassifier {+ calls: AtomicUsize::new(0),+ });+ let router = configured(classifier.clone())?;++ let (parent, _) = test_drive(router.clone(), request(None), echo()).await?;+ let (first, _) = test_drive(router.clone(), child("child-1"), echo()).await?;+ let (same_child, _) = test_drive(router.clone(), child("child-1"), echo()).await?;+ let (sibling, _) = test_drive(router.clone(), child("child-2"), echo()).await?;+ let (defaulted, _) = test_drive(router.clone(), child("child-3"), echo()).await?;+ let maintenance = request(Some(Metadata {+ session_id: Some("session-1".to_string()),+ agent_id: Some("child-1".to_string()),+ is_subagent: true,+ is_delegated_work: false,+ ..Metadata::default()+ }));+ let (maintenance, _) = test_drive(router, maintenance, echo()).await?;++ assert_eq!(parent, "parent");+ assert_eq!(first, "worker");+ assert_eq!(same_child, "worker");+ assert_eq!(sibling, "reviewer");+ assert_eq!(defaulted, "worker");+ assert_eq!(maintenance, "parent");+ assert_eq!(classifier.calls.load(Ordering::Relaxed), 3);+ Ok(())+ }++ #[tokio::test]+ async fn custom_classifier_receives_only_the_delegated_prompt() -> crate::Result<()> {+ let classifier = LlmTaskClassifier::new(LlmClassifierConfig::Custom {+ judge_target: ModelId::from("judge"),+ targets: vec![+ ("worker".to_string(), ModelId::from("worker")),+ ("reviewer".to_string(), ModelId::from("reviewer")),+ ],+ default_target: "worker".to_string(),+ config: CustomClassifierConfig::new(+ "classify the delegated task",+ json!({+ "type": "object",+ "properties": {+ "target": {"type": "string", "enum": ["worker", "reviewer"]}+ },+ "required": ["target"],+ "additionalProperties": false+ }),+ CustomClassifierPolicy::target_selector("/target"),+ ),+ })?;+ let router = configured(Arc::new(classifier))?;+ let mut request = child("child-1");+ request.llm_request.instructions = vec![InstructionBlock {+ role: Role::System,+ content: Message::text(Role::System, "child system instructions").content,+ }];+ request.llm_request.messages = vec![+ Message::text(Role::User, "harness context"),+ Message {+ role: Role::User,+ content: vec![+ ContentBlock::Text {+ text: "<system-reminder>tool context</system-reminder>".to_string(),+ },+ ContentBlock::Text {+ text: "review this parser".to_string(),+ },+ ],+ },+ ];+ let calls = Arc::new(Mutex::new(Vec::new()));+ let served_calls = calls.clone();++ let (selected, _) = test_drive(router, request, move |target, request| {+ let calls = served_calls.clone();+ async move {+ let completion = if target == "judge" {+ r#"{"target":"reviewer"}"#+ } else {+ "child answer"+ };+ calls.lock().push((target, request));+ Ok(reply(completion))+ }+ })+ .await?;++ assert_eq!(selected, "reviewer");+ let calls = calls.lock();+ assert_eq!(calls.len(), 2);+ assert_eq!(calls[0].0, "judge");+ assert_eq!(+ calls[0].1.llm_request.instructions[0].content,+ Message::text(Role::System, "classify the delegated task").content+ );+ assert_eq!(+ calls[0].1.llm_request.messages,+ vec![Message::text(Role::User, "review this parser")]+ );+ assert_eq!(calls[1].0, "reviewer");+ assert_eq!(calls[1].1.llm_request.instructions.len(), 1);+ assert_eq!(calls[1].1.llm_request.messages.len(), 2);+ Ok(())+ }+}diff --git a/crates/libsy/src/lib.rs b/crates/libsy/src/lib.rsindex b1f9c2943..8ae823689 100644--- a/crates/libsy/src/lib.rs+++ b/crates/libsy/src/lib.rs@@ -20,9 +20,10 @@ pub use algorithms::llm_class::{TaskClassifierConfig,};pub use algorithms::noop::Noop;-pub use algorithms::passthrough::{Passthrough, PassthroughConfig, PassthroughSubagentConfig};+pub use algorithms::passthrough::Passthrough;pub use algorithms::rand::{Random, RandomClassifier};pub use algorithms::stage::{LlmFallback, StageRouter, StageRouterConfig};+pub use algorithms::subagent::{SubagentRouter, SubagentRouterConfig};pub use algorithms::util::affinity::{AffinityRouter, ClassifyTrigger};pub use algorithms::util::classifier_contract::{ClassifierContractConfig, ClassifierResponseFormat,diff --git a/crates/switchyard-server/src/config.rs b/crates/switchyard-server/src/config.rsindex feee52ca7..77373959b 100644--- a/crates/switchyard-server/src/config.rs+++ b/crates/switchyard-server/src/config.rs@@ -12,8 +12,8 @@ use libsy::{AdvisorGate, AdvisorGateConfig, Algorithm, ClassifierContractConfig, ClassifierResponseFormat,ClassifyTrigger, CustomClassifierConfig, CustomClassifierPolicy, EscalationJudgeConfig,GateTrigger, HandoffNoteConfig, LlmClassifierConfig, LlmFallback, LlmTaskClassifier, Noop,- Passthrough, PassthroughConfig, PassthroughSubagentConfig, PickerMode, Random, StageRouter,- StageRouterConfig, TargetPrompts, TaskClassifierConfig,+ Passthrough, PickerMode, Random, StageRouter, StageRouterConfig, SubagentRouter,+ SubagentRouterConfig, TargetPrompts, TaskClassifierConfig,};use serde::Deserialize;use serde_json::Value;@@ -396,8 +396,7 @@ struct EscalationClassifierRouteConfig {judge: EscalationJudgeConfig,}-#[derive(Clone, Debug, Deserialize)]-#[serde(deny_unknown_fields)]+#[derive(Debug)]struct CustomClassifierRouteConfig {classifier_target: String,targets: Vec<String>,@@ -405,14 +404,61 @@ struct CustomClassifierRouteConfig {prompt: String,response_schema: String,policy: ClassifierPolicyConfig,- #[serde(default)]classify_trigger: ClassifyTrigger,- #[serde(default)]message_hash_fallback: bool,- #[serde(default)]recent_turn_window: Option<usize>,+ max_output_tokens: u64,+}++#[derive(Debug, Default, Deserialize)]+#[serde(default, deny_unknown_fields)]+struct LlmClassifierRouteConfig {+ classifier_target: String,+ mode: Option<ClassifierMode>,+ strong_target: Option<String>,+ weak_target: Option<String>,+ base_threshold: Option<f64>,+ threshold_step: Option<f64>,+ classify_trigger: ClassifyTrigger,+ message_hash_fallback: bool,+ recent_turn_window: Option<usize>,+ prompt: Option<String>,+ response_format_type: ClassifierResponseFormat,#[serde(default = "default_classifier_max_output_tokens")]max_output_tokens: u64,+ escalation: Option<EscalationJudgeConfig>,+ targets: Option<Vec<String>>,+ default_target: Option<String>,+ response_schema: Option<String>,+ policy: Option<ClassifierPolicyConfig>,+}++#[derive(Debug, Deserialize)]+#[serde(tag = "type", rename_all = "snake_case", deny_unknown_fields)]+enum SubagentRouteConfig {+ Passthrough { target: String },+ LlmClassifier(Box<LlmClassifierRouteConfig>),+}++impl SubagentRouteConfig {+ fn routing_target_names(&self) -> Vec<&str> {+ match self {+ Self::Passthrough { target } => vec![target],+ Self::LlmClassifier(classifier) => classifier+ .targets+ .iter()+ .flatten()+ .map(String::as_str)+ .collect(),+ }+ }++ fn classifier_target_name(&self) -> Option<&str> {+ match self {+ Self::LlmClassifier(classifier) => Some(&classifier.classifier_target),+ Self::Passthrough { .. } => None,+ }+ }}#[derive(Debug, Deserialize)]@@ -449,7 +495,7 @@ enum RouteConfig {reasoning: Option<bool>,target: String,#[serde(default)]- subagent_classifier: Option<CustomClassifierRouteConfig>,+ subagents: Option<SubagentRouteConfig>,},LlmClassifier {id: ModelId,@@ -459,39 +505,8 @@ enum RouteConfig {tool_calling: Option<bool>,#[serde(default)]reasoning: Option<bool>,- classifier_target: String,- #[serde(default)]- mode: Option<ClassifierMode>,- #[serde(default)]- strong_target: Option<String>,- #[serde(default)]- weak_target: Option<String>,- #[serde(default)]- base_threshold: Option<f64>,- #[serde(default)]- threshold_step: Option<f64>,- #[serde(default)]- classify_trigger: ClassifyTrigger,- #[serde(default)]- message_hash_fallback: bool,- #[serde(default)]- recent_turn_window: Option<usize>,- #[serde(default)]- prompt: Option<String>,- #[serde(default)]- response_format_type: ClassifierResponseFormat,- #[serde(default = "default_classifier_max_output_tokens")]- max_output_tokens: u64,- #[serde(default)]- escalation: Option<EscalationJudgeConfig>,- #[serde(default)]- targets: Option<Vec<String>>,- #[serde(default)]- default_target: Option<String>,- #[serde(default)]- response_schema: Option<String>,- #[serde(default)]- policy: Option<ClassifierPolicyConfig>,+ #[serde(flatten)]+ config: LlmClassifierRouteConfig,},StageRouter {id: ModelId,@@ -520,6 +535,9 @@ enum RouteConfig {/// Capability judge consulted on turns the signals leave undecided.#[serde(default)]classifier: Option<StageClassifierConfig>,+ /// Optional routing applied only to delegated sub-agent work.+ #[serde(default)]+ subagents: Option<SubagentRouteConfig>,},Advisor {id: ModelId,@@ -627,45 +645,52 @@ impl RouteConfig {Self::Noop { .. } => Vec::new(),Self::Random { targets, .. } => targets.iter().map(String::as_str).collect(),Self::Passthrough {- target,- subagent_classifier,- ..+ target, subagents, ..} => {let mut names = vec![target.as_str()];- if let Some(classifier) = subagent_classifier {- names.extend(classifier.targets.iter().map(String::as_str));+ if let Some(subagents) = subagents {+ names.extend(subagents.routing_target_names());}names}- Self::LlmClassifier {- mode,- strong_target,- weak_target,- escalation,- targets,- ..- } => match mode.unwrap_or(if escalation.is_some() {- ClassifierMode::Escalation- } else {- ClassifierMode::Capability- }) {- ClassifierMode::Capability => weak_target- .iter()- .chain(strong_target)- .map(String::as_str)- .collect(),- ClassifierMode::Escalation => strong_target- .iter()- .chain(weak_target)- .map(String::as_str)- .collect(),- ClassifierMode::Custom => targets.iter().flatten().map(String::as_str).collect(),- },+ Self::LlmClassifier { config, .. } => {+ match config.mode.unwrap_or(if config.escalation.is_some() {+ ClassifierMode::Escalation+ } else {+ ClassifierMode::Capability+ }) {+ ClassifierMode::Capability => config+ .weak_target+ .iter()+ .chain(&config.strong_target)+ .map(String::as_str)+ .collect(),+ ClassifierMode::Escalation => config+ .strong_target+ .iter()+ .chain(&config.weak_target)+ .map(String::as_str)+ .collect(),+ ClassifierMode::Custom => config+ .targets+ .iter()+ .flatten()+ .map(String::as_str)+ .collect(),+ }+ }Self::StageRouter {capable_target,efficient_target,+ subagents,..- } => vec![capable_target, efficient_target],+ } => {+ let mut names = vec![capable_target.as_str(), efficient_target.as_str()];+ if let Some(subagents) = subagents {+ names.extend(subagents.routing_target_names());+ }+ names+ }// The advisor is judge-only: reviews go through its own client,// so it is not a completion (or count_tokens) destination.Self::Advisor {@@ -681,17 +706,23 @@ impl RouteConfig {fn callable_target_names(&self) -> Vec<&str> {let mut names = self.routing_target_names();match self {- Self::LlmClassifier {- classifier_target, ..- } => names.push(classifier_target),+ Self::LlmClassifier { config, .. } => names.push(&config.classifier_target),Self::Passthrough {- subagent_classifier: Some(classifier),+ subagents: Some(subagents),..- } => names.push(&classifier.classifier_target),+ } => names.extend(subagents.classifier_target_name()),Self::StageRouter {- classifier: Some(classifier),+ classifier,+ subagents,..- } => names.push(&classifier.target),+ } => {+ if let Some(classifier) = classifier {+ names.push(&classifier.target);+ }+ if let Some(subagents) = subagents {+ names.extend(subagents.classifier_target_name());+ }+ }Self::Advisor { advisor_target, .. } => names.push(advisor_target),_ => {}}@@ -743,9 +774,11 @@ impl RouteConfig {},}}+}+impl LlmClassifierRouteConfig {fn classifier_mode(&self, route_name: &str) -> ServerResult<LlmClassifierModeConfig> {- let Self::LlmClassifier {+ let Self {classifier_target,mode,strong_target,@@ -763,11 +796,7 @@ impl RouteConfig {default_target,response_schema,policy,- ..- } = self- else {- return Err(ServerError::new("route is not an llm_classifier"));- };+ } = self;let selected_mode = match (mode, escalation.is_some()) {(Some(mode), _) => *mode,@@ -996,6 +1025,100 @@ const fn default_max_retries() -> u32 {DEFAULT_MAX_RETRIES}+// Resolve nested policy once so every supported parent builds the same child route.+fn build_subagent_router_config(+ route_name: &str,+ config: &SubagentRouteConfig,+ targets: &BTreeMap<String, ModelId>,+) -> ServerResult<SubagentRouterConfig> {+ match config {+ SubagentRouteConfig::Passthrough { target } => Ok(SubagentRouterConfig::fixed_target(+ resolve_target_model_id(route_name, target, targets)?,+ )),+ SubagentRouteConfig::LlmClassifier(config) => {+ let LlmClassifierModeConfig::Custom(config) = config.classifier_mode(route_name)?+ else {+ return Err(ServerError::new(format!(+ "route {route_name}: subagents llm_classifier only supports mode custom"+ )));+ };+ let judge_target =+ resolve_target_model_id(route_name, &config.classifier_target, targets)?;+ let resolved_targets = config+ .targets+ .iter()+ .map(|name| {+ resolve_target_model_id(route_name, name, targets)+ .map(|target| (name.clone(), target))+ })+ .collect::<ServerResult<Vec<_>>>()?;+ let default_target = resolved_targets+ .iter()+ .find(|(name, _)| *name == config.default_target)+ .map(|(_, target)| target.clone())+ .ok_or_else(|| {+ ServerError::new(format!(+ "route {route_name}: subagents llm_classifier default_target {:?} must be one of its configured targets",+ config.default_target+ ))+ })?;+ let response_schema =+ serde_json::from_str(&config.response_schema).map_err(|error| {+ ServerError::new(format!(+ "route {route_name}: subagents llm_classifier response_schema is invalid JSON: {error}"+ ))+ })?;+ let mut classifier_config = CustomClassifierConfig::new(+ config.prompt,+ response_schema,+ config.policy.into_libsy(),+ );+ classifier_config.recent_turn_window = config.recent_turn_window;+ classifier_config.max_output_tokens = config.max_output_tokens;+ let subagent_targets = resolved_targets+ .iter()+ .map(|(_, target)| target.clone())+ .collect();+ let classifier = Arc::new(+ LlmTaskClassifier::new(LlmClassifierConfig::Custom {+ judge_target,+ targets: resolved_targets,+ default_target: config.default_target,+ config: classifier_config,+ })+ .map_err(|error| {+ ServerError::new(format!(+ "route {route_name}: subagents llm_classifier: {error}"+ ))+ })?,+ );+ Ok(SubagentRouterConfig {+ targets: subagent_targets,+ classifier,+ default_target,+ classify_trigger: config.classify_trigger,+ message_hash_fallback: config.message_hash_fallback,+ })+ }+ }+}++fn attach_subagent_router(+ route_name: &str,+ parent: Arc<dyn Algorithm>,+ config: Option<&SubagentRouteConfig>,+ targets: &BTreeMap<String, ModelId>,+) -> ServerResult<Arc<dyn Algorithm>> {+ let Some(config) = config else {+ return Ok(parent);+ };+ let config = build_subagent_router_config(route_name, config, targets)?;+ let algorithm = SubagentRouter::new(parent, config).map_err(|error| {+ ServerError::new(format!("route {route_name}: subagent routing: {error}"))+ })?;+ Ok(Arc::new(algorithm))+}+fn build_algorithm(route_name: &str,config: &RouteConfig,@@ -1016,86 +1139,20 @@ fn build_algorithm(Ok(Arc::new(algorithm))}RouteConfig::Passthrough {- target,- subagent_classifier,- ..+ target, subagents, ..} => {let parent_target = resolve_target_model_id(route_name, target, targets)?;- let subagent = if let Some(config) = subagent_classifier {- let judge_target =- resolve_target_model_id(route_name, &config.classifier_target, targets)?;- let resolved_targets = config- .targets- .iter()- .map(|name| {- resolve_target_model_id(route_name, name, targets)- .map(|target| (name.clone(), target))- })- .collect::<ServerResult<Vec<_>>>()?;- let subagent_default_target = resolved_targets- .iter()- .find(|(name, _)| *name == config.default_target)- .map(|(_, target)| target.clone())- .ok_or_else(|| {- ServerError::new(format!(- "passthrough route {route_name}: subagent_classifier default_target {:?} must be one of its configured targets",- config.default_target- ))- })?;- let response_schema =- serde_json::from_str(&config.response_schema).map_err(|error| {- ServerError::new(format!(- "passthrough route {route_name}: subagent_classifier response_schema is invalid JSON: {error}"- ))- })?;- let mut classifier_config = CustomClassifierConfig::new(- config.prompt.clone(),- response_schema,- config.policy.clone().into_libsy(),- );- classifier_config.recent_turn_window = config.recent_turn_window;- classifier_config.max_output_tokens = config.max_output_tokens;- let subagent_targets = resolved_targets- .iter()- .map(|(_, target)| target.clone())- .collect();- let classifier = Arc::new(- LlmTaskClassifier::new(LlmClassifierConfig::Custom {- judge_target,- targets: resolved_targets,- default_target: config.default_target.clone(),- config: classifier_config,- })- .map_err(|error| {- ServerError::new(format!(- "passthrough route {route_name}: subagent_classifier: {error}"- ))- })?,- );- Some(PassthroughSubagentConfig {- targets: subagent_targets,- classifier,- default_target: subagent_default_target,- classify_trigger: config.classify_trigger,- message_hash_fallback: config.message_hash_fallback,- })- } else {- None- };- let algorithm = Passthrough::new(PassthroughConfig {- parent_target,- subagent,- })- .map_err(|error| {- ServerError::new(format!("passthrough route {route_name}: {error}"))- })?;- Ok(Arc::new(algorithm))+ let algorithm = Passthrough::new(parent_target);+ let parent: Arc<dyn Algorithm> = Arc::new(algorithm);+ attach_subagent_router(route_name, parent, subagents.as_ref(), targets)}RouteConfig::LlmClassifier {- classifier_target, ..+ config: classifier_config,+ ..} => {- let classifier = resolve_target_model_id(route_name, classifier_target, targets)?;- let mode = config.classifier_mode(route_name)?;+ let classifier =+ resolve_target_model_id(route_name, &classifier_config.classifier_target, targets)?;+ let mode = classifier_config.classifier_mode(route_name)?;let algorithm = match mode {LlmClassifierModeConfig::Capability(config) => {let strong =@@ -1180,6 +1237,7 @@ fn build_algorithm(capable_system_prompt,efficient_system_prompt,classifier,+ subagents,..} => {if matches!(picker, PickerMode::CapableFirst) {@@ -1214,7 +1272,8 @@ fn build_algorithm(let algorithm = StageRouter::new(capable, efficient, config).map_err(|error| {ServerError::new(format!("stage_router route {route_name}: {error}"))})?;- Ok(Arc::new(algorithm))+ let parent: Arc<dyn Algorithm> = Arc::new(algorithm);+ attach_subagent_router(route_name, parent, subagents.as_ref(), targets)}RouteConfig::Advisor {executor_target,@@ -1407,15 +1466,12 @@ target = "weak"}}- fn passthrough_with_subagent_classifier(extra: &str) -> String {- let configured = VALID_CONFIG.replace(- "[routes.passthrough]\nid = \"switchyard/passthrough\"\ntype = \"passthrough\"\ntarget = \"weak\"",- r#"[routes.passthrough]-id = "switchyard/passthrough"-type = "passthrough"-target = "weak"--[routes.passthrough.subagent_classifier]+ fn with_subagent_llm_classifier(config: &str, route: &str, extra: &str) -> String {+ let mut configured = config.to_string();+ configured.push_str(&format!("\n[routes.{route}.subagents]\n"));+ configured.push_str(+ r#"type = "llm_classifier"+mode = "custom"classifier_target = "classifier"targets = ["strong", "weak"]default_target = "weak"@@ -1424,9 +1480,33 @@ response_schema = '{"type":"object","properties":{"target":{"type":"string","enupolicy = { type = "target_selector", selector = "/target" }classify_trigger = "new_session""#,);- configured.replace(- "classify_trigger = \"new_session\"",- &format!("classify_trigger = \"new_session\"{extra}"),+ configured.push_str(extra);+ configured+ }++ fn with_subagent_passthrough(config: &str, route: &str) -> String {+ format!("{config}\n[routes.{route}.subagents]\ntype = \"passthrough\"\ntarget = \"strong\"")+ }++ fn stage_config() -> String {+ format!(+ r#"{VALID_CONFIG}+[targets.stage_judge]+id = "stage-judge/model"+llm_client = "primary"++[routes.stage]+id = "switchyard/stage"+type = "stage_router"+capable_target = "strong"+efficient_target = "weak"+picker = "efficient_first"+confidence_threshold = 1.0++[routes.stage.classifier]+target = "stage_judge"+base_threshold = 0.5+"#)}@@ -1447,10 +1527,27 @@ classify_trigger = "new_session""#,}#[test]- fn passthrough_accepts_a_custom_subagent_classifier() -> ServerResult<()> {- let configured = passthrough_with_subagent_classifier("");+ fn passthrough_and_stage_accept_subagent_routing() -> ServerResult<()> {+ let stage = stage_config();+ let stage_with_classifier = with_subagent_llm_classifier(&stage, "stage", "");+ let parsed: ServerConfig = toml::from_str(&stage_with_classifier)+ .map_err(|error| ServerError::new(format!("failed to parse stage config: {error}")))?;+ let Some(stage_route) = parsed.routes.get("stage") else {+ return Err(ServerError::new("stage route is missing"));+ };+ let callable_targets = stage_route.callable_target_names();+ for expected in ["strong", "weak", "stage_judge", "classifier"] {+ assert!(callable_targets.contains(&expected));+ }- server_state_from_toml(&configured)?;+ for configured in [+ with_subagent_llm_classifier(VALID_CONFIG, "passthrough", ""),+ with_subagent_passthrough(VALID_CONFIG, "passthrough"),+ stage_with_classifier,+ with_subagent_passthrough(&stage, "stage"),+ ] {+ server_state_from_toml(&configured)?;+ }Ok(())}@@ -1645,6 +1742,24 @@ classifier_magic = trueVALID_CONFIG.replace("base_threshold = 0.5", "base_threshold = 1.5"),"base_threshold must be between 0 and 1",),+ (+ VALID_CONFIG.replace("classifier_target = \"classifier\"\n", ""),+ "route references unknown target",+ ),+ (+ VALID_CONFIG.replace(+ "classifier_target = \"classifier\"",+ "classifier_target = \"\"",+ ),+ "route references unknown target",+ ),+ (+ VALID_CONFIG.replace(+ "classifier_target = \"classifier\"",+ "classifier_target = \" \"",+ ),+ "route references unknown target",+ ),(VALID_CONFIG.replace("base_threshold = 0.5",@@ -1674,9 +1789,18 @@ classifier_magic = true"message_hash_fallback requires classify_trigger = new_session",),(- passthrough_with_subagent_classifier("\nmessage_hash_fallback = true"),+ with_subagent_llm_classifier(+ VALID_CONFIG,+ "passthrough",+ "\nmessage_hash_fallback = true",+ ),"cannot use message_hash_fallback",),+ (+ with_subagent_llm_classifier(VALID_CONFIG, "passthrough", "")+ .replace("mode = \"custom\"", "mode = \"capability\""),+ "mode capability cannot use custom classifier fields",+ ),(VALID_CONFIG.replace("base_threshold = 0.5",diff --git a/docs/reference/toml_schema.md b/docs/reference/toml_schema.mdindex f5945acbd..b607644e9 100644--- a/docs/reference/toml_schema.md+++ b/docs/reference/toml_schema.md@@ -115,13 +115,13 @@ type = "noop"### `passthrough`-Sends every request to one target. It can also classify delegated sub-agent work;+Sends parent requests to one target. It can also route delegated sub-agent work;see [Sub-Agent-Aware Routing](../routing_algorithms/subagent_routing.md).| Key | Required | Meaning ||---|:---:|---|-| `target` | Yes | Target every request is sent to. |-| `subagent_classifier` | No | Custom classifier used only for delegated sub-agent work. |+| `target` | Yes | Target used for parent and harness-maintenance requests. |+| `subagents` | No | Nested `passthrough` or `llm_classifier` policy used only for delegated sub-agent work. Nested classifiers currently support only `mode = "custom"`. |### `random`@@ -209,6 +209,7 @@ optional `handoff_notes` and `classifier` tables and for tuning.| `efficient_system_prompt` | No | unset | System prompt handed to the efficient tier. || `classifier.classify_trigger` | No | `every_request` | When the judge runs. See the `llm_classifier` route. `new_session` has no effect here. || `classifier.response_format_type` | No | `json_schema` | Structured-output mode for the optional classifier judge. Use `json_object` when the classifier provider does not support JSON Schema; Switchyard adds the schema to the prompt and validates the verdict locally. |+| `subagents` | No | unset | Nested `passthrough` or custom `llm_classifier` policy used only for delegated sub-agent work. See [Sub-Agent-Aware Routing](../routing_algorithms/subagent_routing.md). |## Validation Errorsdiff --git a/docs/routing_algorithms/overview.md b/docs/routing_algorithms/overview.mdindex f7b971987..635959a4a 100644--- a/docs/routing_algorithms/overview.md+++ b/docs/routing_algorithms/overview.md@@ -12,7 +12,7 @@ configuration and tuning. For the vocabulary these pages use, see| Strategy | Use it when | Route `type` ||---|---|---|-| [Sub-Agent-Aware Routing](subagent_routing.md) | Parent traffic should use one target while delegated sub-agents are classified across other targets. | `passthrough` with `subagent_classifier` |+| [Sub-Agent-Aware Routing](subagent_routing.md) | Delegated sub-agents should use a separate routing policy from the parent agent. | `passthrough` or `stage_router` with `subagents` || [Random Routing](random_routing.md) | You need a fixed traffic split for A/B tests, baselines, or cost experiments. | `random` || [LLM Classifier Routing](llm_classifier_routing.md) | Request content should decide whether a turn needs the weak or strong tier. | `llm_classifier` || [Stage-Router Routing](stage_router_routing.md) | Tool-result and agent-progress signals should route most turns without an extra classifier call. | `stage_router` |diff --git a/docs/routing_algorithms/subagent_routing.md b/docs/routing_algorithms/subagent_routing.mdindex d4e6add70..2533e80ea 100644--- a/docs/routing_algorithms/subagent_routing.md+++ b/docs/routing_algorithms/subagent_routing.md@@ -1,8 +1,8 @@# Sub-Agent-Aware Routing-Sub-agent-aware routing keeps parent-agent traffic on one target while routing-delegated sub-agent work across separate targets. Current support is available-through the `passthrough` route's optional `subagent_classifier` table.+Sub-agent-aware routing leaves parent-agent traffic with its configured routing+algorithm while routing delegated sub-agent work separately. It is available on+`passthrough` and `stage_router` routes through the optional `subagents` table.```tomlschema_version = 1@@ -36,7 +36,9 @@ context_window = 400000tool_calling = truereasoning = true-[routes.agent.subagent_classifier]+[routes.agent.subagents]+type = "llm_classifier"+mode = "custom"classifier_target = "classifier"targets = ["worker", "reviewer"]default_target = "worker"@@ -77,9 +79,35 @@ the prompt supplied by the parent and selects one configured target. With`classify_trigger = "new_session"`, Switchyard reuses that decision for laterrequests from the same `session + agent` identity. Use `every_request` toclassify each delegated request. `user_turn` is not supported for sub-agent-routing. Harness-maintenance requests continue to the parent target.+routing. Harness-maintenance requests continue through the parent route.++To use Stage Router for parent traffic, replace the `[routes.agent]` table in the+example with the following. The nested `[routes.agent.subagents]` classifier is+unchanged.++```toml+[routes.agent]+id = "agent"+type = "stage_router"+capable_target = "reviewer"+efficient_target = "worker"+picker = "efficient_first"+confidence_threshold = 0.7+context_window = 400000+tool_calling = true+reasoning = true+```Clients must still request the route ID (`agent` above). An explicit model namethat is not registered as a route is rejected before sub-agent classification.`message_hash_fallback` is not supported for sub-agent routing because affinityrequires harness-provided child identity.++To send every delegated sub-agent request to one fixed target without calling a+classifier, replace the `subagents` table above with:++```toml+[routes.agent.subagents]+type = "passthrough"+target = "worker"+```