Subagents

When a task involves gathering or processing information from multiple sources, a single agent can quickly fill its context window with intermediate tool calls and results. TrueForge solves this with subagents — lightweight, isolated agent runs that handle focused subtasks in parallel and return only their final results to the root agent. Dynamic subagents are enabled by default. The root agent stays focused on high-level coordination. Subagents do the heavy lifting.

Why subagents?

Subagents solve the context bloat problem. When an agent uses tools with large outputs — API responses, search results, file contents — the context window fills up with intermediate data that is only needed temporarily. As the context grows, the agent becomes slower, more expensive, and more prone to errors. Consider a task: “Summarize the recent pull requests for every member of my team.”

Without subagents
With subagents

The agent looks up members of the team.
It works on each member one by one, fetching pull requests and summarizing each.
All intermediate tool calls and results stay in the context window.
The agent has to reason over a large, cluttered context to produce the final answer.
The bloat carries over to future turns in the session.

When subagents help most:

Multi-step research across several entities (users, repos, services) that can run in parallel
Tasks where intermediate tool output is large but the final answer is a summary
Work that benefits from isolation — each subtask gets a clean context to reason in

How it works

The root agent decides at runtime whether to delegate. When it does, it calls the built-in create_sub_agent tool with focused, generated instructions for each subtask, spawns the subagents, and waits for their results.

Shared tools and sandbox — subagents have access to the same MCP tools and sandbox environment as the root agent.
No user interaction — subagents cannot ask the user questions. Only the root agent talks to the user. Subagent tool calls that require approval still pause for the user, though.
No nesting — subagents cannot create other subagents. Delegation is one level deep.
Parallel execution — multiple subagents run concurrently. The root agent waits for all of them before continuing.

Example

In this example, the user asks for a summary of work merged by a team. The root agent looks up team members, then delegates PR research for each member to parallel subagents.

User

Can you please give me a summary of work merged by “agent” team in agent-runtime in last 7 days?

Assistant

get_team_members

Tool Call

{
  "org": "truefoundry",
  "team_slug": "agent"
}

Tool Response

[
  "alice",
  "bob"
]

Assistant

These subagents run in parallel and return their final assistant messages to the main agent. The main agent waits for all the subagents to finish and then combines the results to produce the final answer.

The agent team has 2 members. The date is 2026-05-22, so I need PRs merged in the last 7 days (since 2026-05-15). Let me now fetch merged PRs for each team member in parallel using sub-agents!

Subagent: bob-prs

System

These instructions are generated by the main agent for the subagent to execute.

Search for pull requests merged by GitHub user “bob” in the repository “agent-runtime” owned by “truefoundry” since 2026-05-15 (last 7 days, today is 2026-05-22). Use the search_pull_requests tool with:

query: “repo:truefoundry/agent-runtime author:bob is:merged merged:>=2026-05-15”

For each PR found, provide:

PR number and title
Merged date
A brief 1-2 sentence description of what the PR does (infer from the title or any available description)

Return a concise structured summary of all PRs found. If none found, say “No PRs merged in the last 7 days.”

Assistant

search_pull_requests

Tool Call

{
  "query": "repo:truefoundry/agent-runtime author:bob is:merged merged:>=2026-05-15"
}

Tool Response

{
  "total_count": 2,
  "incomplete_results": false,
  "items": [
    {
      "id": 4475054266,
      "title": "misc: add responseUpdatedAt to agent response store"
    },
    {
      "id": 4454608143,
      "title": "fix: Sandbox: update instruction on agent to invoke mcp_client.py script directly, not via python"
    }
  ]
}

Assistant

Merged: 2026-05-20 Description: Adds a new responseUpdatedAt timestamp field to ResponseInStore …
Merged: 2026-05-19 Description: Fixes sandbox initialization by symlinking the uploaded mcp_client.py as mcp-client

Subagent: alice-prs

System

These instructions are generated by the main agent for the subagent to execute.

Search for pull requests merged by GitHub user “alice” in the repository “agent-runtime” owned by “truefoundry” since 2026-05-15 (last 7 days, today is 2026-05-22). Use the search_pull_requests tool with:

query: “repo:truefoundry/agent-runtime author:alice is:merged merged:>=2026-05-15”

For each PR found, provide:

PR number and title
Merged date
A brief 1-2 sentence description of what the PR does (infer from the title or any available description)

Return a concise structured summary of all PRs found. If none found, say “No PRs merged in the last 7 days.”

Assistant

search_pull_requests

Tool Call

{
  "query": "repo:truefoundry/agent-runtime author:alice is:merged merged:>=2026-05-15"
}

Tool Response

{
  "total_count": 0,
  "incomplete_results": false,
  "items": []
}

Assistant

No PRs merged by alice in the last 7 days.

Assistant

Here is a summary of work merged by the agent team in the last 7 days:

Alice: No PRs merged in the last 7 days.
Bob: 2 PRs merged in the last 7 days. The theme of work is around sandbox initialization and responseUpdatedAt … …

Disabling

Set config.dynamic_sub_agents.enabled: false on the agent. See config.dynamic_sub_agents in the agent spec reference.

Getting Started

TrueForge Harness

SDK

UI Chat

Project

Why subagents?

How it works

Example

Disabling

​Why subagents?

​How it works

​Example

​Disabling

Why subagents?

How it works

Example

Disabling