Skip to main content
Agent の定義

Agent の定義

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

Agent は Qoder Cloud Agents のコア構成テンプレートであり、AI エージェントの能力範囲を定義します — モデル、振る舞い、使用可能なツール。1 つの Agent を複数の Session で再利用でき、Agent を更新しても実行中の Session には影響しません。

コア要素

Agent は「職務記述書」のようなものです：
要素役割
モデルAgent の推論能力
システムプロンプトAgent の振る舞いとルール
ツールAgent が実行できる操作
SkillsAgent が呼び出せる高レベルスキル
Agent 自体はタスクを実行しません — 構成情報にすぎません。実際の処理は Agent にバインドされた Session 内で行われます。

フィールドリファレンス

フィールド型必須説明
idstring—システム生成、agent_ プレフィックス + 32 文字の小文字16進数
typestring—固定値 "agent"
namestringはいAgent 名。英小文字のケバブケース推奨（64 文字以内）
descriptionstringいいえ説明文。デフォルト ""
modelstringはいモデル識別子。詳細は下記参照
systemstringいいえシステムプロンプト。デフォルト ""
toolsarrayいいえ使用可能なツールのリスト。詳細は下記参照
skillsarrayいいえ関連する Skill ID のリスト
mcp_serversarrayいいえMCP サーバー設定のリスト。デフォルト []
multiagentobject|nullいいえMultiagent オーケストレーション設定。未設定時は null を返す
metadataobjectいいえタグ付けやフィルタリング用のカスタムキー/値ペア
versioninteger—バージョン番号。1 から開始
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 の値：
ツール名説明
Bashシェルコマンドの実行
Readファイル内容の読み取り
Writeファイルの作成または上書き
Editファイルの部分編集
Globグロブパターンによるファイル一覧
Grepファイル内容の検索
WebFetch単一ページの HTTP GET
WebSearchWeb 検索
ImageSearch画像検索
ImageGenテキストプロンプトからの画像生成
DeliverArtifacts/data/ 配下で生成したファイルをユーザーに配信
カスタムのクライアントサイドツールと権限ポリシーについては Agent ツール設定 を参照してください。

Agent の管理

完全な CRUD インターフェースは API リファレンス / Agents を参照してください。以下は一般的なワークフローの例です。

作成

curl -s -X POST https://api.qoder.com/api/v1/cloud/agents \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -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 から始まります。

取得

# 単一の Agent を取得
curl -s https://api.qoder.com/api/v1/cloud/agents/agent_xxx \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN"

# ページネーション付きリスト
curl -s "https://api.qoder.com/api/v1/cloud/agents?limit=20" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN"

更新

更新時は現在の version を必ず指定してください。詳細は下記「バージョン管理」を参照してください。 
curl -s -X POST https://api.qoder.com/api/v1/cloud/agents/agent_xxx \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -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 コンフリクトの処理

保持しているバージョンが古い場合： 
{
  "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 が実行されるインフラストラクチャを構成する。

Session の開始

Agent で作業セッションを作成する。

ツール

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

Agents API

Agent の CRUD API リファレンス。
はじめに
Agent の定義
Agent 環境の設定
Agent にタスクを委任する
Agent 連携
Agent コンテキストの管理
アカウント
ベストプラクティス
お知らせ
API リファレンス