メインコンテンツへスキップ
Agent は Qoder Cloud Agents の中核となる構成テンプレートで、AI エージェントの能力範囲（モデル・行動指針・利用ツール）を定義します。1 つの Agent は複数の Session で再利用でき、Agent の更新が稼働中の Session に影響することはありません。

​
コア要素

Agent は「職務記述書」のようなものです。
要素役割
モデルAgent の推論能力
システムプロンプトAgent の挙動と方針
ツールAgent が実行できる操作
SkillsAgent が呼び出せる高レベル能力
Agent 自体はタスクを実行しません。実際にタスクを実行するのは、Agent にバインドされた Session です。

​
Agent 構成フィールド

フィールド型必須説明
idstring—システム生成、agent_ プレフィックス + 32 文字の小文字 16 進数
typestring—常に "agent"
namestringはいAgent 名。英小文字 + ハイフン推奨（≤ 64 文字）
descriptionstringいいえ自由記述の説明、デフォルト ""
modelstringはいモデル識別子（下記参照）
systemstringいいえシステムプロンプト、デフォルト ""
toolsarrayいいえ利用可能なツールリスト（下記参照）
skillsarrayいいえ関連付ける Skill ID リスト
mcp_serversarrayいいえMCP サーバー構成のリスト、デフォルト []
metadataobjectいいえタグや絞り込み用のカスタム key/value
versioninteger—バージョン番号、1 から始まる
archivedboolean—アーカイブ済みかどうか、デフォルト false
archived_atstring|null—アーカイブ時刻（ISO 8601）、未アーカイブの場合は null
created_atstring—作成時刻（ISO 8601）
updated_atstring—最終更新時刻

​
model

model は Agent が使用するモデルの識別子です。モデル一覧 を呼び出して現在のアカウントで利用可能な値を確認し、Agent の作成・更新時にモデルの id を指定してください。

​
tools

tools はツールオブジェクトの配列です。組み込みツールは agent_toolset_20260401 で構成し、enabled_tools 配列でアトミックなツールを必要に応じて有効化します： 
{
  "tools": [
    {
      "type": "agent_toolset_20260401",
      "enabled_tools": ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "WebFetch", "WebSearch"]
    }
  ]
}
利用可能な enabled_tools の値：
ツール名説明
BashShell コマンドを実行
Readファイル内容を読み取り
Writeファイルを作成・上書き
Editファイルを部分編集
Globワイルドカードによるファイル一覧
Grepファイル内容検索
WebFetchHTTP GET 単一ページ
WebSearchWeb 検索
DeliverArtifacts/data/ 配下で生成したファイルをユーザーに配信
カスタムクライアントサイドツールや権限ポリシーについては、Agent ツール を参照してください。

​
Agent を作成する

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 .
成功時は 201 Created が返り、version は 1 から始まります。

​
Agent を取得・一覧する

# 単一 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"

​
Agent を更新する

更新リクエストには現在の version を必ず含める必要があります。マージ規則の詳細は下記「更新セマンティクス」を参照してください。 
curl -s -X PUT 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 は自動的に +1 されます。

​
更新セマンティクス

Agent は楽観的同時実行制御 (OCC) を採用しています。
  • 作成時、version は 1 から始まる
  • 更新成功のたびに version は自動的に +1
  • 更新リクエストには現在の version を必ず含める必要があります。失敗ケースは 2 種類：
    • version フィールドが欠落している場合 — 400 invalid_request_error（"Field 'version' is required."）が返る
    • version は存在するがサーバ側と一致しない場合 — 409 conflict_error が返る
これにより、複数人 / 複数システムからの同時更新で書き戻しが発生するのを防ぎます。

​
409 への対処

保持しているバージョンが古い場合: 
{
  "type": "error",
  "error": {
    "type": "conflict_error",
    "message": "Version conflict. Expected version 2, got 1."
  }
}
復旧手順:
  1. GET で最新の Agent と version を取得
  2. 自分の変更をマージ
  3. 新しい version を付けて再度 PUT

​
ベストプラクティス

  1. 命名規則 — チーム-用途 形式（例: backend-code-review、frontend-test-gen）
  2. 簡潔なプロンプト — system には役割、出力形式、制約を明確に書く
  3. 最小ツールセット — タスクに必要なツールだけを付与し、誤操作リスクを減らす
  4. metadata の活用 — タグで分類し、後段の絞り込みや監査に役立てる
  5. 本番ではバージョン固定 — Session 作成時に {"id": ..., "version": ...} 形式で Agent バージョンを固定し、更新が本番挙動に影響するのを防ぐ

​
よくある質問

Q: Agent を更新すると、稼働中の Session にも影響しますか? 影響しません。Session は作成時点の Agent バージョンにバインドされており、その後の更新は伝播しません。 Q: tools 配列は空でも構いませんか? 構いません。ツールを持たない Agent はテキスト対話のみが可能で、操作は実行できません。 Q: name フィールドに長さ制限はありますか? 64 文字以内に収め、英小文字・数字・ハイフンを使用することを推奨します。 Q: 古いバージョンの Agent にロールバックするには? 現時点では自動ロールバックはサポートされていません。更新前に旧構成を控え、必要なときに最新の version を付けて手動で PUT し直してください。

​
次のステップ

クラウド環境

Agent が動作する基盤の構成。

Session の開始

Agent を使って実行セッションを開始。

Agent ツール

ツールタイプと権限ポリシーの詳細。

Agents API

完全な Agents CRUD インターフェイス。