Subagents

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

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

This guide focuses on using built-in subagents from the Python SDK and defining custom subagents on demand. For complete type definitions, see Agents Reference.

Unless otherwise noted, “Agent” in this guide means a subagent that the main session can delegate to. QoderAgentOptions.agent is a special usage that runs an Agent 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 QoderSDKClient.supported_agents() to read the subagents actually available to the current session:

from qoder_agent_sdk import QoderSDKClient, QoderAgentOptions


client = QoderSDKClient(options=QoderAgentOptions())
await client.connect("List available agents.")
agents = client.supported_agents()
await client.disconnect()

supported_agents() returns the subagents registered through agents plus the built-in, user, project, and plugin subagents discovered by the current CLI. See AgentInfo for the return structure.

---

Using Built-in Subagents

Run as the Main Session Role

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

from qoder_agent_sdk import QoderAgentOptions, query


options = QoderAgentOptions(agent="general-purpose")

async for message in query(
    prompt="Summarize this project architecture and identify the most important modules.",
    options=options,
):
    print(message)

agent can reference a subagent registered by the SDK, or a built-in / user / project / plugin subagent discovered by the current CLI.

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.

options = QoderAgentOptions(
    allowed_tools=["Agent"],
)

async for message in query(
    prompt="Use the Explore agent to find where authentication is implemented.",
    options=options,
):
    print(message)

allowed_tools=["Agent"] allows or pre-authorizes this class of tool calls. If you also use tools to restrict the main session tool allowlist, include Agent in tools as well. Do not put Agent in disallowed_tools.

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 client.supported_agents() first.

---

Custom Subagents

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

• Read-only code review subagent: can only read files and search; 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 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 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, so allowed_tools must include the Agent tool.

---

Defining Custom Subagents with agents

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

import asyncio

from qoder_agent_sdk import AgentDefinition, QoderAgentOptions, query


async def main():
    options = QoderAgentOptions(
        allowed_tools=["Agent"],
        agents={
            "code-reviewer": AgentDefinition(
                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"],
            ),
        },
    )

    async for message in query(
        prompt="Use the code-reviewer agent to review the authentication module.",
        options=options,
    ):
        print(message)


asyncio.run(main())

There are three key points in this example:

• QoderAgentOptions.agents registers the custom subagents available to this session.
• Subagent delegation happens through the Agent tool; you must use allowed_tools=["Agent"] here to pre-authorize that call path.
• The subagent’s own tools only allow reading and searching, so it cannot edit files or execute commands.

agents Input

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

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

The Python SDK’s AgentDefinition field names use protocol-style camelCase, such as disallowedTools, maxTurns, initialPrompt, and permissionMode, not disallowed_tools or max_turns.

---

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. The Python AgentDefinition constructor requires this field.

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."""

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 Subagent Model and Reasoning

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

Option	Controls	When to adjust first
model	Selects which model or model alias the subagent uses	This subagent repeatedly handles a fixed type of task and you need stable capability and 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

At the Python type level, model is str | None. Common values include "inherit", "auto", model aliases, or any full model ID supported by the current CLI / backend. Actual usable values depend on qodercli and backend configuration.

Example: give different subagents different strategies.

agents = {
    "explorer": AgentDefinition(
        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="inherit",
        effort="low",
        maxTurns=5,
    ),
    "architect": AgentDefinition(
        description="Designs complex implementation plans across modules.",
        prompt="Analyze tradeoffs carefully and return an implementation plan with risks.",
        tools=["Read", "Grep", "Glob"],
        model="auto",
        effort="high",
        maxTurns=10,
    ),
}

For complete field reference, 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}.

The Main Session’s Agent Tool

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. If you set QoderAgentOptions.tools to limit the main session’s available tools, remember to include Agent. If you set disallowed_tools=["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 / 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.

options = QoderAgentOptions(
    allowed_tools=["Agent"],
    agents={
        "analyst": AgentDefinition(
            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.

AgentDefinition(
    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 can_use_tool callback; the context.agent_id received by the callback can be used to identify whether the call comes from a subagent.

---

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.

AgentDefinition(
    description="Reviews pull requests using the team review workflow.",
    prompt="Review the requested changes and return actionable findings.",
    tools=["Read", "Grep", "Glob"],
    skills=["review"],
)

A subagent’s skills only affect that subagent’s context. They are not the same as the main session’s QoderAgentOptions.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:

options = QoderAgentOptions(
    mcp_servers={
        "orders": {
            "command": "python",
            "args": ["servers/orders.py"],
        },
    },
    allowed_tools=["Agent"],
    agents={
        "support": AgentDefinition(
            description="Answers customer support questions using order tools.",
            prompt="Use order tools when needed and return a concise answer.",
            mcpServers=["orders"],
            tools=["mcp__orders__lookup_order"],
        ),
    },
)

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

options = QoderAgentOptions(
    allowed_tools=["Agent"],
    agents={
        "knowledge": AgentDefinition(
            description="Searches the internal knowledge base.",
            prompt="Search the knowledge base and cite the relevant entries.",
            mcpServers=[
                {
                    "kb": {
                        "command": "python",
                        "args": ["servers/kb.py"],
                    },
                },
            ],
            tools=["mcp__kb__search"],
        ),
    },
)

Recommendations:

Scenario	How to configure
Multiple subagents share one MCP server	Configure the server in session-level QoderAgentOptions.mcp_servers, 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 complete field status, see 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.

Explicit Invocation

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

async for message in query(
    prompt="Use the tester agent to run the unit tests and summarize failures.",
    options=QoderAgentOptions(
        allowed_tools=["Agent"],
        agents={
            "tester": AgentDefinition(
                description="Runs tests and analyzes failures.",
                prompt="Run the requested tests and explain failures clearly.",
                tools=["Bash", "Read", "Grep"],
            ),
        },
    ),
):
    print(message)

Run as the Main Session Role

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

options = QoderAgentOptions(
    agents={
        "planner": AgentDefinition(
            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",
)

agent can reference a custom subagent in agents, or a built-in / user / project / 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.

---

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.

options = QoderAgentOptions(
    allowed_tools=["Agent"],
    agents={
        "researcher": AgentDefinition(
            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": AgentDefinition(
            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": AgentDefinition(
            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 agent:

options = QoderAgentOptions(
    agents={
        "auditor": AgentDefinition(
            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",
)

async for message in query(prompt="", options=options):
    print(message)

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 agents unless you intentionally want to override it.
• Calling subagents depends on the main session’s Agent tool. allowed_tools=["Agent"] pre-authorizes it; if you use 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 agent; it is ignored when the agent is delegated to as a subagent.
• AgentDefinition field names are camelCase, not snake_case.
• Fields like background, memory, and criticalSystemReminder_EXPERIMENTAL exist as types, but the SDK registration pipeline does not currently use them to change runtime behavior. Check Agents Reference before relying on them.

---

Continue Reading

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