Subagents

Purpose and Scope

Subagents are for agent systems that need delegation without letting the main agent carry every token, tool result, and intermediate decision in its own context window. In the AI SDK agent model, a subagent is an agent invoked by a parent agent through a tool. The parent decides when to delegate, the tool calls the subagent, and the subagent runs autonomously with its own model, instructions, tools, and context before returning a result. This pattern keeps the main agent focused on orchestration instead of long-running investigation or specialized execution.

Sources: content/docs/03-agents/06-subagents.mdx

Use subagents when the delegated task is large enough to justify the extra latency and complexity. The documentation frames the strongest cases as context-heavy research, independent work that can be parallelized, and capability isolation. For example, a parent agent can ask separate subagents to inspect different areas of a codebase, then synthesize their compact summaries. That is different from simply adding more tools to the parent: the subagent absorbs the detailed exploration and returns only what the parent needs to continue coherently.

Sources: content/docs/03-agents/06-subagents.mdx

Relevant Source Files

• content/docs/03-agents/06-subagents.mdx - First-party documentation page defining subagents, their workflow, when to use them, why they help with context offloading and parallelism, and the basic ToolLoopAgent plus tool delegation pattern.

Core Primitives

A subagent system has three important parts. The first is the specialized agent itself, usually a ToolLoopAgent with its own model, instructions, and tool set. The second is the parent-facing tool, created with tool, whose execute function invokes the subagent. The third is the returned model-facing output, which should normally be a focused summary rather than a transcript of everything the subagent did. The source documentation explicitly calls out toModelOutput as the control point for deciding what the parent model sees.

Sources: content/docs/03-agents/06-subagents.mdx

The distinction between tool output and model output matters because subagents are most valuable when they reduce context pressure. A subagent may read many files, search many documents, or perform a multi-step investigation, but the parent agent should not automatically receive the full working history. In practice, the parent usually needs a final answer, a set of findings, or a small structured result. Treat the subagent as a bounded worker with a contract: it receives a task, performs autonomous work, and returns the smallest useful result for the parent’s next decision.

Sources: content/docs/03-agents/06-subagents.mdx

Basic Delegation Flow

The simplest implementation is a blocking delegation tool. Define a research subagent, expose a research tool to the main agent, and call researchSubagent.generate inside the tool’s execute function. The supplied example passes the user’s task as the subagent prompt and forwards the abortSignal from the tool execution context. That forwarding is important: cancellation should propagate from the parent request into the delegated run instead of leaving the subagent working after the user or server has abandoned the original operation.

Sources: content/docs/03-agents/06-subagents.mdx

import { ToolLoopAgent, tool } from 'ai';
import { z } from 'zod';
 
const researchSubagent = new ToolLoopAgent({
  model,
  instructions: `You are a research agent.
Summarize your findings in your final response.`,
  tools: {
    read: readFileTool,
    search: searchTool,
  },
});
 
const researchTool = tool({
  description: 'Research a topic or question in depth.',
  inputSchema: z.object({
    task: z.string().describe('The research task to complete'),
  }),
  execute: async ({ task }, { abortSignal }) => {
    const result = await researchSubagent.generate({
      prompt: task,
      abortSignal,
    });
    return result.text;
  },
});
 
const mainAgent = new ToolLoopAgent({
  model,
  instructions: 'You are a helpful assistant that can delegate research tasks.',
  tools: {
    research: researchTool,
  },
});

This pattern is appropriate when the UI does not need intermediate progress. The parent model sees a normal tool result after the subagent completes, and the application can keep its interface simple. The tradeoff is that the user may experience the delegated work as one long pause. If the subagent does expensive exploration, consider adding status updates rather than forcing the parent request to appear idle. The official tools documentation describes preliminary tool results with async iterables, where the last yielded value becomes the final result; that pattern is useful for showing subagent progress while preserving one final tool outcome.

Streaming Progress and UI Behavior

Streaming subagent progress is not the same as exposing the subagent’s private reasoning or full context. A good progress stream reports durable, user-safe milestones: starting a search, reading a file group, completing analysis, or returning a final summary. When a tool returns multiple preliminary results from an async generator, the UI can render those updates while the parent agent waits for the final value. This fits the AI SDK stream model, where applications can send structured data parts to the frontend and keep a long-running interaction responsive.

Sources: content/docs/03-agents/06-subagents.mdx

For chat applications, progress should be designed as an interface contract. The parent-facing tool result can include fields such as status, text, and a final summary, while the model-facing output can remain compact. If you are using UI message streams, remember that the AI SDK data stream protocol is based on Server-Sent Events and supports structured parts for message starts, text deltas, reasoning deltas, and custom data. Use those stream capabilities to communicate subagent state to users without dumping every intermediate tool call into the parent model context.

Approval and Safety Constraints

Do not assume that a subagent can pause for human approval in the same way a top-level tool might. The official subagent guidance states that subagent tools cannot use approval flows such as toolApproval or the deprecated needsApproval; tools inside the subagent must execute automatically. This is an important safety boundary. If an operation requires human confirmation, put that approval step in the parent flow or in application code before invoking the subagent, rather than hiding it inside a delegated autonomous loop.

Sources: content/docs/03-agents/06-subagents.mdx

Capability isolation is still useful, but it is not a substitute for approval enforcement. A read-only exploration subagent can safely receive search and file-reading tools, while a coding subagent might receive editing tools only after the parent has collected approval. Keep the delegated tool set narrow, describe the subagent’s role in its instructions, and avoid giving one subagent every capability available to the system. The documentation’s specialized orchestration examples point toward separate exploration, coding, and integration subagents, each with a focused tool set and purpose.

Sources: content/docs/03-agents/06-subagents.mdx

System-to-Code Mapping

Implementation Checklist

Start by deciding whether the task really needs delegation. If it is simple, sequential, and comfortably fits in the parent context, keep it as a normal tool or direct model call. If it requires broad exploration, parallel research, or a specialized capability set, define a subagent with narrowly scoped instructions and tools. Then create a parent-facing tool with a clear input schema, call the subagent from execute, forward abortSignal, and return a concise result. Add streaming progress only when users benefit from seeing the delegated work unfold.

Sources: content/docs/03-agents/06-subagents.mdx

Before shipping, review the safety model. Keep approval-required actions outside the subagent, constrain each subagent’s tool access, and decide what information should be returned to the parent model versus only shown to the user. The next useful topics are tool calling, preliminary tool results, stream protocol design, loop control, and tool approvals, because subagents sit at the intersection of all four: they are invoked as tools, may stream progress, participate in multi-step loops, and must respect approval boundaries.