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 は Qoder Cloud Agents の中核となる構成テンプレートで、AI エージェントの能力範囲（モデル・行動指針・利用ツール）を定義します。1 つの Agent は複数の Session で再利用でき、Agent の更新が稼働中の Session に影響することはありません。
コア要素
Agent は「職務記述書」のようなものです。
| 要素 | 役割 |
|---|
| モデル | Agent の推論能力 |
| システムプロンプト | Agent の挙動と方針 |
| ツール | Agent が実行できる操作 |
| Skills | Agent が呼び出せる高レベル能力 |
フィールドリファレンス
| フィールド | 型 | 必須 | 説明 |
|---|
id | string | — | システム生成、ag_ プレフィックス |
name | string | はい | Agent 名。英小文字 + ハイフン推奨（≤ 64 文字） |
model | string | はい | モデル識別子（下記参照） |
system | string | いいえ | Agent 挙動を定義するシステムプロンプト |
tools | array | いいえ | 利用可能なツールリスト（下記参照） |
skills | array | いいえ | 関連付ける Skill ID リスト |
metadata | object | いいえ | タグや絞り込み用のカスタム key/value |
version | integer | — | バージョン番号、1 から始まる |
created_at | string | — | 作成時刻（ISO 8601） |
updated_at | string | — | 最終更新時刻 |
model
Agent が使用するモデルを指定する文字列です。
| 値 | 説明 |
|---|
"ultimate" | 最強モデル。複雑な推論や長時間タスクに最適 |
"auto" | 価格性能比が最も良いモデルを自動選択 |
tools はツールオブジェクトの配列で、各エントリが Agent が実行できる 1 種類の操作を宣言します。
{
"tools": [
{"type": "bash_20250124"},
{"type": "file_read"},
{"type": "file_write"},
{"type": "web_search"}
]
}
| タイプ | 説明 |
|---|
bash | Shell コマンドを実行 |
file_read | ファイル内容を読み取り |
file_write | ファイルを作成・更新 |
web_search | Web 検索 |
Agent の管理
完全な CRUD インターフェイスは API Reference / Agents を参照してください。以下は典型的なワークフロー例です。
curl -s -X POST https://openapi.qoder.sh/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": "bash_20250124"},
{"type": "file_read"},
{"type": "file_write"}
],
"metadata": {
"team": "backend",
"purpose": "code-review"
}
}' | jq .
version は 1 から始まります。
# 単一 Agent を取得
curl -s https://openapi.qoder.sh/api/v1/cloud/agents/ag_xxx \
-H "Authorization: Bearer $QODER_PAT"
# ページネーション付き一覧
curl -s "https://openapi.qoder.sh/api/v1/cloud/agents?limit=20" \
-H "Authorization: Bearer $QODER_PAT"
version を必ず含める必要があります。詳細は下記「バージョン管理」を参照してください。
curl -s -X PUT https://openapi.qoder.sh/api/v1/cloud/agents/ag_xxx \
-H "Authorization: Bearer $QODER_PAT" \
-H "Content-Type: application/json" \
-d '{
"name": "code-reviewer",
"model": "ultimate",
"system": "あなたはセキュリティとパフォーマンスに特化したシニアコードレビュー担当者です。",
"version": 1
}' | jq .
version は自動的に +1 されます。
curl -s -X DELETE https://openapi.qoder.sh/api/v1/cloud/agents/ag_xxx \
-H "Authorization: Bearer $QODER_PAT"
Agent を削除しても、その Agent にバインドされた稼働中の Session は終了しません。Session は作成時に Agent 構成のスナップショットを保持しています。
バージョン管理
Agent は楽観的同時実行制御 (OCC) を採用しています。
- 作成時、
version は 1 から始まる
- 更新成功のたびに
version は自動的に +1
- 更新リクエストには現在の
version を必ず含める必要がある。さもなくば 409 Conflict が返る
これにより、複数人 / 複数システムからの同時更新で書き戻しが発生するのを防ぎます。
409 への対処
保持しているバージョンが古い場合:
{
"error": {
"type": "conflict",
"message": "Version mismatch: expected 2, got 1"
}
}
GET で最新の Agent と version を取得- 自分の変更をマージ
- 新しい
version を付けて再度 PUT
ベストプラクティス
- 命名規則 —
チーム-用途 形式（例: backend-code-review、frontend-test-gen）
- 簡潔なプロンプト —
system には役割、出力形式、制約を明確に書く
- 最小ツールセット — タスクに必要なツールだけを付与し、誤操作リスクを減らす
- metadata の活用 — タグで分類し、後段の絞り込みや監査に役立てる
- 本番ではバージョン固定 — Session 作成時に
{"id": ..., "version": ...} 形式で Agent バージョンを固定し、更新が本番挙動に影響するのを防ぐ
よくある質問
Q: Agent を更新すると、稼働中の Session にも影響しますか?
影響しません。Session は作成時点の Agent バージョンにバインドされており、その後の更新は伝播しません。
Q: tools 配列は空でも構いませんか?
構いません。ツールを持たない Agent はテキスト対話のみが可能で、操作は実行できません。
Q: name フィールドに長さ制限はありますか?
64 文字以内に収め、英小文字・数字・ハイフンを使用することを推奨します。
Q: 古いバージョンの Agent にロールバックするには?
現時点では自動ロールバックはサポートされていません。更新前に旧構成を控え、必要なときに最新の version を付けて手動で PUT し直してください。
次のステップ
