switchyard_libsy/algorithms/
subagent.rs

1// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
2// SPDX-License-Identifier: Apache-2.0
3
4//! Delegated sub-agent routing around an arbitrary parent algorithm.
5
6use std::sync::Arc;
7
8use switchyard_protocol::{Metadata, ModelId, Request};
9
10use super::fall_through::{DefaultTarget, FallThrough};
11use super::util::affinity::{AffinityRouter, ClassifyTrigger};
12use super::util::subagent::SubagentGate;
13use crate::core::algorithm::{self, Algorithm, Driver};
14use crate::core::classifier::Classifier;
15use crate::core::state::State;
16use crate::{LibsyError, Result, RoutingOutcome};
17
18/// Runtime components for delegated sub-agent routing.
19pub struct SubagentRouterConfig {
20    /// Targets the delegated-work classifier may select.
21    pub targets: Vec<ModelId>,
22    /// Classifier invoked for delegated work according to `classify_trigger`.
23    pub classifier: Arc<dyn Classifier<State>>,
24    /// Child target used when `classifier` abstains.
25    pub default_target: ModelId,
26    /// Controls whether each child is classified once or on every request.
27    pub classify_trigger: ClassifyTrigger,
28    /// Unsupported for child routing because child identity must come from harness metadata.
29    pub message_hash_fallback: bool,
30}
31
32impl SubagentRouterConfig {
33    /// Routes delegated work directly to one fixed target.
34    pub fn fixed_target(target: impl Into<ModelId>) -> Self {
35        let target = target.into();
36        Self {
37            targets: vec![target.clone()],
38            classifier: Arc::new(DefaultTarget::new(target.clone())),
39            default_target: target,
40            classify_trigger: ClassifyTrigger::EveryRequest,
41            message_hash_fallback: false,
42        }
43    }
44}
45
46/// Routes delegated work independently while preserving the parent algorithm for other traffic.
47pub struct SubagentRouter {
48    parent: Arc<dyn Algorithm>,
49    subagent: FallThrough<State>,
50}
51
52impl SubagentRouter {
53    /// Wraps `parent` with the configured delegated-work route.
54    ///
55    /// # Errors
56    ///
57    /// Returns an error when the child default is not a child target or when the affinity
58    /// settings cannot identify delegated children safely.
59    pub fn new(parent: Arc<dyn Algorithm>, config: SubagentRouterConfig) -> Result<Self> {
60        algorithm::ensure_model_is_target(&config.targets, &config.default_target)?;
61        if config.message_hash_fallback {
62            return Err(LibsyError::AlgorithmError {
63                message: "sub-agent routing cannot use message_hash_fallback".to_string(),
64            });
65        }
66
67        let mut subagent = match config.classify_trigger {
68            ClassifyTrigger::EveryRequest => {
69                FallThrough::new_with_state(config.targets).with_name("subagent")
70            }
71            ClassifyTrigger::NewSession => {
72                let affinity = Arc::new(AffinityRouter::for_subagents());
73                FallThrough::new_with_state(config.targets)
74                    .with_name("subagent")
75                    .with_processor(affinity.clone())
76                    .with_classifier(affinity)
77            }
78            ClassifyTrigger::UserTurn => {
79                return Err(LibsyError::AlgorithmError {
80                    message: "sub-agent routing cannot use classify_trigger = user_turn"
81                        .to_string(),
82                });
83            }
84        };
85        subagent = subagent
86            .with_classifier(Arc::new(SubagentGate::new(config.classifier)))
87            .with_classifier(Arc::new(DefaultTarget::new(config.default_target)));
88
89        Ok(Self { parent, subagent })
90    }
91}
92
93#[async_trait::async_trait]
94impl Algorithm for SubagentRouter {
95    fn name(&self) -> &str {
96        self.parent.name()
97    }
98
99    async fn route(self: Arc<Self>, driver: Driver, request: Request) -> Result<RoutingOutcome> {
100        if request
101            .metadata
102            .as_ref()
103            .is_some_and(Metadata::is_subagent_work)
104        {
105            self.subagent.execute(driver, request).await
106        } else {
107            self.parent.clone().route(driver, request).await
108        }
109    }
110}
111
112#[cfg(test)]
113mod tests {
114    use std::sync::Arc;
115    use std::sync::atomic::{AtomicUsize, Ordering};
116
117    use async_trait::async_trait;
118    use parking_lot::Mutex;
119    use serde_json::json;
120    use switchyard_protocol::{
121        ContentBlock, InstructionBlock, Message, Metadata, ModelId, Request, Response, Role,
122        text_request,
123    };
124
125    use super::{SubagentRouter, SubagentRouterConfig};
126    use crate::algorithms::passthrough::Passthrough;
127    use crate::core::algorithm::Algorithm;
128    use crate::core::classifier::{Classification, Classifier, Score};
129    use crate::core::testing::{echo, reply, test_drive};
130    use crate::{
131        ClassifyTrigger, CustomClassifierConfig, CustomClassifierPolicy, Driver,
132        LlmClassifierConfig, LlmTaskClassifier, State,
133    };
134
135    struct ScriptedClassifier {
136        calls: AtomicUsize,
137    }
138
139    #[async_trait]
140    impl Classifier<State> for ScriptedClassifier {
141        async fn score(
142            &self,
143            _state: &mut State,
144            _request: &mut Request,
145            _driver: Option<&Driver>,
146        ) -> crate::Result<(Classification, Option<Response>)> {
147            let scores = match self.calls.fetch_add(1, Ordering::Relaxed) {
148                0 => vec![Score {
149                    confidence: 1.0,
150                    target: ModelId::from("worker"),
151                }],
152                1 => vec![Score {
153                    confidence: 1.0,
154                    target: ModelId::from("reviewer"),
155                }],
156                _ => Vec::new(),
157            };
158            Ok((Classification::Scores(scores), None))
159        }
160    }
161
162    fn request(metadata: Option<Metadata>) -> Request {
163        Request {
164            llm_request: text_request(Some("auto".to_string()), "hi"),
165            raw_request: None,
166            metadata,
167        }
168    }
169
170    fn child(agent_id: &str) -> Request {
171        request(Some(Metadata {
172            session_id: Some("session-1".to_string()),
173            agent_id: Some(agent_id.to_string()),
174            is_subagent: true,
175            is_delegated_work: true,
176            ..Metadata::default()
177        }))
178    }
179
180    fn parent() -> Arc<dyn Algorithm> {
181        Arc::new(Passthrough::new("parent"))
182    }
183
184    fn configured(classifier: Arc<dyn Classifier<State>>) -> crate::Result<Arc<SubagentRouter>> {
185        Ok(Arc::new(SubagentRouter::new(
186            parent(),
187            SubagentRouterConfig {
188                targets: vec![ModelId::from("worker"), ModelId::from("reviewer")],
189                classifier,
190                default_target: ModelId::from("worker"),
191                classify_trigger: ClassifyTrigger::NewSession,
192                message_hash_fallback: false,
193            },
194        )?))
195    }
196
197    #[tokio::test]
198    async fn routes_parent_and_children_with_affinity_and_default() -> crate::Result<()> {
199        let classifier = Arc::new(ScriptedClassifier {
200            calls: AtomicUsize::new(0),
201        });
202        let router = configured(classifier.clone())?;
203
204        let (parent, _) = test_drive(router.clone(), request(None), echo()).await?;
205        let (first, _) = test_drive(router.clone(), child("child-1"), echo()).await?;
206        let (same_child, _) = test_drive(router.clone(), child("child-1"), echo()).await?;
207        let (sibling, _) = test_drive(router.clone(), child("child-2"), echo()).await?;
208        let (defaulted, _) = test_drive(router.clone(), child("child-3"), echo()).await?;
209        let maintenance = request(Some(Metadata {
210            session_id: Some("session-1".to_string()),
211            agent_id: Some("child-1".to_string()),
212            is_subagent: true,
213            is_delegated_work: false,
214            ..Metadata::default()
215        }));
216        let (maintenance, _) = test_drive(router, maintenance, echo()).await?;
217
218        assert_eq!(parent, "parent");
219        assert_eq!(first, "worker");
220        assert_eq!(same_child, "worker");
221        assert_eq!(sibling, "reviewer");
222        assert_eq!(defaulted, "worker");
223        assert_eq!(maintenance, "parent");
224        assert_eq!(classifier.calls.load(Ordering::Relaxed), 3);
225        Ok(())
226    }
227
228    #[tokio::test]
229    async fn custom_classifier_receives_only_the_delegated_prompt() -> crate::Result<()> {
230        let classifier = LlmTaskClassifier::new(LlmClassifierConfig::Custom {
231            judge_target: ModelId::from("judge"),
232            targets: vec![
233                ("worker".to_string(), ModelId::from("worker")),
234                ("reviewer".to_string(), ModelId::from("reviewer")),
235            ],
236            default_target: "worker".to_string(),
237            config: CustomClassifierConfig::new(
238                "classify the delegated task",
239                json!({
240                    "type": "object",
241                    "properties": {
242                        "target": {"type": "string", "enum": ["worker", "reviewer"]}
243                    },
244                    "required": ["target"],
245                    "additionalProperties": false
246                }),
247                CustomClassifierPolicy::target_selector("/target"),
248            ),
249        })?;
250        let router = configured(Arc::new(classifier))?;
251        let mut request = child("child-1");
252        request.llm_request.instructions = vec![InstructionBlock {
253            role: Role::System,
254            content: Message::text(Role::System, "child system instructions").content,
255        }];
256        request.llm_request.messages = vec![
257            Message::text(Role::User, "harness context"),
258            Message {
259                role: Role::User,
260                content: vec![
261                    ContentBlock::Text {
262                        text: "<system-reminder>tool context</system-reminder>".to_string(),
263                    },
264                    ContentBlock::Text {
265                        text: "review this parser".to_string(),
266                    },
267                ],
268            },
269        ];
270        let calls = Arc::new(Mutex::new(Vec::new()));
271        let served_calls = calls.clone();
272
273        let (selected, _) = test_drive(router, request, move |target, request| {
274            let calls = served_calls.clone();
275            async move {
276                let completion = if target == "judge" {
277                    r#"{"target":"reviewer"}"#
278                } else {
279                    "child answer"
280                };
281                calls.lock().push((target, request));
282                Ok(reply(completion))
283            }
284        })
285        .await?;
286
287        assert_eq!(selected, "reviewer");
288        let calls = calls.lock();
289        assert_eq!(calls.len(), 2);
290        assert_eq!(calls[0].0, "judge");
291        assert_eq!(
292            calls[0].1.llm_request.instructions[0].content,
293            Message::text(Role::System, "classify the delegated task").content
294        );
295        assert_eq!(
296            calls[0].1.llm_request.messages,
297            vec![Message::text(Role::User, "review this parser")]
298        );
299        assert_eq!(calls[1].0, "reviewer");
300        assert_eq!(calls[1].1.llm_request.instructions.len(), 1);
301        assert_eq!(calls[1].1.llm_request.messages.len(), 2);
302        Ok(())
303    }
304}
switchyard_libsy/algorithms/subagent.rs

switchyard_libsy/algorithms/
subagent.rs
