From 62d35011344abe39997cd493613d147bb84a29c7 Mon Sep 17 00:00:00 2001 From: Lifei Zhou Date: Sun, 18 Oct 2026 23:31:23 +0000 Subject: [PATCH] subagent: Limit concurrent subagents with GOOSE_MAX_CONCURRENT_SUBAGENTS (#12946) --- crates/goose-agent/src/subagent.rs | 12 +++++ crates/goose-agent/tests/subagent.rs | 47 ++++++++++++++----- .../goose/src/agents/state_machine_builder.rs | 10 +++- .../guides/context-engineering/subagents.mdx | 1 + .../docs/guides/environment-variables.md | 1 + 5 files changed, 59 insertions(+), 12 deletions(-) diff --git a/crates/goose-agent/src/subagent.rs b/crates/goose-agent/src/subagent.rs index 6365617f2..a5b5d125d 100644 --- a/crates/goose-agent/src/subagent.rs +++ b/crates/goose-agent/src/subagent.rs @@ -1,4 +1,5 @@ use std::collections::HashSet; +use std::num::NonZeroUsize; use std::sync::Arc; use anyhow::Result; @@ -165,6 +166,7 @@ struct Running { pub struct SubagentOperation { runner: Arc>, running: Mutex, + max_concurrency: NonZeroUsize, } impl SubagentOperation { @@ -172,9 +174,16 @@ impl SubagentOperation { Self { runner, running: Mutex::default(), + max_concurrency: NonZeroUsize::MAX, } } + /// Limits how many subagents run at once; additional subagents remain pending. + pub fn with_max_concurrency(mut self, max_concurrency: NonZeroUsize) -> Self { + self.max_concurrency = max_concurrency; + self + } + fn deliver>( &self, subagent_session_id: &str, @@ -257,6 +266,9 @@ where let mut running = self.running.lock().await; for subagent_session_id in &pending { + if running.subagent_session_ids.len() >= self.max_concurrency.get() { + break; + } if running.subagent_session_ids.contains(subagent_session_id) { continue; } diff --git a/crates/goose-agent/tests/subagent.rs b/crates/goose-agent/tests/subagent.rs index c717cf6cc..c1c73734f 100644 --- a/crates/goose-agent/tests/subagent.rs +++ b/crates/goose-agent/tests/subagent.rs @@ -1,4 +1,5 @@ use std::collections::HashMap; +use std::num::NonZeroUsize; use std::sync::{Arc, Mutex}; use async_trait::async_trait; @@ -314,19 +315,21 @@ async fn a_subagent_cancelled_elsewhere_is_reported_and_not_restarted() { } #[tokio::test] -async fn stop_delivers_finished_subagents_and_cancels_the_rest() { +async fn stop_delivers_finished_subagents_and_cancels_running_and_queued_children() { let runner = Arc::new(fake(&["a", "b", "c"])); let a = runner.running("a"); let b = runner.running("b"); - let c = runner.running("c"); - let operation = operation(&runner); + runner.finished("c", SubagentOutcome::Completed("c done".into())); + let operation = operation(&runner).with_max_concurrency(NonZeroUsize::new(2).unwrap()); let mut messages = vec![kickoff()]; interrupt(&operation, &messages); + assert_eq!(runner.started(), ["a", "b"]); a.finish(SubagentOutcome::Completed("a done".into())); b.finish(SubagentOutcome::Cancelled); let saved = stop(&operation, &messages).await; + assert!(b.is_closed()); assert_eq!( texts(&saved), [ @@ -335,20 +338,14 @@ async fn stop_delivers_finished_subagents_and_cancels_the_rest() { Subagent c was cancelled before it finished and will not run again.", ] ); - assert!(c.is_closed()); assert_eq!( runner.events(), - [ - "started a", - "started b", - "started c", - "finished a, 2 remaining" - ] + ["started a", "started b", "finished a, 2 remaining"] ); messages.extend(saved); assert!(run_once(&operation, &messages).await.is_empty()); - assert_eq!(runner.started(), ["a", "b", "c"]); + assert_eq!(runner.started(), ["a", "b"]); assert!(stop(&operation, &messages).await.is_empty()); } @@ -448,3 +445,31 @@ async fn stop_skips_messages_queued_ahead_of_a_finished_result() { assert_eq!(texts(&saved), ["Subagent a completed: done"]); assert!(shown(&mut rx).is_empty()); } + +#[tokio::test] +async fn concurrency_limit_queues_subagents_until_a_slot_is_available() { + let runner = Arc::new(fake(&["a", "b", "c"])); + let a = runner.running("a"); + let b = runner.running("b"); + let c = runner.running("c"); + let operation = operation(&runner).with_max_concurrency(NonZeroUsize::new(2).unwrap()); + let mut messages = vec![kickoff()]; + + interrupt(&operation, &messages); + assert_eq!(runner.started(), ["a", "b"]); + + b.finish(SubagentOutcome::Failed("boom".into())); + messages.extend(run_once(&operation, &messages).await); + assert_eq!(runner.started(), ["a", "b"]); + + interrupt(&operation, &messages); + assert_eq!(runner.started(), ["a", "b", "c"]); + + c.finish(SubagentOutcome::Completed("c done".into())); + messages.extend(run_once(&operation, &messages).await); + a.finish(SubagentOutcome::Completed("a done".into())); + messages.extend(run_once(&operation, &messages).await); + + assert!(run_once(&operation, &messages).await.is_empty()); + assert_eq!(runner.started(), ["a", "b", "c"]); +} diff --git a/crates/goose/src/agents/state_machine_builder.rs b/crates/goose/src/agents/state_machine_builder.rs index 036c3e6c7..27cb5f30c 100644 --- a/crates/goose/src/agents/state_machine_builder.rs +++ b/crates/goose/src/agents/state_machine_builder.rs @@ -1,3 +1,4 @@ +use std::num::NonZeroUsize; use std::sync::{Arc, Mutex as StdMutex}; use std::time::Duration; @@ -14,6 +15,7 @@ use crate::agents::state_machine::{ SubagentOperation, ToolApprovalOperation, ToolExecutionOperation, ToolPairCompactionOperation, }; use crate::agents::subagent_handler::ForegroundSubagentRunner; +use crate::config::Config; use crate::hooks::HookManager; use crate::providers::base::Provider; use crate::session::{Session, SessionManager}; @@ -82,7 +84,13 @@ pub(crate) fn build_state_machine( Arc::clone(&extension_lease), )), Arc::new(RemainingToolCallsOperation::new(hook_manager.clone())), - Arc::new(SubagentOperation::new(Arc::new(subagent_runner))), + Arc::new( + SubagentOperation::new(Arc::new(subagent_runner)).with_max_concurrency( + Config::global() + .get_param::("GOOSE_MAX_CONCURRENT_SUBAGENTS") + .unwrap_or(NonZeroUsize::new(5).unwrap()), + ), + ), Arc::new(SteerOperation::new(steer_queue, hook_manager.clone())), Arc::new(BangShellOperation::new()), ]; diff --git a/documentation/docs/guides/context-engineering/subagents.mdx b/documentation/docs/guides/context-engineering/subagents.mdx index a43ccd527..d3775753a 100644 --- a/documentation/docs/guides/context-engineering/subagents.mdx +++ b/documentation/docs/guides/context-engineering/subagents.mdx @@ -271,6 +271,7 @@ Subagents use the following pre-configured settings, but you can override any de ### Default Settings | Parameter | Default | How to Customize | |-----------|---------|------------------| +| **Maximum Concurrent Subagents** | 5 | Set `GOOSE_MAX_CONCURRENT_SUBAGENTS` to a positive integer. Additional tasks wait until a running subagent finishes. The limit applies per parent session. | | **Max Turns** | 25 | Use natural language, set `GOOSE_SUBAGENT_MAX_TURNS`, or configure `settings.max_turns` in [recipes](/docs/guides/recipes/recipe-reference#settings) or subagent tool calls | | **Timeout** | 5 minutes | Request longer timeout in your prompt | | **Extensions** | Inherited from parent | Specify which extensions to use in your prompt | diff --git a/documentation/docs/guides/environment-variables.md b/documentation/docs/guides/environment-variables.md index b3aa66f0f..b0b6eb0cc 100644 --- a/documentation/docs/guides/environment-variables.md +++ b/documentation/docs/guides/environment-variables.md @@ -136,6 +136,7 @@ These variables control how goose manages conversation sessions and context. |----------|---------|---------|---------| | `GOOSE_MAX_TURNS` | [Maximum number of turns](/docs/guides/sessions/smart-context-management#maximum-turns) allowed without user input | Integer (e.g., 10, 50, 100) | 1000 | | `GOOSE_GATEWAY_MAX_TURNS` | Maximum number of turns for gateway sessions (e.g., Telegram). Overrides `GOOSE_MAX_TURNS` for gateway traffic only, so chat platforms can keep a stricter cap than CLI/desktop sessions. | Integer (e.g., 5, 10, 25) | Falls back to `GOOSE_MAX_TURNS`, then 5 | +| `GOOSE_MAX_CONCURRENT_SUBAGENTS` | Maximum number of subagents running at once per parent session. Additional tasks wait for a slot. Unset or invalid values use the default. | Positive integer (e.g., 2, 5, 10) | 5 | | `GOOSE_SUBAGENT_MAX_TURNS` | Sets the maximum turns allowed for a [subagent](/docs/guides/context-engineering/subagents) to complete before timeout. Can be overridden by [`settings.max_turns`](/docs/guides/recipes/recipe-reference#settings) in recipes or subagent tool calls. | Integer (e.g., 25) | 25 | | `CONTEXT_FILE_NAMES` | Specifies custom filenames for [hint/context files](/docs/guides/context-engineering/using-goosehints#custom-context-files) | JSON array of strings (e.g., `["CLAUDE.md", ".goosehints"]`) | `[".goosehints", "AGENTS.md"]` | | `GOOSE_DISABLE_SESSION_NAMING` | Disables automatic AI-generated session naming; avoids the background model call and keeps the default "CLI Session" (goose CLI) or "New Chat" (goose Desktop) | "1", "true" (case-insensitive) to enable | false |