Subagents

Subagents are specialized roles that the main session can delegate to temporarily. The Qoder Agent SDK supports two kinds of subagents:

• Built-in subagents: Provided by qodercli, such as general search, code exploration, planning, and related roles.
• Custom subagents: Defined by SDK users through options.agents, suitable for business review, test execution, security analysis, and other specialized roles.

This guide focuses on using built-in subagents from the SDK and defining custom subagents when needed. You can read it from top to bottom or jump to a specific configuration item. For complete type definitions, see Agents Reference.

Unless otherwise noted, “Agent” in this guide means a subagent that the main session can delegate to. options.agent is a special usage that runs a subagent definition as the main session role.

Built-in Subagents

When using a built-in subagent, you do not need to write the subagent definition yourself. You only need to know its name and reference it from the SDK.

Common built-in subagents currently provided by qodercli:

Name	Purpose
general-purpose	General-purpose subagent, suitable for searching code, researching complex problems, and executing multi-step tasks
Explore	Read-only code exploration subagent, suitable for quickly finding files, searching keywords, and understanding code structure
Plan	Read-only planning subagent, suitable for designing implementation plans, identifying key files, and analyzing architectural tradeoffs

The built-in subagent list can change with the qodercli version and current configuration. In the interactive CLI, enter /agents to view the currently discovered subagents. From the command line, you can also run:

qodercli agents list

After an SDK session is initialized, use q.supportedAgents() to read the subagents actually available to the current session:

import { query } from '@qoder-ai/qoder-agent-sdk';

const q = query({ prompt: 'List available agents.' });
const agents = await q.supportedAgents();

q.supportedAgents() returns subagents registered through options.agents and built-in, user, project, and plugin subagents discovered by the current CLI that are suitable for SDK sessions. general-purpose, Explore, and Plan may appear by default in SDK sessions; the interactive CLI helper agents qoder-guide and statusline-setup are not supported in SDK sessions and are not returned by q.supportedAgents(). See AgentInfo for the return structure.

---

Using Built-in Subagents

Run as the Main Session Role

If you want the whole session to run under a built-in subagent role, pass the built-in subagent name directly to options.agent. You do not need to redefine it in options.agents.

import { query } from '@qoder-ai/qoder-agent-sdk';

const q = query({
  prompt: 'Summarize this project architecture and identify the most important modules.',
  options: {
    agent: 'general-purpose',
  },
});

options.agent can reference a subagent registered by the SDK, or a built-in, user, project, or plugin subagent discovered by the current CLI and suitable for SDK sessions.

Delegate as a Subagent

Subagent delegation happens through the built-in Agent tool. The main session’s available tool set must include Agent; otherwise the model has no entry point for delegation. In SDK usage, a common pattern is to pre-authorize that tool call path and name the desired subagent in the prompt.

const q = query({
  prompt: 'Use the Explore agent to find where authentication is implemented.',
  options: {
    // Pre-authorize Agent tool calls. If options.tools restricts the tool set, include 'Agent' there too.
    allowedTools: ['Agent'],
  },
});

allowedTools: ['Agent'] allows or pre-authorizes this class of tool calls. If you also use options.tools to restrict the main session tool allowlist, include Agent in tools as well. Do not put Agent in disallowedTools.

The subagent name must match the discovered result exactly, including case. For example, current built-in names include Explore, Plan, and general-purpose. If unsure, call q.supportedAgents() first.

---

Custom Subagents

When built-in subagents do not fit your business or project constraints, define custom subagents with options.agents. For example:

• Read-only code review subagent: can only read files and search, and cannot modify code.
• Test execution subagent: can run test commands and analyze failure reasons.
• Security review subagent: focuses only on authentication, authorization, injection, sensitive information leakage, and related risks.
• Business support subagent: can only call specific MCP tools, such as order lookup, ticket search, or internal knowledge base search.

Custom subagents usually involve three steps:

1. Define the subagent name, usage description, and system prompt in options.agents.
2. Narrow the tools it can use with tools or disallowedTools.
3. Let the main session delegate to it through the Agent tool, or use options.agent to let it drive the main session directly.

The Agent tool is required: Custom subagents need the main session to delegate through the built-in Agent tool. The Agent tool must be included in allowedTools because Qoder invokes subagents through the Agent tool.

---

Defining Custom Subagents with options.agents

Minimal example: register a read-only code review subagent.

import { query } from '@qoder-ai/qoder-agent-sdk';

const q = query({
  prompt: 'Use the code-reviewer agent to review the authentication module.',
  options: {
    // Pre-authorize Agent tool calls. If options.tools restricts the tool set, include 'Agent' there too.
    allowedTools: ['Agent'],
    agents: {
      'code-reviewer': {
        description:
          'Reviews code for correctness, security issues, and maintainability problems.',
        prompt: `You are a code review specialist.
Review the requested code and report concrete findings.
Sort findings by severity and include file paths when possible.`,
        tools: ['Read', 'Grep', 'Glob'],
      },
    },
  },
});

for await (const message of q) {
  // Consume streamed messages according to your application needs.
}

There are three key points in this example:

• options.agents registers the custom subagent available to this session.
• Subagent delegation happens through the Agent tool; this example must use allowedTools: ['Agent'] to pre-authorize that call path.
• The subagent’s own tools only allow reading and searching, so it cannot edit files or execute commands.

options.agents Input

options.agents maps subagent names to subagent definitions. See AgentDefinition for the complete type.

Field	Type	Required	How to set it	Description
description	string	Yes	One sentence describing when to use this subagent	Routing description for the model; affects whether it is invoked
prompt	string	Yes	The subagent’s role, boundaries, and output requirements	System prompt for this subagent
tools	string[]	No	For example ['Read', 'Grep', 'Glob']	Tool allowlist; when set, only listed tools can be used
disallowedTools	string[]	No	For example ['Bash', 'Write']	Tool blocklist, useful when excluding only a few tools
model	string	No	For example 'inherit', 'auto', 'performance'	Model configuration for the subagent
maxTurns	number	No	For example 8	Limits how many turns the subagent may execute
effort	EffortLevel	No	For example 'low', 'medium', 'high', 'max'	Controls reasoning effort
permissionMode	PermissionMode	No	For example 'default', 'acceptEdits', 'plan'	Controls the permission mode for tool calls inside the subagent
skills	string[]	No	For example ['review']	Skills preloaded into the subagent context
mcpServers	AgentMcpServerSpec[]	No	MCP server names or configurations	Limits or adds MCP servers for the subagent
initialPrompt	string	No	First-turn automatic input	Only takes effect when this subagent becomes the main session role through options.agent

---

Configuring the Subagent Role

description and prompt are the two most important fields for a custom subagent.

description

description explains when this subagent should be used. The model uses it to decide whether to delegate.

description:
  'Runs project tests, analyzes failing output, and suggests fixes.'

A good description should state the task boundary clearly. Avoid generic descriptions such as A helpful agent or Helper.

prompt

prompt defines the subagent’s role, boundaries, and output format. TypeScript users get a type error if they omit prompt; JavaScript users should also always provide it.

prompt: `You are a code review specialist.
Only review the requested code; do not edit files.
Return findings sorted by severity, with file paths and suggested fixes.`

If prompt only says something vague like “you are a helpful assistant”, the model may still call the subagent, but the subagent will behave much like a general assistant: it will not know what to prioritize, what to avoid, or how to return results.

At minimum, prompt should explain three things:

What to explain	Example
What task it owns	Review code for security and maintainability issues.
What it should not do	Do not edit files. Do not run commands.
How to return results	Return findings sorted by severity with file paths.

---

Configuring Model and Reasoning

First make description and prompt clear, then consider model, effort, and maxTurns. The former decides whether the subagent is invoked correctly and whether it understands its boundaries. The latter mainly tunes quality, speed, and cost after the role is clear.

Option	Controls	When to adjust first
model	Which model tier the subagent uses	This subagent repeatedly handles a fixed type of task and you need stable capability and credit cost
effort	How much reasoning budget to spend under the same model	The same subagent occasionally receives a more complex task that needs more careful reasoning
maxTurns	The maximum number of turns	The task may explore too deeply or run too long, or you want a hard cost limit

Use this order of judgment:

1. Start with no setting, or set model: 'inherit', so the subagent follows the main session model.
2. For frequent, simple, low-risk tasks, use model: 'efficient' or model: 'lite' to reduce cost.
3. For architecture design, complex refactors, cross-module reviews, and other high-risk tasks, use model: 'performance' or model: 'ultimate'.
4. If the model tier stays the same but you want the subagent to think more on the current task, increase effort.
5. If you are worried about runaway exploration, combine it with maxTurns.

Common combinations:

Scenario	Recommended configuration	Description
Quick Q&A, format conversion, simple locating	model: 'efficient', effort: 'low', maxTurns: 3	Cheap and fast, suitable for low-risk tasks
Read-only code exploration and module mapping	model: 'auto' or 'inherit', effort: 'medium'	Let routing or the main session model decide the capability tier
Code review, security review, migration plan	model: 'performance', effort: 'high'	Better for tasks that require careful tradeoffs and issue discovery
Complex system design and difficult analysis	model: 'ultimate', effort: 'high' or 'max'	Higher cost; recommended only for critical complex tasks
Batch helper subtasks	model: 'efficient', effort: 'low', smaller maxTurns	Helps control total cost in multi-subagent collaboration

Example: give different subagents different strategies.

agents: {
  explorer: {
    description: 'Quickly searches code and summarizes relevant files.',
    prompt: 'Find relevant files and return a concise summary. Do not edit.',
    tools: ['Read', 'Grep', 'Glob'],
    model: 'efficient',
    effort: 'low',
    maxTurns: 5,
  },
  architect: {
    description: 'Designs complex implementation plans across modules.',
    prompt: 'Analyze tradeoffs carefully and return an implementation plan with risks.',
    tools: ['Read', 'Grep', 'Glob'],
    model: 'performance',
    effort: 'high',
    maxTurns: 10,
  },
}

For complete values, see Agents Reference - model, Agents Reference - maxTurns, and Agents Reference - effort.

---

Controlling Subagent Tools

Custom subagents and the main session use the same tool names. Built-in tool names include Read, Grep, Glob, and Bash; custom MCP tools use the full format mcp__{serverName}__{toolName}. These settings decide which tools the subagent can see and call.

The Main Session’s Agent Tool

options.agents only registers subagents. It does not automatically make the model call them. To delegate a task, the main session’s tool set must contain Agent. The default tool set usually registers it. If you use options.tools to limit the main session’s available tools, remember to include Agent. If you set disallowedTools: ['Agent'], delegation is disabled.

Tool Allowlist: tools

tools is the subagent’s tool allowlist. Once set, the subagent can only use listed tools.

tools: ['Read', 'Grep', 'Glob']

Common tool combinations:

Scenario	Recommended tools	Description
Read-only analysis	Read, Grep, Glob	Can inspect code; cannot modify files or run commands
Run tests	Bash, Read, Grep	Can execute test commands and analyze output
Write code	Read, Edit, Write, Grep, Glob	Can read and write files but cannot run commands directly
Call business tools	mcp__server__tool	Only allows specific custom tools

Tool Blocklist: disallowedTools

disallowedTools is useful when you want to allow most tools while excluding a few.

disallowedTools: ['Bash', 'Write']

Usually avoid setting both tools and disallowedTools unless you are certain of the final tool set.

Relationship to Main Session Tool Configuration

A subagent’s tools and disallowedTools only apply to that subagent. They do not inherit the main session’s tool allowlist or blocklist trimming. Even if the main session only pre-authorizes the Agent delegation path, the subagent can still use its own configured Read, Grep, and related tools.

query({
  prompt: 'Use the analyst agent to inspect the repository.',
  options: {
    // Pre-authorize the main session to call the Agent tool.
    allowedTools: ['Agent'],
    agents: {
      analyst: {
        description: 'Reads and summarizes code structure.',
        prompt: 'Inspect relevant files and return a concise summary. Do not edit files.',
        tools: ['Read', 'Grep', 'Glob'],
      },
    },
  },
});

---

Controlling Subagent Permissions

The tool set decides which tools a subagent can call. Permission settings decide how those tool calls are approved or blocked. You can configure permissionMode separately on a subagent to control permission behavior for its internal tool execution.

Permission Mode: permissionMode

agents: {
  planner: {
    description: 'Plans implementation work without making changes.',
    prompt: 'Read relevant files and return an implementation plan. Do not edit files.',
    tools: ['Read', 'Grep', 'Glob'],
    permissionMode: 'plan',
  },
}

For complete values and semantics of permissionMode, see Agents Reference - permissionMode. If the host needs to approve tool calls one by one, use the session-level canUseTool callback.

---

Loading Skills for Subagents

skills preloads specialized skills for a subagent. It is useful when you want to bind a specific workflow, team convention, or tool usage pattern to one subagent instead of putting it in every prompt.

agents: {
  reviewer: {
    description: 'Reviews pull requests using the team review workflow.',
    prompt: 'Review the requested changes and return actionable findings.',
    tools: ['Read', 'Grep', 'Glob'],
    skills: ['review'],
  },
}

Recommendations:

Scenario	How to configure
The subagent always follows a specialized workflow	Put the corresponding skill in the subagent’s skills
Only the main session needs a skill	Use session-level options.skills; do not put it in the subagent
A plugin-provided skill	Use the plugin-qualified name, for example sdk-test-plugin:sdk-echo

Subagent skills only affect that subagent’s context. They are not the same as main-session options.skills. For session-level skill behavior, see Skills.

---

Configuring Subagent mcpServers

mcpServers limits or adds MCP servers for a subagent. It is suitable for exposing business tools only to the subagents that need them, such as order lookup, ticket search, or internal knowledge base search.

You can reference an MCP server already configured at the session level:

const q = query({
  prompt: 'Use the support agent to check the latest order status.',
  options: {
    mcpServers: {
      orders: {
        type: 'stdio',
        command: 'node',
        args: ['servers/orders.js'],
      },
    },
    allowedTools: ['Agent'],
    agents: {
      support: {
        description: 'Answers customer support questions using order tools.',
        prompt: 'Use order tools when needed and return a concise answer.',
        mcpServers: ['orders'],
        tools: ['mcp__orders__get_order'],
      },
    },
  },
});

You can also configure a dedicated MCP server for a specific subagent:

agents: {
  knowledge: {
    description: 'Searches the internal knowledge base.',
    prompt: 'Search the knowledge base and cite the relevant entries.',
    mcpServers: [
      {
        kb: {
          type: 'stdio',
          command: 'node',
          args: ['servers/kb.js'],
        },
      },
    ],
    tools: ['mcp__kb__search'],
  },
}

Recommendations:

Scenario	How to configure
Multiple subagents share one MCP server	Configure the server in session-level options.mcpServers, then reference its name in the subagent’s mcpServers
Only one subagent needs a business tool	Put the server in that subagent’s mcpServers, and use tools to limit callable tools
You only want to call a specific MCP tool	Also set tools: ['mcp__server__tool'] to avoid exposing every tool from the server

For the MCP server configuration structure, see MCP and Agents Reference - mcpServers.

---

Invoking Subagents

Subagents have three common invocation modes.

Automatic Invocation

The model decides whether to call a subagent based on the task and each subagent’s description. Clear descriptions improve routing accuracy.

agents: {
  tester: {
    description: 'Runs tests and analyzes test failures.',
    prompt: 'Run relevant tests and explain any failures clearly.',
    tools: ['Bash', 'Read', 'Grep'],
  },
}

Explicit Invocation

If you want the model to use a specific subagent, name it in the prompt.

const q = query({
  prompt: 'Use the tester agent to run the unit tests and summarize failures.',
  options: {
    // Pre-authorize Agent tool calls. If options.tools restricts the tool set, include 'Agent' there too.
    allowedTools: ['Agent'],
    agents: {
      tester: {
        description: 'Runs tests and analyzes failures.',
        prompt: 'Run the requested tests and explain failures clearly.',
        tools: ['Bash', 'Read', 'Grep'],
      },
    },
  },
});

Run as the Main Session Role

options.agent makes the main session run directly as a subagent identity.

const q = query({
  prompt: 'Plan the refactor for the payment module.',
  options: {
    agents: {
      planner: {
        description: 'Plans implementation work before code changes.',
        prompt: 'Break the task into clear steps, risks, and validation checks.',
        tools: ['Read', 'Grep', 'Glob'],
        model: 'inherit',
      },
    },
    agent: 'planner',
  },
});

options.agent can reference a custom subagent in options.agents, or a built-in, user, project, or plugin subagent discovered by the current CLI.

---

Subagent Context and Results

A subagent runs in an independent context. It receives its own system prompt and delegation prompt, but it does not directly inherit the parent session’s full history.

Subagent can see	Subagent cannot see
Its own prompt	Full parent-session conversation history
The task prompt passed by the main session through the Agent tool	Intermediate tool results from the parent session
Its own available tool definitions	Parent session private reasoning that was not passed to it
Skills preloaded by configuration	Intermediate context from other Agents

The main channel for passing information from the parent session to a subagent is the task prompt passed when calling the Agent tool. If a subagent needs specific file paths, error messages, or business context, make the main session pass them explicitly during delegation.

When a subagent completes, the parent session receives its final response, not the full context of every internal tool call. This is one of the main benefits of using subagents to isolate context.

---

Combined Examples

Multi-role Collaboration

Register multiple subagents with different roles. The main session decides whether and when to call them based on the task.

const q = query({
  prompt: 'Add input validation to the user registration endpoint.',
  options: {
    // Pre-authorize Agent tool calls. If options.tools restricts the tool set, include 'Agent' there too.
    allowedTools: ['Agent'],
    agents: {
      researcher: {
        description: 'Reads existing code to understand patterns and constraints.',
        prompt: 'Research relevant files and report implementation constraints. Do not edit.',
        tools: ['Read', 'Grep', 'Glob'],
        maxTurns: 8,
      },
      implementer: {
        description: 'Implements code changes following existing project conventions.',
        prompt: 'Implement the requested change with minimal, idiomatic edits.',
        tools: ['Read', 'Edit', 'Write', 'Grep', 'Glob'],
        maxTurns: 12,
      },
      tester: {
        description: 'Runs tests and explains failures.',
        prompt: 'Run relevant tests, summarize results, and identify failing cases.',
        tools: ['Bash', 'Read', 'Grep'],
        maxTurns: 6,
      },
    },
  },
});

Automatically Run the First Task After Startup

initialPrompt only takes effect when that subagent becomes the main session role through options.agent:

const q = query({
  prompt: '',
  options: {
    agents: {
      auditor: {
        description: 'Audits code for security risks.',
        prompt: 'Scan code for security risks and produce a concise report.',
        initialPrompt: 'Start with the authentication and session management code.',
        tools: ['Read', 'Grep', 'Glob'],
        effort: 'high',
      },
    },
    agent: 'auditor',
  },
});

If auditor is called as a subagent through the main session’s Agent tool, initialPrompt is ignored.

---

Common Pitfalls

• When directly using a built-in subagent, do not redefine a subagent with the same name in options.agents unless you intentionally want to override it.
• Calling subagents depends on the main session’s Agent tool. allowedTools: ['Agent'] pre-authorizes it; if you use options.tools to restrict main-session tools, include Agent there too.
• Subagent names are case-sensitive and must match the discovered result, such as Explore and Plan with capitalized first letters.
• description tells the model when to call the subagent; prompt tells the subagent what to do after it is called.
• Subagents cannot spawn their own subagents. Do not put Agent in a subagent’s tools.
• initialPrompt only takes effect for the main session role specified by options.agent; it is ignored when the agent is delegated to as a subagent.
• Dedicated MCP servers for subagents can be configured through mcpServers; see MCP for MCP connection methods.

---

Continue Reading

• Agents Reference: Complete reference for AgentDefinition, AgentInfo, options.agent, and options.agents.
• Tools: Built-in tools, custom tools, and tool permissions.
• Permissions: permissionMode, allowedTools, and canUseTool.
• Skills: Session-level and subagent-level skill configuration.