Agent の更新

PUT /v1/agents/{agent_id} 指定された Agent の設定を更新します。楽観的並行制御（OCC）を使用するため、リクエストボディに現在の version 値を提供する必要があります。

ヘッダー

ヘッダー	必須	説明
Authorization	はい	`Bearer <PAT>`
Content-Type	はい	`application/json`
X-CAS-Include-Extended	いいえ	`true` に設定するとレスポンスに拡張フィールド（`skills`、`metadata`）が含まれます

パスパラメータ

パラメータ	型	必須	説明
`agent_id`	string	はい	Agent の一意識別子

リクエストボディ

フィールド	型	必須	説明
`version`	integer	はい	現在のバージョン番号（OCC 検証）。サーバー側の現在のバージョンと一致する必要がある
`name`	string	いいえ	Agent 名、1-256 文字
`model`	string / object	いいえ	モデル識別子
`instructions`	string	いいえ	システムプロンプト
`description`	string	いいえ	Agent の説明
`tools`	array	いいえ	ツール設定リスト
`mcp_servers`	array	いいえ	MCP サーバー設定リスト
`skills`	array	いいえ	Skill バインドリスト。形式: `[{"type":"custom","skill_id":"<skill_id>"}]`、最大 20 件
`metadata`	object	いいえ	カスタムメタデータのキーバリュー
`default_environment`	string	いいえ	デフォルトの実行環境

リクエスト例

curl -X PUT "https://api.qoder.com/api/v1/cloud/agents/agent_019eXXXX..." \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "doc-test-agent-updated",
    "model": "ultimate",
    "instructions": "あなたは更新後のドキュメントテストアシスタントです",
    "description": "API ドキュメントテスト用",
    "version": 1
  }'

レスポンス例

HTTP 200 OK

{
  "type": "agent",
  "id": "agent_019eXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "name": "doc-test-agent-updated",
  "description": "API ドキュメントテスト用",
  "model": "ultimate",
  "system": "あなたは更新後のドキュメントテストアシスタントです",
  "instructions": "あなたは更新後のドキュメントテストアシスタントです",
  "tools": [],
  "mcp_servers": [],
  "default_environment": "",
  "version": 2,
  "archived": false,
  "archived_at": null,
  "created_at": "2026-05-18T15:26:39.61669Z",
  "updated_at": "2026-05-18T15:27:07.967138Z"
}

楽観的並行制御（OCC）

更新操作は、バージョン番号を使った楽観ロック検証を行います。

クライアントはまず GET で Agent の現在の version 値を取得します。
更新時、その version をリクエストボディに含めます。
サーバーは version が現在の値と一致するか検証します。
一致すれば更新成功、version は自動的に +1 されます。
一致しなければ 409 Conflict が返されます。

これにより、複数のクライアントが同じ Agent を並行して変更したときに、互いに上書きしないことが保証されます。

エラーコード

HTTP	type	トリガー条件
400	`invalid_request_error`	リクエストボディの形式エラーまたはフィールド値が不正
400	`invalid_request_error`	`skills` が上限の 20 件を超過
401	`authentication_error`	PAT が無効または期限切れ
403	`permission_error`	この Agent を更新する権限がない
404	`not_found_error`	指定 ID の Agent が存在しない
409	`conflict_error`	`version` が一致せず、並行競合が発生

エラーレスポンス例

バージョン競合（409）:

{
  "type": "error",
  "error": {
    "type": "conflict_error",
    "message": "Version conflict. Expected version 99, got 1."
  }
}

注意事項

version フィールドは必須です。渡さないと更新は失敗します。
更新成功ごとに version は自動的にインクリメントされます。
更新はマージセマンティクスです。リクエストボディに含まれないオプションフィールドは現在の値が維持されます。明示的に指定されたフィールドのみが更新されます。
GET /v1/agents/{agent_id}/versions で履歴バージョンを参照できます。

​ヘッダー

​パスパラメータ

​リクエストボディ

​リクエスト例

​レスポンス例

​楽観的並行制御（OCC）

​エラーコード

​エラーレスポンス例

​注意事項