エージェントの作成 - - Alibaba Cloud ドキュメントセンター

新しいエージェントの設定を作成します。

重要

新しい Qoder CN ドキュメントサイトが利用可能になりました。このサイトの内容は、最新の製品の機能を反映していない場合があります。最新の製品ドキュメントについては、docs.qoder.cn にアクセスしてください。

POST /api/v1/cloud/agents

新しいエージェントの設定を作成します。

リクエストヘッダー

ヘッダー	必須	説明
`Authorization`	はい	`Bearer <PAT>`
`Content-Type`	はい	`application/json`
`Idempotency-Key`	いいえ	重複作成を防止するためのべき等キー

リクエストボディ

フィールド	タイプ	必須	説明
`name`	string	はい	エージェント名。1～256 文字
`model`	string \| object	はい	モデルの識別子。文字列 (例：`"ultimate"`) を渡すか、エージェントのモデルオブジェクトを渡して `effort` または `context_window` も設定できます。利用可能な値は List models で照会してください。
`system`	string	いいえ	システムプロンプト。最大 100000 文字
`description`	string	いいえ	エージェントの説明。最大 2048 文字
`tools`	エージェントツール配列	いいえ	ツールの設定リスト。最大 128 件
`mcp_servers`	MCP サーバー配列	いいえ	MCP サーバーの設定リスト。最大 20 件。認証は Vault で設定します。
`skills`	スキルバインディング配列	いいえ	スキルバインディングのリスト。最大 20 件
`metadata`	メタデータオブジェクト	いいえ	カスタムメタデータ。省略した場合のデフォルトは `{}` です。
`multiagent`	マルチエージェント	いいえ	マルチエージェントの設定。設定する場合は、`agent_toolset_20260401` ツールも設定する必要があります。

リクエスト例

curl -X POST "https://api.qoder.com.cn/api/v1/cloud/agents" \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "doc-test-agent",
    "model": "ultimate",
    "system": "あなたはドキュメントテスト用のアシスタントです",
    "tools": [
      {
        "type": "agent_toolset_20260401",
        "enabled_tools": ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "WebFetch", "WebSearch"]
      }
    ],
    "mcp_servers": [
      {
        "type": "url",
        "name": "weather-service",
        "url": "https://mcp.example.com/mcp"
      }
    ]
  }'

推論エフォートまたはコンテキストウィンドウを設定するには、model をオブジェクトとして渡します：

curl -X POST "https://api.qoder.com.cn/api/v1/cloud/agents" \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "doc-test-agent-tuned",
    "model": {
      "id": "ultimate",
      "effort": "high",
      "context_window": 400000
    },
    "system": "あなたはドキュメントテスト用のアシスタントです"
  }'

応答例

HTTP 200 OK

{
  "type": "agent",
  "id": "agent_019eXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "name": "doc-test-agent",
  "description": "",
  "model": "ultimate",
  "system": "あなたはドキュメントテスト用のアシスタントです",
  "tools": [
    {
      "type": "agent_toolset_20260401",
      "enabled_tools": ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "WebFetch", "WebSearch"]
    }
  ],
  "mcp_servers": [
    {
      "type": "url",
      "name": "weather-service",
      "url": "https://mcp.example.com/mcp"
    }
  ],
  "skills": [],
  "metadata": {},
  "multiagent": null,
  "version": 1,
  "archived_at": null,
  "created_at": "2026-05-18T15:26:39.61669Z",
  "updated_at": "2026-05-18T15:26:39.61669Z"
}

応答フィールド

フィールド	タイプ	説明
`type`	string	固定値 `"agent"`
`id`	string	一意のエージェント識別子。接頭辞は `"agent_"` です。
`name`	string	エージェント名
`description`	string	エージェントの説明
`model`	string \| object	モデルの識別子。詳細はエージェントのモデルを参照してください。
`system`	string	システムプロンプト
`tools`	エージェントツール配列	ツールの設定リスト
`mcp_servers`	MCP サーバー配列	MCP サーバーの設定リスト
`skills`	スキルバインディング配列	スキルバインディングのリスト
`metadata`	メタデータオブジェクト	カスタムメタデータ
`multiagent`	マルチエージェント \| null	マルチエージェントの設定。未設定の場合は `null` です。
`version`	integer	現在のバージョン番号。1 から開始し、1 ずつ増加します。
`archived_at`	string \| null	アーカイブのタイムスタンプ (ISO 8601)。アーカイブされていない場合は `null` です。
`created_at`	string	作成タイムスタンプ (ISO 8601)
`updated_at`	string	最終更新タイムスタンプ (ISO 8601)

エラー

HTTP	type	条件
400	`invalid_request_error`	必須フィールド `name` がありません。
400	`invalid_request_error`	`name` が文字列ではありません。エラーメッセージは `Field 'name' must be a string.` です。
400	`invalid_request_error`	`name` が 1～256 文字の範囲外です。
400	`invalid_request_error`	必須フィールド `model` がありません。
400	`invalid_request_error`	`model.effort` が `none`、`low`、`medium`、`high`、`xhigh`、`max` のいずれでもありません。
400	`invalid_request_error`	`model.context_window` が正の整数ではありません。
400	`invalid_request_error`	`model.speed` が指定されました。代わりに `model.effort` を使用してください。
400	`invalid_request_error`	`tools` が 128 件の上限を超えています。
400	`invalid_request_error`	`mcp_servers` または `skills` の設定形式が無効です。
400	`invalid_request_error`	`skills` が 20 件の上限を超えています。
400	`invalid_request_error`	`multiagent.type` が `"coordinator"` ではありません。
400	`invalid_request_error`	`multiagent.agents` が空であるか、20 件の上限を超えています。
400	`invalid_request_error`	`multiagent` が設定されていますが、`tools` に `agent_toolset_20260401` が含まれていません。
400	`invalid_request_error`	`multiagent.agents` で参照されているエージェント ID が存在しません。
401	`authentication_error`	PAT が無効であるか、有効期限が切れています。
403	`permission_error`	この操作を実行する権限が不足しています。

エラー応答の例

{
  "type": "error",
  "request_id": "cb80235f-76a2-4ff3-9e28-5aa2da12dc14",
  "error": {
    "type": "invalid_request_error",
    "message": "name must be between 1 and 256 characters"
  }
}

エラーエンベロープ仕様の詳細については、「Errors」をご参照ください。