メインコンテンツへスキップ
POST /api/v1/cloud/agents 新しい Agent 設定を作成します。

​
リクエストヘッダー

ヘッダー必須説明
AuthorizationはいBearer <PAT>
Content-Typeはいapplication/json
Idempotency-Keyいいえ冪等キー。重複作成を防止します

​
リクエストボディ

フィールド型必須説明
namestringはいAgent 名。1〜256 文字
modelstring | objectはいモデル識別子。"ultimate" のような文字列、または model ID と併せて effort や context_window を設定する Agent model オブジェクトを渡します。利用可能な値は モデル一覧 で確認できます
systemstringいいえシステムプロンプト。最大 100000 文字
descriptionstringいいえAgent の説明。最大 2048 文字
toolsAgent tool の配列いいえツール設定リスト。最大 128 件
mcp_serversMCP server の配列いいえMCP サーバー設定リスト。最大 20 件。認証は Vault で設定します
skillsSkill binding の配列いいえSkill バインディングリスト。最大 20 件
metadataMetadata オブジェクトいいえカスタムメタデータ。省略時は {}
multiagentMultiagentいいえAgents 設定。設定する場合は agent_toolset_20260401 ツールエントリも必要です

​
リクエスト例

curl -X POST "https://api.qoder.com/api/v1/cloud/agents" \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "doc-test-agent",
    "model": "ultimate",
    "system": "You are a documentation testing assistant.",
    "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"
      }
    ]
  }'
推論の effort やコンテキストウィンドウを設定するには、model をオブジェクトとして渡します: 
curl -X POST "https://api.qoder.com/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": "You are a documentation testing assistant."
  }'

​
レスポンス例

HTTP 200 OK 
{
  "type": "agent",
  "id": "agent_019eXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "name": "doc-test-agent",
  "description": "",
  "model": "ultimate",
  "system": "You are a documentation testing assistant.",
  "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"
}

​
レスポンスフィールド

フィールド型説明
typestring固定値 "agent"
idstringAgent の一意識別子。プレフィックスは "agent_"
namestringAgent 名
descriptionstringAgent の説明
modelstring | objectモデル識別子。Agent model を参照
systemstringシステムプロンプト
toolsAgent tool の配列ツール設定リスト
mcp_serversMCP server の配列MCP サーバー設定
skillsSkill binding の配列Skill バインディングリスト
metadataMetadata オブジェクトカスタムメタデータ
multiagentMultiagent | nullAgents 設定。未設定時は null
versioninteger現在のバージョン番号。1 から開始
archived_atstring|nullアーカイブ日時（ISO 8601）。未アーカイブ時は null
created_atstring作成日時（ISO 8601）
updated_atstring最終更新日時（ISO 8601）

​
エラー

HTTPtype発生条件
400invalid_request_error必須フィールド name が未指定
400invalid_request_errorname が 256 文字を超過
400invalid_request_error必須フィールド model が未指定
400invalid_request_errormodel.effort が none、low、medium、high、xhigh、max のいずれでもない
400invalid_request_errormodel.context_window が正の整数でない
400invalid_request_errormodel.speed が指定された。代わりに model.effort を使用する
400invalid_request_errortools が上限の 128 件を超過
400invalid_request_errormcp_servers または skills の設定形式が不正
400invalid_request_errorskills が上限の 20 件を超過
400invalid_request_errormultiagent.type が "coordinator" ではない
400invalid_request_errormultiagent.agents が空、または上限の 20 件を超過
400invalid_request_errormultiagent が設定されているが tools に agent_toolset_20260401 エントリがない
400invalid_request_errormultiagent.agents で参照された Agent ID が存在しない
401authentication_errorPAT が無効または期限切れ
403permission_errorこの操作を実行する権限がありません
エラーレスポンスの完全なエンベロープについては エラー を参照してください。

​
エラーレスポンス例

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

​
関連

Agent の定義

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