メインコンテンツへスキップ
POST /api/v1/cloud/agents/{agent_id} 指定された Agent の設定を更新します。楽観的並行制御（OCC）を使用し、リクエストボディに現在の version 値を含める必要があります。

​
リクエストヘッダー

ヘッダー必須説明
AuthorizationはいBearer <PAT>
Content-Typeはいapplication/json

​
パスパラメーター

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

​
リクエストボディ

フィールド型必須説明
versionintegerはい現在のバージョン番号（OCC 検証用）。サーバー側の現在のバージョンと一致する必要があります
namestringいいえAgent 名、1〜256 文字
modelstring | objectいいえモデル識別子。文字列、または effort や context_window を設定する Agent model オブジェクトを渡します。利用可能な値はモデル一覧で確認できます
systemstringいいえシステムプロンプト、最大 100000 文字
descriptionstringいいえAgent の説明、最大 2048 文字
toolsAgent tool の配列いいえ保存済みのツール設定リストを置換します。最大 128 件
mcp_serversMCP server の配列いいえ保存済みの MCP server リストを置換します。最大 20 件。tools 内の mcp_toolset エントリはこのリスト内の名前を参照する必要があります
skillsSkill binding の配列いいえ保存済みの Skill バインディングリストを置換します。最大 20 件
metadataobjectいいえMetadata パッチ。文字列値はキーの追加または更新に使用し、null 値は保存済み metadata のキーを削除します

​
リクエスト例

curl -X POST "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",
    "system": "You are an updated documentation testing assistant.",
    "description": "Used for API documentation testing",
    "version": 1
  }'

​
レスポンス例

HTTP 200 OK 
{
  "type": "agent",
  "id": "agent_019eXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "name": "doc-test-agent-updated",
  "description": "Used for API documentation testing",
  "model": "ultimate",
  "system": "You are an updated documentation testing assistant.",
  "tools": [],
  "mcp_servers": [],
  "skills": [],
  "metadata": {},
  "multiagent": null,
  "version": 2,
  "archived_at": null,
  "created_at": "2026-05-18T15:26:39.61669Z",
  "updated_at": "2026-05-18T15:27:07.967138Z"
}

​
レスポンスフィールド

フィールド型説明
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更新後の新しいバージョン番号
archived_atstring|nullアーカイブ時刻（ISO 8601）、未アーカイブの場合は null
created_atstring作成時刻（ISO 8601）
updated_atstring最終更新時刻（ISO 8601）

​
楽観的並行制御（OCC）

更新操作はバージョン番号による楽観ロックを使用します：
  1. クライアントはまず GET で Agent の現在の version 値を取得します
  2. 更新時にその version をリクエストボディに含めます
  3. サーバーは version が現在の値と一致するかを検証します
  4. 一致する場合、更新が成功し version が自動的に 1 加算されます
  5. 一致しない場合、サーバーは 409 Conflict を返します
これにより、複数のクライアントが同じ Agent を同時に更新しても、互いの変更を上書きすることが防止されます。

​
エラーコード

HTTPtypeトリガー条件
400invalid_request_errorリクエストボディの形式が不正、またはフィールド値が無効
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 が上限の 20 件を超過
400invalid_request_errorskills が上限の 20 件を超過
401authentication_errorPAT が無効または期限切れ
403permission_errorこの Agent を更新する権限がありません
404not_found_error指定された ID の Agent が存在しません
409conflict_errorversion が不一致、並行競合が発生
エラーエンベロープの詳細はエラーを参照してください。

​
エラーレスポンス例

バージョン競合（409）： 
{
  "type": "error",
  "request_id": "cb80235f-76a2-4ff3-9e28-5aa2da12dc14",
  "error": {
    "type": "conflict_error",
    "message": "Version conflict. Expected version 99, got 1."
  }
}

​
注意事項

  • version フィールドは必須です。省略すると更新が失敗します。
  • 更新が成功するたびに version が自動的にインクリメントされます。
  • 更新は部分更新（マージ）セマンティクスを使用します：リクエストボディに含まれていないオプションフィールドは現在の値を保持し、明示的に指定されたフィールドのみが更新されます。
  • tools、mcp_servers、または skills を明示的に指定した場合、そのフィールドの配列はリクエスト内の配列で完全に置換されます。
  • metadata を明示的に指定した場合、文字列値は保存済み metadata オブジェクトにマージされ、null 値は既存のキーを削除します。
  • バージョン履歴はAgent バージョン一覧で確認できます。

​
関連

Agent の定義

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