> ## Documentation Index > Fetch the complete documentation index at: https://docs.qoder.com/llms.txt > Use this file to discover all available pages before exploring further. # サブ Agent サブ Agent は、メインセッションが一時的に委任できる専門ロールです。Qoder Agent SDK Python 版は次の2種類のサブ Agent をサポートします。 * **組み込みサブ Agent**：qodercli が提供します。汎用検索、コード探索、計画などがあります。 * **カスタムサブ Agent**：SDK 利用者が `QoderAgentOptions.agents` で定義します。業務レビュー、テスト実行、セキュリティ分析などの専門ロールに適しています。 このガイドでは、Python SDK から組み込みサブ Agent を使う方法と、必要に応じてカスタムサブ Agent を定義する方法を中心に説明します。完全な型定義は [Agents Reference](/ja/cli/sdk/python/references#agents-reference) を参照してください。 特に断りがない限り、このガイドの「Agent」はメインセッションから委任できるサブ Agent を指します。`QoderAgentOptions.agent` は、ある Agent 定義をメインセッションのロールとして実行する特別な使い方です。
## 組み込みサブ Agent 組み込みサブ Agent を使う場合、自分でサブ Agent 定義を書く必要はありません。名前を知っていれば SDK から参照できます。 現在 qodercli でよく使われる組み込みサブ Agent： | 名前 | 用途 | | ----------------- | ------------------------------------------------------------ | | `general-purpose` | 汎用サブ Agent。コード検索、複雑な問題の調査、複数ステップのタスク実行に適しています | | `Explore` | 読み取り専用のコード探索サブ Agent。ファイル検索、キーワード検索、コード構造の把握に適しています | | `Plan` | 読み取り専用の計画サブ Agent。実装方針の設計、重要ファイルの特定、アーキテクチャ上のトレードオフ分析に適しています | 組み込みサブ Agent の一覧は、qodercli のバージョンや現在の設定によって変わります。対話型 CLI では `/agents` を入力すると、現在検出されているサブ Agent を確認できます。コマンドラインでも次を実行できます。 ```bash theme={null} qodercli agents list ``` SDK セッション初期化後は、`QoderSDKClient.supported_agents()` で現在のセッションから実際に利用できるサブ Agent を取得できます。 ```python theme={null} 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()` の戻り値には、SDK が `agents` で登録したサブ Agent と、現在の CLI が検出した組み込み、ユーザー、プロジェクト、プラグインのサブ Agent が含まれることがあります。戻り値の構造は [AgentInfo](/ja/cli/sdk/python/references#agentinfo) を参照してください。
## 組み込みサブ Agent の使用
### メインセッションロールとして実行する セッション全体を組み込みサブ Agent のロールで実行したい場合は、組み込みサブ Agent 名を `QoderAgentOptions.agent` に直接渡します。`agents` で再定義する必要はありません。 ```python theme={null} 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` は SDK が登録したサブ Agent だけでなく、現在の CLI が検出した組み込み / ユーザー / プロジェクト / プラグインのサブ Agent も参照できます。
### サブ Agent として委任する サブ Agent への委任は、組み込みの `Agent` ツールを通じて行われます。メインセッションの利用可能ツール集合に `Agent` が含まれていないと、モデルは委任を開始できません。SDK では、このツール呼び出し経路を事前承認し、prompt 内で対象サブ Agent を指名する方法がよく使われます。 ```python theme={null} 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"]` は、この種類のツール呼び出しを許可または事前承認します。同時に `tools` でメインセッションのツール許可リストを絞る場合は、`tools` にも `Agent` を含めてください。`Agent` を `disallowed_tools` に入れないでください。 サブ Agent 名は、大文字小文字を含めて検出結果と一致している必要があります。たとえば現在の組み込み名には `Explore`、`Plan`、`general-purpose` があります。不確かな場合は先に `client.supported_agents()` を呼び出してください。
## カスタムサブ Agent 組み込みサブ Agent が業務やプロジェクトの制約に合わない場合は、`QoderAgentOptions.agents` でカスタムサブ Agent を定義できます。例： * 読み取り専用コードレビューサブ Agent：ファイルの読み取りと検索だけが可能で、コードは変更できません。 * テスト実行サブ Agent：テストコマンドを実行し、失敗理由を分析できます。 * セキュリティレビューサブ Agent：認証、認可、インジェクション、機密情報漏えいなどのリスクに集中します。 * 業務サポートサブ Agent：注文検索、チケット検索、内部ナレッジベース検索など、指定した MCP ツールだけを呼び出せます。 カスタムサブ Agent は通常、次の3ステップで構成します。 1. `agents` にサブ Agent 名、用途説明、システムプロンプトを定義する。 2. `tools` または `disallowedTools` で利用可能なツールを絞る。 3. メインセッションから `Agent` ツールで委任するか、`agent` でメインセッションを直接駆動させる。 > **`Agent` ツールは必須です**：カスタムサブ Agent は、メインセッションが組み込み `Agent` ツールを通じて委任する必要があるため、`allowed_tools` に `Agent` ツールを含める必要があります。
## agents でカスタムサブ Agent を定義する 最小例：読み取り専用のコードレビューサブ Agent を登録します。 ```python theme={null} 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()) ``` この例の重要点は3つです。 * `QoderAgentOptions.agents` は、このセッションで利用できるカスタムサブ Agent を登録します。 * サブ Agent 委任は `Agent` ツールで行われるため、ここでは `allowed_tools=["Agent"]` でその呼び出し経路を事前承認する必要があります。 * サブ Agent 自身の `tools` は読み取りと検索だけを許可しているため、ファイル編集もコマンド実行もできません。
### `agents` の入力 `agents` は、サブ Agent 名から `AgentDefinition` へのマップです。完全な型は [AgentDefinition](/ja/cli/sdk/python/references#agentdefinition) を参照してください。 | フィールド | 型 | 必須 | 設定例 | 説明 | | ----------------- | -------------------------------------- | --- | --------------------------------------- | --------------------------------------------- | | `description` | `str` | はい | このサブ Agent をいつ使うかを一文で説明 | モデル向けのルーティング説明。呼び出されるかに影響します | | `prompt` | `str` | はい | サブ Agent のロール、境界、出力要件 | そのサブ Agent のシステムプロンプト | | `tools` | `list[str]` | いいえ | `["Read", "Grep", "Glob"]` など | ツール許可リスト。設定後は列挙されたツールだけを使用できます | | `disallowedTools` | `list[str]` | いいえ | `["Bash", "Write"]` など | ツール拒否リスト。少数のツールだけを除外する場合に適します | | `model` | `str` | いいえ | `"inherit"`、`"auto"` または完全なモデル ID | サブ Agent のモデル設定 | | `maxTurns` | `int` | いいえ | `8` など | サブ Agent が実行できる最大ターン数を制限 | | `effort` | `"low" \| "medium" \| "high" \| "max"` | いいえ | `"high"` など | 推論努力レベルを制御します | | `permissionMode` | `PermissionMode` | いいえ | `"default"`、`"acceptEdits"`、`"plan"` など | サブ Agent 内部のツール呼び出し権限モードを制御します | | `skills` | `list[str]` | いいえ | `["review"]` など | サブ Agent コンテキストにプリロードする skill | | `mcpServers` | `list[str \| dict[str, Any]]` | いいえ | `["orders"]` または `[{"kb": {...}}]` など | サブ Agent の MCP server を制限または追加します | | `initialPrompt` | `str` | いいえ | 最初の自動入力 | このサブ Agent が `agent` でメインセッションロールになった場合のみ有効です | Python SDK の `AgentDefinition` フィールド名はプロトコルスタイルの camelCase を使用します。たとえば `disallowedTools`、`maxTurns`、`initialPrompt`、`permissionMode` であって、`disallowed_tools` や `max_turns` ではありません。
## サブ Agent ロールの設定 `description` と `prompt` は、カスタムサブ Agent で最も重要な2つのフィールドです。
### `description` `description` は「いつこのサブ Agent を使うべきか」を説明します。モデルはそれに基づいて委任するかを判断します。 ```python theme={null} description="Runs project tests, analyzes failing output, and suggests fixes." ``` よい `description` はタスクの境界を具体的に示します。`A helpful agent` や `Helper` のような汎用的な説明は避けてください。
### `prompt` `prompt` は、サブ Agent のロール、境界、出力形式を定義します。Python の `AgentDefinition` コンストラクタはこのフィールドの渡し込みを必須としています。 ```python theme={null} 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.""" ``` `prompt` では少なくとも次の3点を説明することを推奨します。 | 説明すること | 例 | | --------- | ------------------------------------------------------ | | 担当タスク | `Review code for security and maintainability issues.` | | してはいけないこと | `Do not edit files. Do not run commands.` | | 結果の返し方 | `Return findings sorted by severity with file paths.` |
## サブ Agent のモデルと推論の設定 まず `description` と `prompt` を明確にしてから、`model`、`effort`、`maxTurns` を検討してください。前者はサブ Agent が正しく呼ばれるか、呼ばれた後に境界を理解できるかを決めます。後者は、ロールが明確になった後で品質、速度、コストを調整するためのものです。 | 設定 | 制御するもの | 優先的に調整する場面 | | ---------- | ----------------------------- | ---------------------------------------------- | | `model` | サブ Agent が使うモデルまたはモデルエイリアスを選択 | このサブ Agent が固定タイプのタスクを継続的に担当し、能力とコストを安定制御したい場合 | | `effort` | 同じモデルでどれだけ推論予算を使うか | 同じサブ Agent が、ときどきより複雑で慎重な推論を必要とするタスクを受ける場合 | | `maxTurns` | 最大実行ターン数を制限 | タスクが深く探索しすぎる、長く走りすぎる、またはコストにハード上限を設けたい場合 | Python の型レベルでは `model` は `str | None` です。よく使う書き方には `"inherit"`、`"auto"`、モデルエイリアス、または現在の CLI / バックエンドがサポートする完全なモデル ID があります。実際に利用できる値は qodercli とバックエンドの設定に依存します。 例：サブ Agent ごとに異なる戦略を設定します。 ```python theme={null} 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, ), } ``` 各フィールドの完全なリファレンスは [Agents Reference - model](/ja/cli/sdk/python/references#agentdefinition-model)、[Agents Reference - maxTurns](/ja/cli/sdk/python/references#agentdefinition-maxturns)、[Agents Reference - effort](/ja/cli/sdk/python/references#agentdefinition-effort) を参照してください。
## サブ Agent のツール制御 カスタムサブ Agent とメインセッションは同じツール名を使います。組み込みツール名には `Read`、`Grep`、`Glob`、`Bash` などがあります。カスタム MCP ツール名は完全形式 `mcp__{serverName}__{toolName}` を使います。
### メインセッション側の `Agent` ツール `agents` はサブ Agent を登録するだけで、モデルに自動で呼び出させるわけではありません。モデルがタスクを委任するには、メインセッションのツール集合に `Agent` が含まれている必要があります。`QoderAgentOptions.tools` でメインセッションの利用可能ツールを制限する場合は、`Agent` を含めるのを忘れないでください。`disallowed_tools=["Agent"]` を設定すると、委任は無効になります。
### ツール許可リスト：`tools` `tools` はサブ Agent のツール許可リストです。設定後、このサブ Agent は列挙されたツールだけを使用できます。 ```python theme={null} tools=["Read", "Grep", "Glob"] ``` よく使うツール組み合わせ： | シナリオ | 推奨ツール | 説明 | | --------- | --------------------------------------- | ----------------------------- | | 読み取り専用分析 | `Read`, `Grep`, `Glob` | コードを読めますが、変更やコマンド実行はできません | | テスト実行 | `Bash`, `Read`, `Grep` | テストコマンドを実行し、出力を分析できます | | コード作成 | `Read`, `Edit`, `Write`, `Grep`, `Glob` | ファイルを読み書きできますが、直接コマンドは実行できません | | 業務ツール呼び出し | `mcp__server__tool` | 指定したカスタムツールだけを許可します |
### ツール拒否リスト：`disallowedTools` `disallowedTools` は「大部分のツールは許可し、少数だけ除外したい」場合に適しています。 ```python theme={null} disallowedTools=["Bash", "Write"] ``` 最終的なツール集合を明確に理解している場合を除き、通常は `tools` と `disallowedTools` を同時に設定しないでください。
### メインセッションのツール設定との関係 サブ Agent の `tools` / `disallowedTools` は、そのサブ Agent にだけ作用します。メインセッションのツール許可リストや拒否リストの絞り込みは継承しません。メインセッション側で `Agent` という委任経路だけを事前承認していても、サブ Agent は自分に設定された `Read`、`Grep` などのツールを使用できます。 ```python theme={null} 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"], ), }, ) ```
## サブ Agent の権限制御 ツール集合は、サブ Agent が「どのツールを呼び出せるか」を決めます。権限設定は、それらのツール呼び出しを「どのように承認またはブロックするか」を決めます。サブ Agent に個別の `permissionMode` を設定し、内部ツール実行の権限挙動を制御できます。 ```python theme={null} 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", ) ``` `permissionMode` の完全な選択肢と意味は [Agents Reference - permissionMode](/ja/cli/sdk/python/references#agentdefinition-permissionmode) を参照してください。ホストがツール呼び出しを毎回承認する必要がある場合は、セッションレベルの `can_use_tool` コールバックを使用できます。コールバックが受け取る `context.agent_id` で、サブ Agent からの呼び出しかどうかを識別できます。
## サブ Agent への skills 読み込み `skills` は、特定のサブ Agent に専門スキルをプリロードするために使います。特定のワークフロー、チーム規約、ツール利用方法を毎回 prompt に入れるのではなく、サブ Agent に紐づけたい場合に適しています。 ```python theme={null} 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"], ) ``` サブ Agent の `skills` はそのサブ Agent のコンテキストだけに影響します。メインセッションの `QoderAgentOptions.skills` と同じではありません。セッションレベルの skill 挙動は [Skills](/ja/cli/sdk/python/skills) を参照してください。
## サブ Agent の mcpServers 設定 `mcpServers` は、サブ Agent の MCP server を制限または追加するために使います。注文検索、チケット検索、内部ナレッジベース検索など、必要なサブ Agent だけに業務ツールを公開したい場合に適しています。 セッションですでに設定した MCP server を参照できます。 ```python theme={null} 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"], ), }, ) ``` 特定のサブ Agent 専用の MCP server を設定することもできます。 ```python theme={null} 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"], ), }, ) ``` 推奨： | シナリオ | 設定方法 | | -------------------------------- | ---------------------------------------------------------------------------------------- | | 複数のサブ Agent が同じ MCP server を共有する | セッションレベルの `QoderAgentOptions.mcp_servers` に server を設定し、サブ Agent の `mcpServers` で名前を参照する | | あるサブ Agent だけが業務ツールを必要とする | server をそのサブ Agent の `mcpServers` に入れ、`tools` で呼び出し可能ツールを制限する | | 特定の MCP ツールだけを呼び出したい | 同時に `tools=["mcp__server__tool"]` を設定し、server の全ツールを公開しない | 各フィールドの完全な状態は [Agents Reference - mcpServers](/ja/cli/sdk/python/references#agentdefinition-mcpservers) を参照してください。
## サブ Agent の呼び出し サブ Agent にはよく使われる3つの呼び出し方法があります。
### 自動呼び出し モデルはタスクと各サブ Agent の `description` に基づいて、呼び出すかどうかを自動で判断します。`description` を明確にすると命中精度が上がります。
### 明示的な指名呼び出し モデルに特定のサブ Agent を使わせたい場合は、prompt で名前を指定します。 ```python theme={null} 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) ``` ### メインセッションロールとして実行する `QoderAgentOptions.agent` は、メインセッションをあるサブ Agent の身分で直接実行させます。 ```python theme={null} 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` は、`agents` のカスタムサブ Agent だけでなく、現在の CLI が検出した組み込み / ユーザー / プロジェクト / プラグインのサブ Agent も参照できます。
## サブ Agent のコンテキストと結果 サブ Agent は独立したコンテキストで実行されます。自分のシステムプロンプトと委任 prompt は受け取りますが、親セッションの完全な履歴を直接継承しません。 | サブ Agent が見えるもの | サブ Agent が見えないもの | | -------------------------------------- | --------------------- | | 自分の `prompt` | 親セッションの完全な会話履歴 | | メインセッションが `Agent` ツールを通じて渡したタスク prompt | 親セッションの中間ツール結果 | | 自分が利用可能なツール定義 | 渡されていない親セッションの非公開推論過程 | | 設定でプリロードされた skills | 他の Agent の中間コンテキスト | 親セッションからサブ Agent へ情報を渡す主な経路は、Agent ツール呼び出し時に渡すタスク prompt です。サブ Agent が特定のファイルパス、エラー情報、業務背景を必要とする場合は、メインセッションが委任時に明示的に渡すようにしてください。 サブ Agent 完了後、親セッションが受け取るのはその最終応答であり、内部の各ツール呼び出しの全コンテキストではありません。
## 組み合わせ例
### 複数ロール協調 異なるロールを持つ複数のサブ Agent を登録し、メインセッションがタスクに応じて呼び出すか、いつ呼び出すかを判断します。 ```python theme={null} 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, ), }, ) ```
### 起動後に最初のタスクを自動実行する `initialPrompt` は、そのサブ Agent が `agent` によりメインセッションロールになった場合だけ有効です。 ```python theme={null} 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) ``` `auditor` がメインセッションから `Agent` ツールでサブ Agent として呼び出された場合、`initialPrompt` は無視されます。
## よくある落とし穴 * 組み込みサブ Agent を直接使う場合、明示的に上書きしたいのでなければ、`agents` に同名のサブ Agent を再定義しないでください。 * サブ Agent の呼び出しは、メインセッションの `Agent` ツールに依存します。`allowed_tools=["Agent"]` は事前承認です。`tools` でメインセッションの利用可能ツールを制限する場合は、そこにも `Agent` を含めてください。 * サブ Agent 名は現在の検出結果と大文字小文字まで一致する必要があります。たとえば `Explore` と `Plan` は先頭が大文字です。 * `description` はモデルにいつ呼び出すかを伝え、`prompt` は呼び出された後にサブ Agent がどう動くかを伝えます。 * サブ Agent はさらに自分のサブ Agent を生成できません。サブ Agent の `tools` に `Agent` を入れないでください。 * `initialPrompt` は `agent` で指定されたメインセッションロールにだけ有効で、サブ Agent として委任された場合は無視されます。 * `AgentDefinition` のフィールド名は camelCase であり、snake\_case ではありません。 * `background`、`memory`、`criticalSystemReminder_EXPERIMENTAL` などのフィールドは型としては存在しますが、SDK の登録経路では現状ランタイム挙動を変更しません。書き込む前に [Agents Reference](/ja/cli/sdk/python/references#agentdefinition) を確認してください。
## 続きを読む * [Agents Reference](/ja/cli/sdk/python/references#agents-reference)：`AgentDefinition`、`AgentInfo`、`agent`、`agents` の完全なリファレンス。 * [Tools](/ja/cli/sdk/python/tools)：組み込みツール、カスタムツール、ツール権限。 * [権限制御](/ja/cli/sdk/python/permissions)：`permissionMode`、`allowed_tools`、`can_use_tool`。 * [Skills](/ja/cli/sdk/python/skills)：セッションレベルとサブ Agent レベルの skill 設定。