> ## 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 に組み込み、MCP、カスタムツールを装備する。
ツールは Agent が**何ができるか**を決定します。Agent の作成または更新時に `tools` フィールドを設定することで、Agent の能力範囲を正確に制御できます。
## ツールの役割
Agent はタスクの実行時に、`tools` の設定に基づいてどの機能を呼び出せるかを判断します。組み込みツールは `{ "type": "agent_toolset_20260401", "enabled_tools": [...] }` で設定し、`enabled_tools` 配列内の個別ツールを必要に応じて有効化します。クライアントサイドのカスタムツールは独立した `{ "type": "custom", ... }` エントリで設定します。
`enabled_tools` が空でないホワイトリストの場合、リスト外のツールはモデルに一切見えず、呼び出しの試行も行われません。`enabled_tools` を省略するか空配列にした場合、すべての組み込みツールがモデルに公開されます。`tools` フィールド自体を省略するか `[]` に設定した場合、モデルはツールスキーマを一切受け取りません（下記 FAQ 参照）。
## 利用可能なツール
| ツール名（enabled\_tools の値） | 用途 | 典型的な使用例 |
| ----------------------- | --------------------------------------------------- | ------------------------------------ |
| `Bash` | Shell コマンド実行 | 依存関係のインストール、スクリプト実行、curl での API 呼び出し |
| `Read` | ファイル読み取り | マウントされたファイルの確認、コード閲覧 |
| `Write` | ファイル書き込み（作成/上書き） | レポート生成、出力ファイルの作成 |
| `Edit` | ファイルの部分編集 | 設定変更、コード編集 |
| `Glob` | Glob パターンでのファイル一覧取得 | コードファイルの検索 |
| `Grep` | ファイル内容の検索 | 文字列の特定 |
| `WebFetch` | HTTP GET で単一ページを取得 | ドキュメント/ページの取得 |
| `WebSearch` | Web 検索 | 情報の検索 |
| `DeliverArtifacts` | Agent が `/data/` 配下で生成したファイルをダウンロード可能な成果物としてユーザーに配信 | ユーザーがファイル/レポート/エクスポートなどの成果物を必要とする場合 |
注意事項：
* ツール名は上表の正確な値を使用してください。イベントストリームでも同じ値が使用されます
* `enabled_tools` を省略するか空配列 `[]` にすると、**すべての組み込みツール**（上表の `DeliverArtifacts` を含む）が有効になります。Agent にツールを一切持たせたくない場合は、`tools` フィールド全体を省略するか `[]` に設定してください
* `enabled_tools` が**空でないホワイトリスト**の場合、リスト外のツールはモデルに一切見えません。カスタムホワイトリストで `DeliverArtifacts` を使用するには、明示的に含める必要があります（例：`["Bash", "Write", "DeliverArtifacts"]`）
* `enabled_tools` 内の各ツール名はバリデーションされます。未知の名前（例：`"Foo"`）を指定すると **400** エラーが返されます：`"unknown tool name 'Foo'"`
* 組み込みツールと MCP ツールの権限は `configs[].permission_policy` で設定します。詳細は[権限ポリシー](/ja/cloud-agents/permission-policies)を参照してください
* ツールごとにオブジェクトを定義する旧スキーマ（`{"type": "bash_20250124"}` など）はサポートされなくなりました
## 現在のフォーマット：単一オブジェクト
組み込みツールの設定は単一オブジェクトで行い、`enabled_tools` 配列で個別のツールを切り替えます：
```json theme={null}
{
"tools": [
{
"type": "agent_toolset_20260401",
"enabled_tools": ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "WebFetch", "WebSearch"]
}
]
}
```
Agent 作成時に設定する場合：
```bash theme={null}
curl -X POST https://api.qoder.com/api/v1/cloud/agents \
-H "Authorization: Bearer $QODER_PAT" \
-H "Content-Type: application/json" \
-d '{
"name": "dev-agent",
"model": "ultimate",
"system": "あなたは開発アシスタントです",
"tools": [
{
"type": "agent_toolset_20260401",
"enabled_tools": ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "WebFetch", "WebSearch"]
}
]
}'
```
## カスタム クライアントサイド ツール
カスタムツールを使用すると、アプリケーション側の機能を Agent に公開できます。Agent はこれらのツールの呼び出しをリクエストできますが、プラットフォームが直接実行することはありません。Agent がカスタムツールを呼び出すと、Session は `requires_action` の stop reason で一時停止し、クライアントがツールを実行した後、`user.custom_tool_result` イベントで結果を返送します。
```json theme={null}
{
"tools": [
{
"type": "agent_toolset_20260401",
"enabled_tools": ["Read", "Write"]
},
{
"type": "custom",
"name": "lookup_order",
"description": "注文 ID で注文を検索します。",
"input_schema": {
"type": "object",
"properties": {
"order_id": {"type": "string"}
},
"required": ["order_id"]
}
}
]
}
```
カスタムツールのルール：
* `name`、`description`、`input_schema` は必須です
* `input_schema` は `"type": "object"` の JSON Schema オブジェクトである必要があります
* 同一 Agent 内のカスタムツール名は大文字小文字を区別せずに一意である必要があります
* カスタムツール名は `Bash` や `Read` などの組み込みツール名と衝突してはなりません
* `mcp__` で始まる名前は MCP ツール用に予約されています
* カスタムツールはクライアントが実行するため、`permission_policy` はサポートされていません
`user.custom_tool_result` の返送フローについては[イベントを送信](/ja/cloud-agents/api/sessions/send-event)を参照してください。
## ツール設定例
### 最小構成（CLI のみ）
```json theme={null}
{
"tools": [
{
"type": "agent_toolset_20260401",
"enabled_tools": ["Bash"]
}
]
}
```
### 完全な開発環境
```json theme={null}
{
"tools": [
{
"type": "agent_toolset_20260401",
"enabled_tools": ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "WebFetch", "WebSearch"]
}
]
}
```
## ツール設定の更新
`POST` を使用して Agent のツール設定を更新します。リクエストには現在の `version` を含める必要があります。`tools` を指定した場合、保存されているツール配列が置き換えられます。
```bash theme={null}
curl -X POST https://api.qoder.com/api/v1/cloud/agents/agent_abc123 \
-H "Authorization: Bearer $QODER_PAT" \
-H "Content-Type: application/json" \
-d '{
"version": 1,
"tools": [
{
"type": "agent_toolset_20260401",
"enabled_tools": ["Bash", "Read", "Write", "Edit"]
}
]
}'
```
Agent の更新では、省略されたフィールドに対して merge セマンティクスが使用されます。`tools`、`mcp_servers`、`skills` などの配列フィールドは、明示的に指定された場合に全体が置き換えられます。楽観的並行制御のために `version` フィールドを含める必要があります：
* 指定した version が現在のバージョンと一致する場合 → 200、version が 1 増加
* 指定した version が古い場合 → 409 `{ error: { type: "conflict_error", message: "Version conflict. Expected version N, got M." }}`
既存の Session には影響しません。新しい Session は更新後の設定を使用します。
## 現在のツール設定を確認
```bash theme={null}
curl https://api.qoder.com/api/v1/cloud/agents/agent_abc123 \
-H "Authorization: Bearer $QODER_PAT" | jq '.tools'
```
出力例：
```json theme={null}
[
{
"type": "agent_toolset_20260401",
"enabled_tools": ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "WebFetch", "WebSearch"]
}
]
```
## よくある質問
**Q：`tools` を設定しないとどうなりますか？** A：Agent はツールを一切使用できず、プレーンテキストの会話のみ可能です。Agent にツール機能を持たせるには、少なくとも `[{"type":"agent_toolset_20260401"}]` を指定してください（すべての組み込みツールが有効になります）。
**Q：Session レベルでツール設定を上書きできますか？** A：現在はサポートされていません。ツール設定は Agent に紐付けられており、同一 Agent のすべての Session が同じツールセットを共有します。
**Q：`tools` 配列の順序は重要ですか？** A：重要ではありません。Agent はタスクのコンテキストに基づいてどのツールを呼び出すかを自主的に判断します。
**Q：バージョンサフィックスは時間とともに変わりますか？** A：はい。API が新しいバージョンのツールをリリースする際に、新しい日付サフィックスが導入されます。Changelog を確認し、最新バージョンを採用することをお勧めします。
## 次のステップ
ツール呼び出しの許可・確認・拒否を制御する。
Agent にドメイン専門知識を付与する。
Agent 設定を確認する。
セッションのライフサイクルを管理する。