subagent: Limit concurrent subagents with GOOSE_MAX_CONCURRENT_SUBAGENTS (#12946)

This commit is contained in:
Lifei Zhou
2026-10-18 23:31:23 +00:00
committed by GitHub
parent 4ea7c2c6dc
commit 62d3501134
5 changed files with 59 additions and 12 deletions
+12
View File
@@ -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<S> {
runner: Arc<dyn SubagentRunner<S>>,
running: Mutex<Running>,
max_concurrency: NonZeroUsize,
}
impl<S> SubagentOperation<S> {
@@ -172,9 +174,16 @@ impl<S> SubagentOperation<S> {
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<E: From<Message>>(
&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;
}
+36 -11
View File
@@ -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"]);
}
@@ -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::<NonZeroUsize>("GOOSE_MAX_CONCURRENT_SUBAGENTS")
.unwrap_or(NonZeroUsize::new(5).unwrap()),
),
),
Arc::new(SteerOperation::new(steer_queue, hook_manager.clone())),
Arc::new(BangShellOperation::new()),
];
@@ -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 |
@@ -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 |