Agent スキーマ

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 オブジェクトを渡します
`system`	string	システムプロンプト。最大 100000 文字
`tools`	Agent tool の配列	ツール設定リスト。最大 128 件。デフォルトは `[]`
`mcp_servers`	MCP server の配列	MCP サーバーリスト。最大 20 件。デフォルトは `[]`
`skills`	Skill binding の配列	Skill バインディング。最大 20 件。デフォルトは `[]`
`metadata`	object	Metadata オブジェクト。デフォルトは `{}`
`multiagent`	Multiagent \| null	Multiagent オーケストレーション設定。未設定時は `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 model を参照
`system`	string	システムプロンプト
`tools`	Agent tool の配列	ツール設定リスト
`mcp_servers`	MCP server の配列	MCP サーバーリスト
`skills`	Skill binding の配列	Skill バインディング
`metadata`	object	Metadata オブジェクト
`multiagent`	Multiagent \| null	Multiagent オーケストレーション設定
`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	はい	モデル識別子。利用可能な値はモデル一覧で確認できます
`effort`	string	いいえ	推論の effort レベル。有効な値: `none`、`low`、`medium`、`high`、`xhigh`、`max`。モデルが提示するレベルはモデル一覧の `efforts` 配列を参照
`context_window`	integer	いいえ	希望するコンテキストウィンドウ(トークン数、正の整数)。モデル一覧の `available_context_windows` から選択

レスポンスは送信された形式をそのまま返します: 文字列リクエストは model を文字列で、オブジェクトリクエストはチューニングフィールドを保持したオブジェクトで返します。バージョンスナップショット(GET /api/v1/cloud/agents/{agent_id}?version=N)も同じ形式を返します。 Session レスポンスでは Agent が埋め込まれ、agent.model 内に読み取り専用の effective_context_window が追加されます。Session スキーマを参照してください。

Agent tool

tools[] は type によって異なる構造を持つ union 型です。

フィールド	型	適用タイプ	説明
`type`	string	すべて	必須。有効な値：`agent_toolset_20260401`、`browser_toolset_20260714`、`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 の配列	`agent_toolset_20260401`、`mcp_toolset`	ツールごとの有効化状態と権限ルール。ツール単位の権限はここで `permission_policy` を通じて設定します
`mcp_server_name`	string	`mcp_toolset`	必須。`mcp_servers[].name` のいずれかと一致する必要があります
`name`	string	`custom`	必須のカスタムツール名。組み込みツール名と重複してはならず、`mcp__` で始めることもできません。`advisor`（大文字と小文字を区別しない）も使用できません
`description`	string	`custom`	必須のカスタムツールの説明
`input_schema`	object	`custom`	必須の JSON Schema オブジェクト。`input_schema.type` は `"object"` でなければなりません

custom ツールは permission_policy をサポートしていません。権限は agent_toolset_20260401 または mcp_toolset の configs[].permission_policy で設定してください。

Browser Use Beta ツールセット

Browser Use は現在 Beta 機能であり、機能と API は継続的に改善されます。ステータスの説明と有効化の完全な例は Browser Use（Beta）を参照してください。 Agent で Browser Use を有効にするには、作成時または更新時に：

リクエストヘッダーに x-qoder-beta: browser-use-2026-07-14 を追加します。
リクエストボディの tools 配列に以下を追加します：

{
  "type": "browser_toolset_20260714"
}

この設定により、Agent のすべての browser_* ツールと Session ライブプレビューが有効になります。type フィールドのみを受け付け、enabled_tools による個別の Browser ツールの選択はサポートされません。 Agent の更新時に tools を指定すると、既存のツール設定が上書きされます。保持するツールも一緒に指定してください。

組み込みツール名

以下の組み込みツール名を使用できます：

ツール名
`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

フィールド	型	必須	説明
`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 で設定します。

Skill binding

skills[] で使用します。

フィールド	型	必須	説明
`type`	string	はい	有効な値：`qoder`、`custom`
`skill_id`	string	はい	Skill 識別子
`version`	string	いいえ	省略可能な空でないバージョン文字列

Multiagent

Agent の multiagent フィールドで、Coordinator が委譲できる Agent リストと任意の Advisor を設定します。完全なワークフローは Multiagent オーケストレーションを参照してください。

通常の Agent または self を含む場合は tools に agent_toolset_20260401 が必要です。Advisor のみのロスターでは不要です。

フィールド	型	必須	説明
`type`	string	はい	`"coordinator"` でなければなりません
`agents`	Multiagent agent entry の配列	はい	空でないロスター。最大 20 件の一意な通常の Agent エントリと 1 件の Advisor

Multiagent agent entry

multiagent.agents[] は Agent オブジェクト、Self オブジェクト、文字列省略形式、Advisor オブジェクトをサポートします： オブジェクト形式：

フィールド	型	必須	説明
`type`	string	はい	`"agent"` は他の Agent を参照。`"self"` は coordinator 自身を参照
`id`	string	条件付き必須	Agent ID。`type` が `"agent"` の場合に必須
`version`	integer \| string	いいえ	`type: "agent"` に適用。以下の規則を参照

type: "agent" のバージョン規則：

`version`	Agent が保存・返却する値	新しい Session
省略	保存時の最新の数値バージョン	保存済みのバージョンを使用
`"latest"`	文字列 `"latest"`	作成時の最新の数値バージョンを解決して保存
`3`	整数 `3`	v3 を使用

"3" などの正の整数文字列も指定でき、保存後は整数で返されます。null、0、空文字列は無効です。 "latest" は子 Agent のバージョン選択にのみ使用します。Agent 自身のバージョン番号（トップレベルの version）は整数のままです。

Session 作成時に "latest" は具体的なバージョン番号に置き換わり、その Session で後から作成する子 Thread も同じバージョンを使用します。
Coordinator の子 Agent 参照を変更しても、Coordinator の過去のバージョンや既存の Session は変わりません。
保存済みの固定バージョンが自動的に "latest" になることはありません。参照を明示的に変更してください。

agent エントリの表示名は参照先 Agent の name、self は Coordinator の名前を使用します。指定した name フィールドは受け付けられますが無視され、表示名は大文字と小文字を区別せず一意である必要があります。 qoder.advisor は予約済みのロスター名であり、大文字と小文字の違いにかかわらず、通常の Agent や self には使用できません。通常の名前 advisor は使用できますが、Advisor としては動作しません。 文字列省略形式：Agent ID 文字列を直接渡します。{"type": "agent", "id": "<value>"} と同等です。 Advisor オブジェクト：

フィールド	型	必須	説明
`type`	string	はい	`"advisor"` 固定
`model`	string	はい	モデル一覧にある空でない有効なモデル名。モデルオブジェクトは使用できません

Advisor エントリには type と model のみ指定できます。単独でも通常のエントリと組み合わせても設定できます。Advisor の設定を参照してください。例：

{
  "type": "coordinator",
  "agents": [
    {"type": "agent", "id": "agent_019f00000001", "version": "latest", "name": "Research Agent"},
    {"type": "agent", "id": "agent_019f00000002", "version": 3},
    {"type": "self"},
    "agent_019f00000003",
    {"type": "advisor", "model": "ultimate"}
  ]
}

Agent の定義

再利用可能でバージョン管理された Agent 構成を作成する。

​Agent オブジェクト

​Agent version snapshot

​Agent model

​Agent tool

​Browser Use Beta ツールセット

​組み込みツール名

​Tool config

​Permission policy

​MCP server

​Skill binding

​Multiagent

​Multiagent agent entry

​関連

Agent の定義

Agent オブジェクト

Agent version snapshot

Agent model

Agent tool

Browser Use Beta ツールセット

組み込みツール名

Tool config

Permission policy

MCP server

Skill binding

Multiagent

Multiagent agent entry

関連