diff --git a/.changeset/configurable-parallel-subagents.md b/.changeset/configurable-parallel-subagents.md new file mode 100644 index 000000000..f47c03930 --- /dev/null +++ b/.changeset/configurable-parallel-subagents.md @@ -0,0 +1,6 @@ +--- +'@truefoundry/trueforge-core': patch +'@truefoundry/trueforge': patch +--- + +Make the per-turn sub-agent concurrency limit configurable with `MAX_PARALLEL_SUB_AGENTS`, defaulting to 10. diff --git a/packages/trueforge-core/src/agent-session/ITurnResourceResolver.ts b/packages/trueforge-core/src/agent-session/ITurnResourceResolver.ts index fd633908a..63d5d56c2 100644 --- a/packages/trueforge-core/src/agent-session/ITurnResourceResolver.ts +++ b/packages/trueforge-core/src/agent-session/ITurnResourceResolver.ts @@ -19,6 +19,8 @@ export interface ResolvedAgentDefinition { * per-request state (secrets, providers, caches) freely. */ export interface ITurnResourceResolver> { + /** Maximum sub-agent threads executed in parallel per turn. Defaults to 10. */ + readonly maxParallelSubAgents?: number; /** * Host web-search backend. When set and `config.web_search.enabled`, builtins * register search/fetch system tools. Omit when the host has no provider configured. diff --git a/packages/trueforge-core/src/agent-session/SessionHandle.ts b/packages/trueforge-core/src/agent-session/SessionHandle.ts index b872b40d2..e709a5846 100644 --- a/packages/trueforge-core/src/agent-session/SessionHandle.ts +++ b/packages/trueforge-core/src/agent-session/SessionHandle.ts @@ -479,8 +479,10 @@ export class SessionHandle< }); const previousMcpServers = input.previous?.snapshot.mcp_servers; + const maxParallelSubAgents = input.resolver.maxParallelSubAgents; const orchestrator = new AgentThreadOrchestrator({ agentThreads, + ...(maxParallelSubAgents !== undefined ? { maxParallelSubAgents } : {}), createDynamicSubAgentThread, tracing, logger: input.resolver.logger, diff --git a/packages/trueforge-core/src/agent-session/TurnResourceResolver.ts b/packages/trueforge-core/src/agent-session/TurnResourceResolver.ts index 13d12e322..363c21b2a 100644 --- a/packages/trueforge-core/src/agent-session/TurnResourceResolver.ts +++ b/packages/trueforge-core/src/agent-session/TurnResourceResolver.ts @@ -83,6 +83,7 @@ export class TurnResourceResolver< readonly #sources = new Map>(); readonly #models = new Map>(); #sandbox?: HarnessSandbox | undefined; + readonly maxParallelSubAgents?: number; constructor( protected readonly deps: { @@ -97,6 +98,7 @@ export class TurnResourceResolver< mcpRequestTimeoutMs: number; mcpConnectTimeoutMs: number; mcpMaxResponseBytes?: number | undefined; + maxParallelSubAgents?: number; /** One sandbox type per runtime. Omit = no sandbox support. */ sandboxProvider?: TurnSandboxFactory | undefined; /** @@ -115,7 +117,11 @@ export class TurnResourceResolver< /** Forwarded to RemoteMCP / AgentThread (required by their constructors). */ logger: Logger; }, - ) {} + ) { + if (deps.maxParallelSubAgents !== undefined) { + this.maxParallelSubAgents = deps.maxParallelSubAgents; + } + } get webSearchProvider(): IWebSearchProvider | undefined { return this.deps.webSearchProvider; diff --git a/packages/trueforge-core/src/core/index.ts b/packages/trueforge-core/src/core/index.ts index e5601afdf..e26365612 100644 --- a/packages/trueforge-core/src/core/index.ts +++ b/packages/trueforge-core/src/core/index.ts @@ -19,7 +19,7 @@ export type { AgentThreadExecutionResult, SubAgentCompletion, } from './runtime/AgentThread.types'; -export { AgentThreadOrchestrator } from './runtime/AgentThreadOrchestrator'; +export { AgentThreadOrchestrator, DEFAULT_MAX_PARALLEL_SUB_AGENTS } from './runtime/AgentThreadOrchestrator'; export type { CreateDynamicSubAgentThread } from './runtime/CreateDynamicSubAgentThread'; export { isAgentUserMessage, isEmptyMessageContent, isFileContentPart } from './runtime/UserInputMessage'; export type { UserMessage } from './runtime/UserInputMessage'; diff --git a/packages/trueforge-core/src/core/runtime/AgentThreadOrchestrator.ts b/packages/trueforge-core/src/core/runtime/AgentThreadOrchestrator.ts index f71b2469b..af34001d2 100644 --- a/packages/trueforge-core/src/core/runtime/AgentThreadOrchestrator.ts +++ b/packages/trueforge-core/src/core/runtime/AgentThreadOrchestrator.ts @@ -41,7 +41,7 @@ import { import type { CreateDynamicSubAgentThread } from './CreateDynamicSubAgentThread'; import { addAgentThreadMetrics, createEmptyAgentThreadMetrics, type AgentThreadMetrics } from './metrics'; -const MAX_PARALLEL_SUB_AGENTS = 5; +export const DEFAULT_MAX_PARALLEL_SUB_AGENTS = 10; const CANCELED_BECAUSE_USER_SENT_NEW_MESSAGE = 'Canceled because user sent a new message.'; function getActiveAgentThreads(agentThreads: Map): AgentThread[] { @@ -193,6 +193,7 @@ export async function* wrapWithSubAgentSpan( export interface AgentThreadOrchestratorInput { agentThreads: Map; + maxParallelSubAgents?: number; createDynamicSubAgentThread: CreateDynamicSubAgentThread; tracing: AgentTracing; logger: Logger; @@ -207,6 +208,7 @@ export interface AgentThreadOrchestratorInput { export class AgentThreadOrchestrator { private readonly agentThreads: Map; + private readonly maxParallelSubAgents: number; private readonly createDynamicSubAgentThread: CreateDynamicSubAgentThread; private readonly tracing: AgentTracing; private readonly logger: Logger; @@ -218,6 +220,7 @@ export class AgentThreadOrchestrator { private readonly mcpServerInitInfoById = new Map(); constructor(params: AgentThreadOrchestratorInput) { + this.maxParallelSubAgents = params.maxParallelSubAgents ?? DEFAULT_MAX_PARALLEL_SUB_AGENTS; this.agentThreads = params.agentThreads; this.createDynamicSubAgentThread = params.createDynamicSubAgentThread; this.tracing = params.tracing; @@ -694,8 +697,8 @@ export class AgentThreadOrchestrator { turnPaused = false; } - for (let i = 0; i < runnable.length; i += MAX_PARALLEL_SUB_AGENTS) { - const batch = runnable.slice(i, i + MAX_PARALLEL_SUB_AGENTS); + for (let i = 0; i < runnable.length; i += this.maxParallelSubAgents) { + const batch = runnable.slice(i, i + this.maxParallelSubAgents); const generators = batch.map(thread => thread.parent ? wrapWithSubAgentSpan(rootSpan.trace, thread, signal) diff --git a/packages/trueforge/.env.example b/packages/trueforge/.env.example index 6ab5c3f28..87731cfdf 100644 --- a/packages/trueforge/.env.example +++ b/packages/trueforge/.env.example @@ -108,6 +108,8 @@ REDIS_URL=redis://localhost:6379 # REDIS_REQUEST_REPLY_POLL_INTERVAL_MS=500 ## Turn execution and resumable stream settings. All optional. +## Max sub-agents running in parallel per turn. Must be a positive integer. Default 10. +# MAX_PARALLEL_SUB_AGENTS=10 ## Max seconds a single turn may run before cancellation. Default 600 (10 minutes). # SERVER_EXECUTION_TIMEOUT_SECONDS=600 ## Max seconds to wait for turn cancellation + connection drain on SIGTERM/SIGINT. Default 30. diff --git a/packages/trueforge/src/apis/turns.ts b/packages/trueforge/src/apis/turns.ts index 528bb8010..38bb9e83b 100644 --- a/packages/trueforge/src/apis/turns.ts +++ b/packages/trueforge/src/apis/turns.ts @@ -444,6 +444,7 @@ function createTurnResolver(deps: { mcpRequestTimeoutMs: configuration.MCP_REQUEST_TIMEOUT_MS, mcpConnectTimeoutMs: configuration.MCP_CONNECT_TIMEOUT_MS, mcpMaxResponseBytes: configuration.MCP_TOOL_CALL_MAX_RESPONSE_BYTES, + maxParallelSubAgents: configuration.MAX_PARALLEL_SUB_AGENTS, sandboxProvider: async ({ spec, existingSandboxId, tracing }) => { const provider = await resolveSandboxProvider({ tenant_id, diff --git a/packages/trueforge/src/config.ts b/packages/trueforge/src/config.ts index c87283e6f..18d893a6b 100644 --- a/packages/trueforge/src/config.ts +++ b/packages/trueforge/src/config.ts @@ -16,6 +16,7 @@ import os from 'node:os'; import path from 'node:path'; import { fileURLToPath } from 'node:url'; +import { DEFAULT_MAX_PARALLEL_SUB_AGENTS } from '@truefoundry/trueforge-core/core'; import envPaths from 'env-paths'; import { z } from 'zod'; @@ -788,6 +789,8 @@ export interface SharedServerConfiguration { * Default 3600 (60 minutes). */ SERVER_EXECUTION_TIMEOUT_SECONDS: number; + /** Max parallel sub-agents per turn. Env: `MAX_PARALLEL_SUB_AGENTS`. Default 10. */ + MAX_PARALLEL_SUB_AGENTS: number; /** * TTL for a running turn's resumable event stream. * Env: `TURN_STREAM_TTL_SECONDS`. Default execution timeout + 300. @@ -1227,6 +1230,11 @@ const shared: SharedServerConfiguration = { defaultValue: 30, }), SERVER_EXECUTION_TIMEOUT_SECONDS: serverExecutionTimeoutSeconds, + MAX_PARALLEL_SUB_AGENTS: parsePositiveInt({ + envKey: 'MAX_PARALLEL_SUB_AGENTS', + raw: getEnv('MAX_PARALLEL_SUB_AGENTS'), + defaultValue: DEFAULT_MAX_PARALLEL_SUB_AGENTS, + }), TURN_STREAM_TTL_SECONDS: parsePositiveInt({ envKey: 'TURN_STREAM_TTL_SECONDS', raw: getEnv('TURN_STREAM_TTL_SECONDS'),