> ## Documentation Index > Fetch the complete documentation index at: https://docs.qoder.com/llms.txt > Use this file to discover all available pages before exploring further. # Agent の更新 > 指定された Agent の設定を更新します。楽観的並行制御（OCC）を使用します。 `POST /api/v1/cloud/agents/{agent_id}` 指定された Agent の設定を更新します。楽観的並行制御（OCC）を使用し、リクエストボディに現在の `version` 値を含める必要があります。 ## リクエストヘッダー | ヘッダー | 必須 | 説明 | | --------------- | -- | ------------------ | | `Authorization` | はい | `Bearer ` | | `Content-Type` | はい | `application/json` | ## パスパラメーター | パラメーター | 型 | 必須 | 説明 | | ---------- | ------ | -- | ------------ | | `agent_id` | string | はい | Agent の一意識別子 | ## リクエストボディ | フィールド | 型 | 必須 | 説明 | | ------------- | ---------------------------------------------------------------------- | --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `version` | integer | はい | 現在のバージョン番号（OCC 検証用）。サーバー側の現在のバージョンと一致する必要があります | | `name` | string | いいえ | Agent 名、1〜256 文字 | | `model` | string \| object | いいえ | モデル識別子。文字列、または `effort` や `context_window` を設定する [Agent model](/ja/cloud-agents/api/agents/schemas#agent-model) オブジェクトを渡します。利用可能な値は[モデル一覧](/ja/cloud-agents/api/models/list)で確認できます | | `system` | string | いいえ | システムプロンプト、最大 100000 文字 | | `description` | string | いいえ | Agent の説明、最大 2048 文字 | | `tools` | [Agent tool](/ja/cloud-agents/api/agents/schemas#agent-tool) の配列 | いいえ | 保存済みのツール設定リストを置換します。最大 128 件 | | `mcp_servers` | [MCP server](/ja/cloud-agents/api/agents/schemas#mcp-server) の配列 | いいえ | 保存済みの MCP server リストを置換します。最大 20 件。`tools` 内の `mcp_toolset` エントリはこのリスト内の名前を参照する必要があります | | `skills` | [Skill binding](/ja/cloud-agents/api/agents/schemas#skill-binding) の配列 | いいえ | 保存済みの Skill バインディングリストを置換します。最大 20 件 | | `metadata` | object | いいえ | Metadata パッチ。文字列値はキーの追加または更新に使用し、`null` 値は保存済み metadata のキーを削除します | ## リクエスト例 ```bash theme={null} 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** ```json theme={null} { "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" } ``` ## レスポンスフィールド | フィールド | 型 | 説明 | | ------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------- | | `type` | string | 固定値 `"agent"` | | `id` | string | Agent の一意識別子、プレフィックスは `agent_` | | `name` | string | Agent 名 | | `description` | string | Agent の説明 | | `model` | string \| object | モデル識別子。[Agent model](/ja/cloud-agents/api/agents/schemas#agent-model) を参照 | | `system` | string | システムプロンプト | | `tools` | [Agent tool](/ja/cloud-agents/api/agents/schemas#agent-tool) の配列 | ツール設定リスト | | `mcp_servers` | [MCP server](/ja/cloud-agents/api/agents/schemas#mcp-server) の配列 | MCP サーバー設定 | | `skills` | [Skill binding](/ja/cloud-agents/api/agents/schemas#skill-binding) の配列 | Skill バインディングリスト | | `metadata` | [Metadata オブジェクト](/ja/cloud-agents/api/conventions/schemas#metadata-object) | カスタムメタデータ | | `multiagent` | [Multiagent](/ja/cloud-agents/api/agents/schemas#multiagent) \| null | Agents 設定、未設定の場合は `null` | | `version` | integer | 更新後の新しいバージョン番号 | | `archived_at` | string\|null | アーカイブ時刻（ISO 8601）、未アーカイブの場合は `null` | | `created_at` | string | 作成時刻（ISO 8601） | | `updated_at` | string | 最終更新時刻（ISO 8601） | ## 楽観的並行制御（OCC） 更新操作はバージョン番号による楽観ロックを使用します： 1. クライアントはまず GET で Agent の現在の `version` 値を取得します 2. 更新時にその `version` をリクエストボディに含めます 3. サーバーは `version` が現在の値と一致するかを検証します 4. 一致する場合、更新が成功し `version` が自動的に 1 加算されます 5. 一致しない場合、サーバーは 409 Conflict を返します これにより、複数のクライアントが同じ Agent を同時に更新しても、互いの変更を上書きすることが防止されます。 ## エラーコード | HTTP | type | トリガー条件 | | ---- | ----------------------- | -------------------------------------------------------------------- | | 400 | `invalid_request_error` | リクエストボディの形式が不正、またはフィールド値が無効 | | 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` が上限の 20 件を超過 | | 400 | `invalid_request_error` | `skills` が上限の 20 件を超過 | | 401 | `authentication_error` | PAT が無効または期限切れ | | 403 | `permission_error` | この Agent を更新する権限がありません | | 404 | `not_found_error` | 指定された ID の Agent が存在しません | | 409 | `conflict_error` | `version` が不一致、並行競合が発生 | エラーエンベロープの詳細は[エラー](/ja/cloud-agents/api/conventions/errors)を参照してください。 ### エラーレスポンス例 **バージョン競合（409）：** ```json theme={null} { "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 バージョン一覧](/ja/cloud-agents/api/agents/list-versions)で確認できます。 ## 関連 再利用可能でバージョン管理された Agent 構成を作成する。