> ## 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 サーバー、Skill バインディングの構造。
## Agent オブジェクト
作成、一覧取得、更新、アーカイブ、および `version` パラメータなしの `GET /api/v1/cloud/agents/{agent_id}` で返される構造です。
| フィールド | 型 | 説明 |
| ------------- | ----------------------------------- | -------------------------------------------------------------------------------------------------- |
| `id` | string | Agent ID。プレフィックスは `agent_` |
| `type` | string | 固定値 `"agent"` |
| `name` | string | Agent 名。1〜256 文字 |
| `description` | string | Agent の説明。最大 2048 文字 |
| `model` | string \| object | モデル識別子。model ID の文字列、または `effort` と `context_window` も設定する [Agent model](#agent-model) オブジェクトを渡します |
| `system` | string | システムプロンプト。最大 100000 文字 |
| `tools` | [Agent tool](#agent-tool) の配列 | ツール設定リスト。最大 128 件。デフォルトは `[]` |
| `mcp_servers` | [MCP server](#mcp-server) の配列 | MCP サーバーリスト。最大 20 件。デフォルトは `[]` |
| `skills` | [Skill binding](#skill-binding) の配列 | Skill バインディング。最大 20 件。デフォルトは `[]` |
| `metadata` | object | [Metadata オブジェクト](/ja/cloud-agents/api/conventions/schemas#metadata-object)。デフォルトは `{}` |
| `multiagent` | [Multiagent](#multiagent) \| null | Agents 設定。未設定時は `null` を返す |
| `version` | integer | 現在の Agent バージョン。`1` から開始 |
| `archived_at` | string \| null | UTC アーカイブ日時。未アーカイブ時は `null` |
| `created_at` | string | UTC 作成日時 |
| `updated_at` | string | UTC 最終更新日時 |
## Agent version snapshot
`version` パラメータ付きの `GET /api/v1/cloud/agents/{agent_id}` および `GET /api/v1/cloud/agents/{agent_id}/versions` で返される構造です。
| フィールド | 型 | 説明 |
| ------------- | ----------------------------------- | --------------------------------------------------------------------------- |
| `id` | string | Agent ID。プレフィックスは `agent_` |
| `type` | string | 固定値 `"agent"` |
| `name` | string | Agent 名 |
| `description` | string | Agent の説明 |
| `model` | string \| object | モデル識別子。[Agent object](#agent-object) と同じ形式。[Agent model](#agent-model) を参照 |
| `system` | string | システムプロンプト |
| `tools` | [Agent tool](#agent-tool) の配列 | ツール設定リスト |
| `mcp_servers` | [MCP server](#mcp-server) の配列 | MCP サーバーリスト |
| `skills` | [Skill binding](#skill-binding) の配列 | Skill バインディング |
| `metadata` | object | [Metadata オブジェクト](/ja/cloud-agents/api/conventions/schemas#metadata-object) |
| `multiagent` | [Multiagent](#multiagent) \| null | Agents 設定 |
| `version` | integer | このスナップショットのバージョン番号 |
| `archived_at` | string \| null | UTC アーカイブ日時。このスナップショットが未アーカイブの場合は `null` |
| `created_at` | string | Agent の UTC 作成日時 |
| `updated_at` | string | このスナップショットの UTC 最終更新日時 |
## Agent model
Agent の `model` フィールドは、等価な 2 つの形式を受け付けます:
* **文字列(簡易形式)**: モデル ID。例: `"ultimate"`。
* **オブジェクト形式**: `id` と任意のチューニングフィールドを持つオブジェクト。
| フィールド | 型 | 必須 | 説明 |
| ---------------- | ------- | --- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | string | はい | モデル識別子。利用可能な値は [モデル一覧](/ja/cloud-agents/api/models/list) で確認できます |
| `effort` | string | いいえ | 推論の effort レベル。有効な値: `none`、`low`、`medium`、`high`、`xhigh`、`max`。モデルが提示するレベルは [モデル一覧](/ja/cloud-agents/api/models/list) の `efforts` 配列を参照 |
| `context_window` | integer | いいえ | 希望するコンテキストウィンドウ(トークン数、正の整数)。[モデル一覧](/ja/cloud-agents/api/models/list) の `available_context_windows` から選択 |
レスポンスは送信された形式をそのまま返します: 文字列リクエストは `model` を文字列で、オブジェクトリクエストはチューニングフィールドを保持したオブジェクトで返します。バージョンスナップショット(`GET /api/v1/cloud/agents/{agent_id}?version=N`)も同じ形式を返します。
Session レスポンスでは Agent が埋め込まれ、`agent.model` 内に読み取り専用の `effective_context_window` が追加されます。[Session スキーマ](/ja/cloud-agents/api/sessions/schemas) を参照してください。
## Agent tool
`tools[]` は `type` によって異なる構造を持つ union 型です。
| フィールド | 型 | 適用タイプ | 説明 |
| ------------------ | ------------------------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `type` | string | すべて | 必須。有効な値：`agent_toolset_20260401`、`mcp_toolset`、`custom` |
| `enabled_tools` | string の配列 | `agent_toolset_20260401` | 組み込みツールの許可リスト。空でない配列を指定すると厳密な許可リストとして機能します。省略または `[]` を渡すとデフォルトの組み込みツールセットが使用され、`disallowed_tools` と `configs[].enabled` が引き続き適用されます。値には以下の組み込みツール名を使用してください |
| `disallowed_tools` | string の配列 | `agent_toolset_20260401` | 非表示かつ拒否する組み込みツール。値には以下の組み込みツール名を使用してください。同一ツールを `enabled_tools` と `disallowed_tools` の両方に指定することはできません |
| `configs` | [Tool config](#tool-config) の配列 | `agent_toolset_20260401`、`mcp_toolset` | ツールごとの有効化状態と権限ルール。ツール単位の権限はここで `permission_policy` を通じて設定します |
| `mcp_server_name` | string | `mcp_toolset` | 必須。`mcp_servers[].name` のいずれかと一致する必要があります |
| `name` | string | `custom` | 必須のカスタムツール名。組み込みツール名と重複してはならず、`mcp__` で始めることもできません |
| `description` | string | `custom` | 必須のカスタムツールの説明 |
| `input_schema` | object | `custom` | 必須の JSON Schema オブジェクト。`input_schema.type` は `"object"` でなければなりません |
`custom` ツールは `permission_policy` をサポートしていません。権限は `agent_toolset_20260401` または `mcp_toolset` の `configs[].permission_policy` で設定してください。
## 組み込みツール名
以下の組み込みツール名を使用できます：
| ツール名 |
| ------------------ |
| `Bash` |
| `DeliverArtifacts` |
| `Edit` |
| `Glob` |
| `Grep` |
| `ImageGen` |
| `ImageSearch` |
| `Read` |
| `WebFetch` |
| `WebSearch` |
| `Write` |
## Tool config
`tools[].configs[]` で使用します。
| フィールド | 型 | 必須 | 説明 |
| ------------------- | --------------------------------------- | --- | --------------------------------------------------------------------------------------------- |
| `name` | string | はい | 設定対象のツール名。`agent_toolset_20260401` の場合は組み込みツール名を、`mcp_toolset` の場合はその MCP サーバーが公開するツール名を使用します |
| `enabled` | boolean | いいえ | `false` はそのツールを非表示にし拒否します。`true` はそのツールを明示的に有効化します |
| `permission_policy` | [Permission policy](#permission-policy) | いいえ | そのツールの実行時権限動作 |
## Permission policy
| フィールド | 型 | 必須 | 説明 |
| ------ | ------ | -- | ---------------------------------------------- |
| `type` | string | はい | 有効な値：`always_allow`、`always_ask`、`always_deny` |
`always_allow` は一時停止なしで実行します。`always_ask` は `user.tool_confirmation` イベントを待って一時停止します。`always_deny` は拒否されたツール結果を返します。
## MCP server
`mcp_servers[]` で使用します。
| フィールド | 型 | 必須 | 説明 |
| ------ | ------ | -- | ------------------------------- |
| `name` | string | はい | この Agent 内で一意の MCP サーバー名 |
| `type` | string | はい | サポートされる値：`"url"` |
| `url` | string | はい | Streamable HTTP MCP エンドポイント URL |
MCP サーバーの認証は [Vault](/ja/cloud-agents/vaults) で設定します。
## Skill binding
`skills[]` で使用します。
| フィールド | 型 | 必須 | 説明 |
| ---------- | ------ | --- | --------------------- |
| `type` | string | はい | 有効な値：`qoder`、`custom` |
| `skill_id` | string | はい | Skill 識別子 |
| `version` | string | いいえ | 省略可能な空でないバージョン文字列 |
## Multiagent
Agent の `multiagent` フィールドで使用し、Agents 機能を設定します。設定すると、実行時に coordinator 制御ツール（`create_agent`、`send_to_agent`、`list_agents`、`Agent`）が自動的に注入されます。
`multiagent` を使用する場合、`tools` 配列に `agent_toolset_20260401` タイプのエントリを含める必要があります。
| フィールド | 型 | 必須 | 説明 |
| -------- | ----------------------------------------------------- | -- | ------------------------------- |
| `type` | string | はい | `"coordinator"` でなければなりません |
| `agents` | [Multiagent agent entry](#multiagent-agent-entry) の配列 | はい | 委譲可能な Agent のリスト。1〜20 件の一意なエントリ |
### Multiagent agent entry
`multiagent.agents[]` は 3 つの形式をサポートしています：
**オブジェクト形式**：
| フィールド | 型 | 必須 | 説明 |
| --------- | ------- | ------ | ----------------------------------------------------------- |
| `type` | string | はい | `"agent"` は他の Agent を参照。`"self"` は coordinator 自身を参照 |
| `id` | string | 条件付き必須 | Agent ID。`type` が `"agent"` の場合に必須 |
| `version` | integer | いいえ | 特定の Agent バージョンを指定。省略時は最新のアクティブバージョンを使用。正の整数または正の整数文字列をサポート |
| `name` | string | いいえ | 子 Agent の表示名 |
**文字列省略形式**：Agent ID 文字列を直接渡します。`{"type": "agent", "id": ""}` と同等です。
例：
```json theme={null}
{
"type": "coordinator",
"agents": [
{"type": "agent", "id": "agent_019f00000001", "name": "Research Agent"},
{"type": "agent", "id": "agent_019f00000002", "version": 3},
{"type": "self"},
"agent_019f00000003"
]
}
```
## 関連
再利用可能でバージョン管理された Agent 構成を作成する。