> ## 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. # SDK References
## Functions
### `query()` SDK のメインエントリ関数です。到着順にメッセージをストリーミングする非同期イテレータを作成します。 ```python theme={null} async def query( *, prompt: str | AsyncIterable[dict[str, Any]], options: QoderAgentOptions | None = None, ) -> AsyncIterator[Message]: ... ```
#### Parameters | パラメータ | 型 | 説明 | | :-------- | :---------------------------------------- | :-------------------------------------- | | `prompt` | `str \| AsyncIterable[dict[str, Any]]` | 単一ターンの場合は文字列を渡し、マルチターンの場合は非同期イテラブルを渡します | | `options` | [`QoderAgentOptions`](#qoderagentoptions) | 任意のセッション構成 |
#### Return Value `AsyncIterator[Message]` を返し、`async for` で消費します。
### `QoderSDKClient` クラスベースのマルチターン会話 API です。ターンをまたいでセッション状態を保持したり、モデルやパーミッションモードを動的に切り替えたりするシナリオに適しています。 ```python theme={null} client = QoderSDKClient(options=options) await client.connect("Initial prompt.") ``` | メソッド | 説明 | | :----------------------------------------------- | :-------------------------------------- | | `client.query(prompt)` | 新しいターンのユーザー入力を送信 | | `client.receive_response()` | `ResultMessage` までメッセージを消費 | | `client.receive_messages()` | セッション全体のメッセージストリームを受信するバックグラウンド非同期イテレータ | | `client.connect(prompt)` / `client.disconnect()` | 接続を手動で管理 | | `client.interrupt()` | 現在の生成またはツール実行を中断 | | `client.set_model(model)` | 実行時にモデルを切り替え | | `client.set_permission_mode(mode)` | 実行時にパーミッションモードを切り替え | | `client.stop_task(task_id)` | バックグラウンドタスクを停止 | | `client.apply_flag_settings(settings)` | フラグレベルの設定を注入 | | `client.supported_agents()` | 現在利用可能なエージェントを一覧表示 | | `client.get_mcp_status()` | すべての MCP サーバーのステータスを取得 | | `client.set_mcp_servers(servers)` | MCP サーバー構成を置き換え | | `client.reconnect_mcp_server(name)` | 特定の MCP サーバーを再接続 | | `client.toggle_mcp_server(name, enabled)` | MCP サーバーの有効/無効を切り替え | | `client.get_available_models()` | 利用可能なモデル一覧を取得 |
## Types
### `QoderAgentOptions` `query()` および `QoderSDKClient` の構成オブジェクトです。Python SDK では snake\_case のフィールド名を使用します。 | フィールド | 型 | デフォルト | 説明 | | :----------------------------------- | :------------------------------------------------------ | :------ | :-------------------------------------------------------------------------------------- | | `auth` | `InternalAuthOptions \| dict \| None` | `None` | 認証構成 | | `on_auth_expired` | `Callable \| None` | `None` | 認証期限切れ時のコールバック。セッションごとに最大 1 回トリガーされます | | `tools` | `list[str] \| ToolsPreset \| None` | `None` | ツールセット。文字列配列を渡すと利用可能なツールを制限します。組み込みツール名は [組み込みツール一覧](#built-in-tool-list) を参照 | | `allowed_tools` | `list[str]` | `[]` | ツール許可リスト。記載されたツールは事前に承認されます | | `disallowed_tools` | `list[str]` | `[]` | ツール拒否リスト。`allowed_tools` と `permission_mode` より優先されます | | `can_use_tool` | [`CanUseTool`](#canusetool) | `None` | カスタムツールパーミッションコールバック | | `permission_mode` | [`PermissionMode`](#permissionmode) | `None` | セッションパーミッションモード | | `allow_dangerously_skip_permissions` | `bool` | `False` | パーミッションチェックのスキップを許可。`permission_mode="bypassPermissions"` と併用 | | `permission_prompt_tool_name` | `str \| None` | `None` | パーミッションプロンプト用の MCP ツール名。`can_use_tool` と相互排他 | | `model` | `str \| None` | `None` | 使用するモデル | | `fallback_model` | `str \| None` | `None` | メインモデル失敗時のフォールバックモデル | | `resolve_model` | [`ModelPolicyProvider`](#modelpolicyprovider) | `None` | 動的モデル選択コールバック。渡すと動的コールバックモードに切り替わります。詳細は [モデルポリシー](/ja/cli/sdk/python/model-policy) を参照 | | `resolve_model_timeout_ms` | `int` | `500` | コールバックタイムアウト（ミリ秒）。`resolve_model` を渡した場合のみ有効 | | `system_prompt` | `str \| SystemPromptPreset \| SystemPromptFile \| None` | `None` | システムプロンプト | | `cwd` | `str \| Path \| None` | `None` | 作業ディレクトリ | | `env` | `dict[str, str \| None]` | `{}` | CLI プロセスに渡す環境変数 | | `cli_path` | `str \| Path \| None` | `None` | qodercli 実行ファイルへのパス | | `session_id` | `str \| None` | `None` | セッション UUID を指定 | | `resume` | `str \| None` | `None` | 再開するセッション ID | | `continue_conversation` | `bool` | `False` | 直近のセッションを継続 | | `fork_session` | `bool` | `False` | `resume` と併用すると、新しいセッション ID にフォーク | | `max_turns` | `int \| None` | `None` | 最大会話ターン数 | | `include_partial_messages` | `bool` | `False` | `StreamEvent` ストリーミング断片を含める。詳細は [ストリーミング出力](/ja/cli/sdk/python/streaming-output) を参照 | | `mcp_servers` | `dict[str, McpServerConfig] \| str \| Path` | `{}` | MCP サーバー構成。詳細は [MCP](/ja/cli/sdk/python/mcp) を参照 | | `allowed_mcp_server_names` | `list[str]` | `[]` | 利用可能な MCP サーバーを制限 | | `strict_mcp_config` | `bool` | `False` | 厳密な MCP 検証 | | `hooks` | `dict[HookEvent, list[HookMatcher]] \| None` | `None` | ライフサイクルフック。詳細は [Hooks](/ja/cli/sdk/python/hooks) を参照 | | `agents` | `dict[str, AgentDefinition] \| None` | `None` | プログラム的に定義されたサブエージェント。詳細は [Agents リファレンス](#qoderagentoptionsagents) を参照 | | `agent` | `str \| None` | `None` | メインスレッドが使用するエージェント名。詳細は [Agents リファレンス](#qoderagentoptionsagent) を参照 | | `settings` | `str \| Path \| Settings \| None` | `None` | インライン設定オブジェクトまたは設定ファイルパス | | `setting_sources` | `list[SettingSource] \| None` | `None` | 読み込むファイルシステム設定 | | `add_dirs` | `list[str \| Path]` | `[]` | AI がアクセス可能な追加ディレクトリ | | `extra_args` | `dict[str, str \| None]` | `{}` | CLI に渡す追加引数 | | `plugins` | `list[SdkPluginConfig]` | `[]` | ローカルプラグインを読み込む。詳細は [Plugins](/ja/cli/sdk/python/plugins) を参照 | | `skills` | `list[str] \| Literal["all"] \| None` | `None` | 有効化するスキル。`"all"` を渡すとすべて有効化 | | `enable_file_checkpointing` | `bool \| None` | `None` | ファイルチェックポイントを有効化 | | `thinking` | `ThinkingConfig \| None` | `None` | Thinking 構成 |
### Authentication ```python theme={null} from qoder_agent_sdk import access_token, access_token_from_env, qodercli_auth ``` | ファクトリ関数 | 説明 | | :-------------------------------- | :---------------------------------------------- | | `access_token(token)` | PAT を直接渡す | | `access_token_from_env()` | デフォルトの環境変数 `QODER_PERSONAL_ACCESS_TOKEN` から読み取る | | `access_token_from_env("MY_PAT")` | 指定した環境変数から読み取る | | `qodercli_auth()` | ローカルの `qodercli login` セッションを再利用 | 便利な使い方については、[SDK 認証](/ja/cli/sdk/python/authentication) を参照してください。
## Agents Reference このページでは、SDK Agents に関する安定した設定項目をまとめます。入門と利用シーンについては [サブエージェント利用ガイド](/ja/cli/sdk/python/agents) を参照してください。
### Sources of Available Agents 現在のセッションで利用可能な Agent は、複数のソースから提供される場合があります： | ソース | 説明 | | --------------- | ------------------------------------------ | | SDK 登録 | `QoderAgentOptions.agents` を介して現在のセッションに登録 | | CLI 組み込み | qodercli 起動時に登録される組み込み Agent | | ユーザー / プロジェクト設定 | ユーザーまたはプロジェクトの設定ディレクトリ内の Agent 定義 | | プラグイン | ロード済みプラグインが提供する Agent | 対話型 CLI では `/agents` を実行して現在検出されている Agent を確認できます。コマンドラインでは `qodercli agents list` を実行します。Python SDK では `QoderSDKClient` の接続後、`client.supported_agents()` を呼び出して現在のセッションで利用可能な Agent のサマリを取得できます。
### `QoderAgentOptions.agents` **型:** `dict[str, AgentDefinition] | None` 現在のセッションで利用可能なカスタム Agent を登録します。dict のキーは Agent 名、値はその Agent の定義です。 > **`Agent` ツールが必要**: カスタムサブエージェントは、メインセッションが組み込みの `Agent` ツールを介して委譲する必要があるため、`allowed_tools` に `Agent` ツールを含める必要があります。 ```python theme={null} from qoder_agent_sdk import AgentDefinition, QoderAgentOptions options = QoderAgentOptions( allowed_tools=["Agent"], agents={ "reviewer": AgentDefinition( description="Reviews code quality and reports actionable findings.", prompt="Review the requested code and report concrete issues.", tools=["Read", "Grep", "Glob"], ), }, ) ``` 登録後、モデルは組み込みの `Agent` ツールを介してこれらのサブエージェントを呼び出せます。メインセッションは作業を委譲するため、ツールセットに `Agent` を含める必要があります。`allowed_tools=["Agent"]` は必須の事前認可形式です。`tools` でメインセッションの利用可能ツールを絞り込む場合も、そこに `Agent` を含めてください。
### `QoderAgentOptions.agent` **型:** `str | None` メインセッションがどの Agent のアイデンティティとして実行されるかを指定します。値は `agents` に登録された名前、または現在の CLI が検出した組み込み / プラグイン Agent 名です。 ```python theme={null} options = QoderAgentOptions( agents={ "planner": AgentDefinition( description="Plans work before implementation.", prompt="Break work into steps, risks, and validation checks.", tools=["Read", "Grep", "Glob"], ), }, agent="planner", ) ``` 設定すると、メインセッションはその Agent の `prompt`、`model`、ツール制限を使用します。省略した場合は、デフォルトのメインセッション動作が使用されます。
### `AgentDefinition` カスタム Agent の定義です。Python SDK の `AgentDefinition` は dataclass で、フィールド名はプロトコルスタイルの camelCase を使用します。以下のフィールドは、SDK で現在カバーされ、検証済みの安定した機能です。 ```python theme={null} from dataclasses import dataclass from typing import Any, Literal @dataclass class AgentDefinition: description: str prompt: str tools: list[str] | None = None disallowedTools: list[str] | None = None model: str | None = None skills: list[str] | None = None mcpServers: list[str | dict[str, Any]] | None = None initialPrompt: str | None = None maxTurns: int | None = None effort: Literal["low", "medium", "high", "max"] | None = None permissionMode: PermissionMode | None = None ``` | フィールド | 型 | 必須 | 説明 | | ----------------- | ---------------------------------------------- | --- | -------------------------------------------------- | | `description` | `str` | はい | Agent の用途説明。モデルはこれを使って Agent を呼び出すかどうかを判断 | | `prompt` | `str` | はい | Agent のシステムプロンプト | | `tools` | `list[str] \| None` | いいえ | この Agent のツール許可リスト | | `disallowedTools` | `list[str] \| None` | いいえ | この Agent のツールセットから除外するツール | | `model` | `str \| None` | いいえ | モデルのオーバーライド。`"inherit"` はメインセッションのモデルを継承 | | `mcpServers` | `list[str \| dict[str, Any]] \| None` | いいえ | この Agent が利用可能な MCP サーバー指定 | | `skills` | `list[str] \| None` | いいえ | Agent コンテキストにプリロードするスキル名 | | `initialPrompt` | `str \| None` | いいえ | この Agent をメインセッション Agent として使用する際に自動送信される最初のユーザー入力 | | `maxTurns` | `int \| None` | いいえ | Agent の最大 API ターン数 | | `effort` | `"low" \| "medium" \| "high" \| "max" \| None` | いいえ | 推論の effort レベル | | `permissionMode` | `PermissionMode \| None` | いいえ | この Agent 内のツール実行に対する権限モード | Python SDK は `dataclasses.asdict()` を使って `AgentDefinition` を initialize リクエストにシリアライズし、qodercli は現在の Agent スキーマに従ってパースします。
#### `description` Agent がどんなタスクに適しているかを記述します。モデルがこの Agent を選択するかどうかに影響します。 ```python theme={null} description="Runs project tests, analyzes failing output, and suggests fixes." ``` 明確なトリガーシナリオを記述してください。`Helpful assistant` のような広範な記述は避けてください。
#### `prompt` Agent のシステムプロンプト。役割、制約、出力形式を定義するために使用します。 ```python theme={null} prompt="""You are a security reviewer. Check for authentication bypass, authorization bugs, injection risks, and secret leaks. Return findings sorted by severity.""" ```
#### `tools` Agent のツール許可リスト。設定すると、Agent はリストされたツールのみ使用可能です。 ```python theme={null} tools=["Read", "Grep", "Glob"] ``` `tools` を省略すると、サブエージェントのデフォルトツールセットが使用されます。サブエージェントのツールセットは、メインセッションの `allowed_tools` の絞り込みを継承しません。
#### `disallowedTools` Agent のツールセットから特定のツールを除外します。 ```python theme={null} disallowedTools=["Bash", "Write"] ``` `disallowedTools` を省略すると、サブエージェントはメインセッションの `disallowed_tools` の絞り込みを継承しません。最終的なツールセットを明示的に把握している場合を除き、通常は `tools` と `disallowedTools` を併用しないでください。
#### `model` Agent のモデルを指定します。省略するとセッションのデフォルトモデルが使用されます。Python の型レベルでは `str | None` で、SDK はローカルで特定の文字列を制限しません。一般的なモデル階層は以下のとおりです： | 値 | 階層 | 説明 | 適用 | クレジットコスト | | --------------- | ---------- | --------------------------------- | --------------------------- | -------- | | `"auto"` | スマートルーティング | 能力とコストのバランスを取り、最適なモデルをインテリジェントに選択 | ほとんどの日常的な開発作業。推奨デフォルト | 約 1.0x | | `"ultimate"` | アルティメット | エキスパートレベルの深い推論と思考能力 | 複雑なシステム設計と難しい分析 | 約 1.6x | | `"performance"` | パフォーマンス | 高度な推論と高品質な出力 | コア実装、アーキテクチャ設計、リファクタリング | 約 1.1x | | `"efficient"` | エフィシェント | コスト効率の良い標準的な推論 | 基本的なコード生成、ユニットテスト、日常的な Q\&A | 約 0.3x | | `"lite"` | ライト | 基本的な推論、無料で使用可能 | 簡易検証、シンプルなロジック、簡単な質問 | 0x | Agent では 2 つの特殊な形式もサポートしています： | 値 | 説明 | | ----------- | ------------------------------------------------ | | `"inherit"` | メインセッションのモデルを継承。通常 `supported_agents()` には反映されない | | 完全なモデル ID | 現在の CLI / バックエンドがサポートするモデル ID を直接指定 |
#### `mcpServers` ```python theme={null} mcpServers: list[str | dict[str, Any]] | None ``` この Agent が利用可能な MCP サーバーを制限または追加します。各エントリはセッションレベルのサーバー名、またはインラインのサーバー設定マッピングです。 セッションレベルの MCP サーバーを参照： ```python theme={null} options = QoderAgentOptions( mcp_servers={ "orders": { "command": "python", "args": ["servers/orders.py"], }, }, allowed_tools=["Agent"], agents={ "support": AgentDefinition( description="Answers 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 サーバーを設定： ```python theme={null} AgentDefinition( description="Searches the internal knowledge base.", prompt="Search the knowledge base and cite relevant entries.", mcpServers=[ { "kb": { "command": "python", "args": ["servers/kb.py"], }, }, ], tools=["mcp__kb__search"], ) ``` 特定の MCP ツールのみ公開したい場合は、`tools=["mcp__server__tool"]` も併せて設定し、サーバーの全ツールを Agent に公開しないようにしてください。
#### `skills` Agent コンテキストにプリロードするスキル名のリスト。プレーンなスキル名とプラグイン修飾名の両方をサポートします。 ```python theme={null} skills=["review", "sdk-test-plugin:sdk-echo"] ``` セッションレベルのスキル動作については [Skills](/ja/cli/sdk/python/skills) を参照してください。
#### `initialPrompt` `QoderAgentOptions.agent` を通じてこの Agent がメインセッション Agent になるとき、最初のユーザー入力として自動送信されます。 ```python theme={null} initialPrompt="Start by scanning authentication and session management code." ``` このフィールドはメインセッション Agent でのみ有効です。`Agent` ツール経由でサブエージェントとして呼び出される場合は無視されます。
#### `maxTurns` Agent の最大 API ターン数を制限します。コスト、実行時間、ループのリスクを制御するために使用します。 ```python theme={null} maxTurns=6 ```
#### `effort` ```python theme={null} EffortLevel = Literal["low", "medium", "high", "max"] ``` Agent の推論 effort レベルを制御します。`effort` が高いほど、複雑なレビュー、アーキテクチャ分析、リスクの高い変更に通常適していますが、レイテンシとトークン使用量が増加します。
#### `permissionMode` この Agent 内のツール実行に対する権限モードを制御します。セッションレベルの `permission_mode` と同じ意味を持ちますが、スコープはこの Agent に限定されます。セッションレベルの権限チェーン、`allowed_tools` / `disallowed_tools` / `can_use_tool` の優先順位、例については [権限制御](/ja/cli/sdk/python/permissions#デフォルトポリシーの制御permission_mode) を参照してください。 ```python theme={null} PermissionMode = Literal[ "default", "acceptEdits", "plan", "bypassPermissions", "yolo", "dontAsk", "auto", ] ``` | 値 | 意味 | 適用 | | --------------------- | --------------------------------------------------------------------- | --------------------------------------- | | `"default"` | 標準的な権限動作。ツール呼び出しは依然としてツールセット、許可 / 拒否ルール、ランタイム承認、または CLI のデフォルトポリシーを通過 | ほとんどのインタラクティブなサブエージェント | | `"acceptEdits"` | ファイル編集操作を自動的に受け入れる。他のセンシティブな操作は引き続き権限フローに従う | ワークスペースファイルの変更が承認されているサブエージェント | | `"bypassPermissions"` | 権限チェックをスキップ。高リスクモード。通常は信頼された自動化またはテスト環境のみ | 制御された CI、一時検証、ワンオフ自動化 | | `"yolo"` | `"bypassPermissions"` の互換エイリアス。同様に権限チェックをスキップ | 古い設定との互換性。新規コードでは推奨されない | | `"plan"` | プランモード。先にプランを生成するのに適しており、デフォルトでは実際の変更を行わない | 計画、設計、レビュー、またはサブエージェントがファイルを変更すべきでないケース | | `"dontAsk"` | インタラクティブな確認をしない。事前認可されていないか、ルールで許可されていない操作は拒否 | 非インタラクティブ環境、またはプロンプトではなく失敗すべきワークフロー | | `"auto"` | ランタイム能力が許可または拒否を自動決定 | 確認による中断を減らしつつ、ランタイム判断を保持 | 権限のセマンティクスについては [権限制御](/ja/cli/sdk/python/permissions) を参照してください。
### `AgentInfo` `QoderSDKClient.supported_agents()` が返す Agent サマリ。 ```python theme={null} class AgentInfo(TypedDict): name: str description: str model: NotRequired[str | None] ``` Python SDK は現在 `AgentInfo` という名前の TypedDict をエクスポートしていません。`supported_agents()` の戻り値の型は `list[dict[str, Any]]` です。上記の構造は、実際に返される dict の安定したフィールド規約です。 | フィールド | 型 | 説明 | | ------------- | ------------- | -------------------------------------------------- | | `name` | `str` | Agent 名 | | `description` | `str` | Agent の用途説明 | | `model` | `str \| None` | Agent のモデルオーバーライド。未設定または `model="inherit"` の場合は通常空 | ```python theme={null} from qoder_agent_sdk import AgentDefinition, QoderAgentOptions, QoderSDKClient options = QoderAgentOptions( agents={ "reviewer": AgentDefinition( description="Reviews code quality.", prompt="Review code and report findings.", ), }, ) client = QoderSDKClient(options=options) await client.connect("List agents.") agents = client.supported_agents() await client.disconnect() ``` 返されるリストには、`agents` で登録された Agent や、現在の CLI が検出した組み込み、プロジェクト、ユーザー、プラグインの Agent が含まれる場合があります。実際に利用可能なエントリは qodercli のバージョンと現在の設定に依存します。
### Context and Invocation Boundaries * サブエージェントは独立したコンテキストを使用し、親セッションの完全な履歴を受け取りません。 * 親セッションからサブエージェントに渡される主要な情報は、`Agent` ツールに供給されるタスクプロンプトです。 * サブエージェントの中間ツール結果は親セッションに直接入りません。親セッションはサブエージェントの最終応答を受け取ります。 * サブエージェントは自身のサブエージェントを生成できないため、サブエージェントの `tools` に `Agent` を含めないでください。 * `initialPrompt` は `agent` で指定されたメインセッション Agent でのみ有効です。