> ## 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 構成を作成します。 Agent は Qoder Cloud Agents のコア構成テンプレートであり、AI エージェントの能力範囲を定義します — モデル、振る舞い、使用可能なツール。1 つの Agent を複数の Session で再利用でき、Agent を更新しても実行中の Session には影響しません。 ## コア要素 Agent は「職務記述書」のようなものです： | 要素 | 役割 | | ------------- | ------------------- | | **モデル** | Agent の推論能力 | | **システムプロンプト** | Agent の振る舞いとルール | | **ツール** | Agent が実行できる操作 | | **Skills** | Agent が呼び出せる高レベルスキル | Agent 自体はタスクを実行しません — 構成情報にすぎません。実際の処理は Agent にバインドされた Session 内で行われます。 ## フィールドリファレンス | フィールド | 型 | 必須 | 説明 | | ------------- | ------------ | --- | --------------------------------------- | | `id` | string | — | システム生成、`agent_` プレフィックス + 32 文字の小文字16進数 | | `type` | string | — | 固定値 `"agent"` | | `name` | string | はい | Agent 名。英小文字のケバブケース推奨（64 文字以内） | | `description` | string | いいえ | 説明文。デフォルト `""` | | `model` | string | はい | モデル識別子。詳細は下記参照 | | `system` | string | いいえ | システムプロンプト。デフォルト `""` | | `tools` | array | いいえ | 使用可能なツールのリスト。詳細は下記参照 | | `skills` | array | いいえ | 関連する Skill ID のリスト | | `mcp_servers` | array | いいえ | MCP サーバー設定のリスト。デフォルト `[]` | | `multiagent` | object\|null | いいえ | Agents 設定。未設定時は `null` を返す | | `metadata` | object | いいえ | タグ付けやフィルタリング用のカスタムキー/値ペア | | `version` | integer | — | バージョン番号。1 から開始 | | `archived_at` | string\|null | — | アーカイブ日時（ISO 8601）。未アーカイブ時は `null` | | `created_at` | string | — | 作成日時（ISO 8601） | | `updated_at` | string | — | 最終更新日時 | ### model `model` は Agent が使用するモデルの識別子です。[モデル一覧](/ja/cloud-agents/api/models/list) を呼び出して現在のアカウントで利用可能な値を確認し、Agent の作成・更新時にモデルの `id` を指定してください。 ### tools `tools` はツールオブジェクトの配列です。組み込みツールは `agent_toolset_20260401` を通じて設定し、`enabled_tools` 配列で個々のツールを選択的に有効化します： ```json theme={null} { "tools": [ { "type": "agent_toolset_20260401", "enabled_tools": ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "WebFetch", "WebSearch"] } ] } ``` 利用可能な `enabled_tools` の値： | ツール名 | 説明 | | ------------------ | ---------------------------- | | `Bash` | シェルコマンドの実行 | | `Read` | ファイル内容の読み取り | | `Write` | ファイルの作成または上書き | | `Edit` | ファイルの部分編集 | | `Glob` | グロブパターンによるファイル一覧 | | `Grep` | ファイル内容の検索 | | `WebFetch` | 単一ページの HTTP GET | | `WebSearch` | Web 検索 | | `DeliverArtifacts` | `/data/` 配下で生成したファイルをユーザーに配信 | カスタムのクライアントサイドツールと権限ポリシーについては [Agent ツール設定](/ja/cloud-agents/tools) を参照してください。 ## Agent の管理 完全な CRUD インターフェースは [API リファレンス / Agents](/ja/cloud-agents/api/agents/create) を参照してください。以下は一般的なワークフローの例です。 ### 作成 ```bash theme={null} curl -s -X POST https://api.qoder.com/api/v1/cloud/agents \ -H "Authorization: Bearer $QODER_PAT" \ -H "Content-Type: application/json" \ -d '{ "name": "code-reviewer", "model": "ultimate", "system": "あなたはコードレビューの専門家です。コードを1行ずつレビューし、問題点と改善提案を Markdown 形式で出力してください。", "tools": [ { "type": "agent_toolset_20260401", "enabled_tools": ["Bash", "Read", "Write"] } ], "metadata": { "team": "backend", "purpose": "code-review" } }' | jq . ``` 成功時は **200 OK** が返され、`version` は `1` から始まります。 ### 取得 ```bash theme={null} # 単一の Agent を取得 curl -s https://api.qoder.com/api/v1/cloud/agents/agent_xxx \ -H "Authorization: Bearer $QODER_PAT" # ページネーション付きリスト curl -s "https://api.qoder.com/api/v1/cloud/agents?limit=20" \ -H "Authorization: Bearer $QODER_PAT" ``` ### 更新 更新時は現在の `version` を**必ず**指定してください。詳細は下記「バージョン管理」を参照してください。 ```bash theme={null} curl -s -X POST https://api.qoder.com/api/v1/cloud/agents/agent_xxx \ -H "Authorization: Bearer $QODER_PAT" \ -H "Content-Type: application/json" \ -d '{ "name": "code-reviewer", "model": "ultimate", "system": "あなたはシニアコードレビュアーです。セキュリティとパフォーマンスに重点を置いてレビューしてください。", "version": 1 }' | jq . ``` 成功時は **200 OK** が返され、`version` が自動的にインクリメントされます。 ## バージョン管理 Agent は楽観的同時実行制御（OCC）を採用しています： * 作成時、`version` は `1` から開始されます * 更新が成功するたびに `version` がインクリメントされます * 更新リクエストには現在の `version` を**必ず**含める必要があります。以下の 2 つの失敗パターンがあります： * `version` フィールドが欠落 — **400** `invalid_request_error`（`"Field 'version' is required."`）を返す * `version` が存在するがサーバー側と不一致 — **409** `conflict_error` を返す これにより、複数のユーザーやシステムによる同時更新が互いを上書きすることを防ぎます。 ### 409 コンフリクトの処理 保持しているバージョンが古い場合： ```json theme={null} { "type": "error", "request_id": "cb80235f-76a2-4ff3-9e28-5aa2da12dc14", "error": { "type": "conflict_error", "message": "Version conflict. Expected version 2, got 1." } } ``` リカバリ手順： 1. `GET` で Agent を取得し、最新の `version` を確認する 2. 自分の変更をマージする 3. 新しい `version` を指定して再度 `POST` する ## ベストプラクティス 1. **命名規則** — `チーム-用途` の形式を使用する（例：`backend-code-review`、`frontend-test-gen`） 2. **プロンプトを明確に** — `system` フィールドに役割、出力形式、制約条件を明示する 3. **最小限のツール** — タスクに必要なツールのみを付与し、影響範囲を抑える 4. **metadata を活用** — タグを使って分類管理し、フィルタリングや監査に活用する 5. **本番環境ではバージョンを固定** — Session 作成時に `{"id": ..., "version": ...}` 形式で Agent バージョンを固定し、更新による本番環境への影響を防ぐ ## よくある質問 **Q：Agent を更新すると、実行中の Session に影響しますか？** いいえ。Session は作成時に Agent の特定バージョンにバインドされるため、その後の更新は既存の Session に影響しません。 **Q：`tools` 配列を空にできますか？** はい。ツールなしの Agent はプレーンテキストの会話のみ可能で、いかなる操作も実行できません。 **Q：`name` フィールドに長さ制限はありますか？** 64 文字以内に収め、小文字の英字、数字、ハイフンを使用してください。 **Q：Agent を古いバージョンにロールバックするには？** 現時点では自動ロールバックはサポートされていません。更新前に設定のスナップショットを保存し、必要時にそれを `POST` で再適用してください（最新の `version` を指定）。 ## 次のステップ Agent が実行されるインフラストラクチャを構成する。 Agent で作業セッションを作成する。 ツールタイプと権限ポリシーの詳細。 Agent の CRUD API リファレンス。