Skip to main content

Documentation Index

Fetch the complete documentation index at: https://www.truefoundry.com/llms.txt

Use this file to discover all available pages before exploring further.

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. TrueFoundry Agent Harness solves this by automatically spinning up subagents — lightweight, isolated agent runs that handle focused subtasks in parallel and return only their final results to the root agent. 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. Subagents isolate this work. Each subagent runs with its own context, makes its own tool calls, and returns only a concise result. The root agent never sees the dozens of intermediate steps that produced it.
The agent processes everything sequentially in a single context:
  1. Agent looks up members of the team
  2. Agent works on each team member one by one, looks up pull requests and creates a summary for each
  3. All intermediate tool calls and their results stay in the context window
  4. Agent needs to look back through a large, cluttered context to produce the final answer
  5. Context bloat carries over to future turns
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 generates focused instructions for each subagent, spawns them, and waits for 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 or send messages directly. Only the root agent communicates with the user.
  • 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

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!

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 “org” 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:
  1. PR number and title
  2. Merged date
  3. 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**
```json lines
{
  "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

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 “org” 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:
  1. PR number and title
  2. Merged date
  3. 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**
```json lines
{
  "pull_requests": [
    {
      "total_count": 0,
      "incomplete_results": false
    }
  ]
}

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 … …

​
Tracing subagent execution

Every subagent run is traced end-to-end alongside the root agent. In the Request Traces view, you can see the root agent span, each subagent span (with its name, duration, and step count), and the individual tool calls within each subagent.
Request Traces view showing the root agent execution with multiple parallel subagent spans, each labeled with its name and duration
Clicking into a subagent span reveals the full detail: the generated instructions it received, the tools it called, and the final output it returned to the root agent.
Subagent trace detail panel showing the input instructions and output result for a pr-summary subagent

​
Streaming events

Each agent execution — root and subagent — is identified by a unique execution_id in the stream. Subagent lifecycle is marked by agent.created and agent.done events. For the full event reference and a working client example, see Using API — Subagents.

​
Roadmap: user-defined subagents

Today, the harness decides when and how to create subagents automatically. You cannot define your own specialized subagents with custom instructions, tools, or models. This is on the roadmap. In a future release, the Agent Harness will support user-defined subagents — letting you configure named subagents with specific system prompts, tool sets, and model overrides that the root agent can delegate to. This will enable patterns like dedicated research agents, code reviewers, or data analysts that the root agent can invoke by name.