BroadRouter
Get started

Subagent

Updated

A subagent is a separate agent that a main agent starts to handle one focused task. It runs with its own context window, system prompt and tool access, does the work, and returns only a result or summary to the main agent, which keeps the main conversation small.

Also called: sub-agent, child agent

A subagent is delegation for agents: hand one job to a fresh worker and get back only the answer.

How it works

The main agent decides a task is self-contained, such as “find every caller of this function” or “run the test suite and report failures”. It starts a subagent with a task description. The subagent runs its own agent loop and returns a result.

Claude Code’s docs put it this way: “Each subagent runs in its own context window with a custom system prompt, specific tool access, and independent permissions.” A subagent is defined as a Markdown file with YAML frontmatter, project-level in .claude/agents/:

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

The listed benefits include keeping exploration out of the main conversation, limiting which tools a subagent can use, and routing tasks to lower-cost models.

Other frameworks have similar ideas. The OpenAI Agents SDK says “Handoffs allow an agent to delegate tasks to another agent,” and represents each handoff to the model as a tool.

Anthropic’s context engineering post describes the pattern from the context side: each sub-agent works in a clean context window and “returns only a condensed, distilled summary of its work,” often 1,000 to 2,000 tokens.

Why it matters

  • Context. A test run can print tens of thousands of tokens. In a subagent, that output stays out of the main context window; only the summary comes back. This is a core context engineering tool.
  • Cost. Total tokens usually go up, since each subagent loads its own prompt and tools. The multi-agent cost post estimates the multiplier.
  • Parallelism. Subagents that run at the same time are parallel requests. Your provider’s concurrency limit decides how many run at once.

On BroadNet Inference

BroadNet serves models; the subagent logic lives in your agent tool. Any tool that accepts an OpenAI-compatible base URL can point its main agent and its subagents at BroadNet, and can use different models for each.

On pay-as-you-go, a key allows 4 requests in flight. On the flat-rate plans for DeepSeek V4.1 Flash, each session runs one request at a time, so count the model requests that can be in flight at the same moment: three subagents running at once need three sessions, and four if the orchestrator also calls the model while they run. Running parallel coding agents on a flat-rate API covers the session count in detail.

Questions

Does a subagent save tokens?

It saves context in the main conversation, not total tokens. The subagent's own requests still cost tokens. Claude Code's docs note that subagent requests still draw on your usage, and suggest a smaller model for simple subagent tasks.

Can a subagent start its own subagents?

It depends on the tool. Claude Code's docs say a subagent can by default spawn subagents of its own, up to three layers below the main conversation, and that this can be limited.

What is the difference between a subagent and a handoff?

A subagent works on a task and reports back to the agent that called it. In the OpenAI Agents SDK, a handoff lets one agent delegate to another, and the handoff() helper transfers control to that agent.

Read as MarkdownAsk ChatGPTAsk ClaudeAsk Perplexity