Agent ツール

ツールは Agent が何ができるかを決定します。Agent の作成または更新時に tools フィールドを設定することで、Agent の能力範囲を正確に制御できます。

ツールの役割

Agent はタスクの実行時に、tools の設定に基づいてどの機能を呼び出せるかを判断します。組み込みツールは { "type": "agent_toolset_20260401", "enabled_tools": [...] } で設定し、enabled_tools 配列内の個別ツールを必要に応じて有効化します。クライアントサイドのカスタムツールは独立した { "type": "custom", ... } エントリで設定します。 enabled_tools が空でないホワイトリストの場合、リスト外のツールはモデルに一切見えず、呼び出しの試行も行われません。enabled_tools を省略するか空配列にした場合、すべての組み込みツールがモデルに公開されます。tools フィールド自体を省略するか [] に設定した場合、モデルはツールスキーマを一切受け取りません（下記 FAQ 参照）。

利用可能なツール

ツール名（enabled_tools の値）	用途	典型的な使用例
`Bash`	Shell コマンド実行	依存関係のインストール、スクリプト実行、curl での API 呼び出し
`Read`	ファイル読み取り	マウントされたファイルの確認、コード閲覧
`Write`	ファイル書き込み（作成/上書き）	レポート生成、出力ファイルの作成
`Edit`	ファイルの部分編集	設定変更、コード編集
`Glob`	Glob パターンでのファイル一覧取得	コードファイルの検索
`Grep`	ファイル内容の検索	文字列の特定
`WebFetch`	HTTP GET で単一ページを取得	ドキュメント/ページの取得
`WebSearch`	Web 検索	情報の検索
`DeliverArtifacts`	Agent が `/data/` 配下で生成したファイルをダウンロード可能な成果物としてユーザーに配信	ユーザーがファイル/レポート/エクスポートなどの成果物を必要とする場合

注意事項：

ツール名は上表の正確な値を使用してください。イベントストリームでも同じ値が使用されます
enabled_tools を省略するか空配列 [] にすると、すべての組み込みツール（上表の DeliverArtifacts を含む）が有効になります。Agent にツールを一切持たせたくない場合は、tools フィールド全体を省略するか [] に設定してください
enabled_tools が空でないホワイトリストの場合、リスト外のツールはモデルに一切見えません。カスタムホワイトリストで DeliverArtifacts を使用するには、明示的に含める必要があります（例：["Bash", "Write", "DeliverArtifacts"]）
enabled_tools 内の各ツール名はバリデーションされます。未知の名前（例："Foo"）を指定すると 400 エラーが返されます："unknown tool name 'Foo'"
組み込みツールと MCP ツールの権限は configs[].permission_policy で設定します。詳細は権限ポリシーを参照してください
ツールごとにオブジェクトを定義する旧スキーマ（{"type": "bash_20250124"} など）はサポートされなくなりました

現在のフォーマット：単一オブジェクト

組み込みツールの設定は単一オブジェクトで行い、enabled_tools 配列で個別のツールを切り替えます：

{
  "tools": [
    {
      "type": "agent_toolset_20260401",
      "enabled_tools": ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "WebFetch", "WebSearch"]
    }
  ]
}

Agent 作成時に設定する場合：

curl -X POST https://api.qoder.com/api/v1/cloud/agents \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "dev-agent",
    "model": "ultimate",
    "system": "あなたは開発アシスタントです",
    "tools": [
      {
        "type": "agent_toolset_20260401",
        "enabled_tools": ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "WebFetch", "WebSearch"]
      }
    ]
  }'

カスタムクライアントサイドツール

カスタムツールを使用すると、アプリケーション側の機能を Agent に公開できます。Agent はこれらのツールの呼び出しをリクエストできますが、プラットフォームが直接実行することはありません。Agent がカスタムツールを呼び出すと、Session は requires_action の stop reason で一時停止し、クライアントがツールを実行した後、user.custom_tool_result イベントで結果を返送します。

{
  "tools": [
    {
      "type": "agent_toolset_20260401",
      "enabled_tools": ["Read", "Write"]
    },
    {
      "type": "custom",
      "name": "lookup_order",
      "description": "注文 ID で注文を検索します。",
      "input_schema": {
        "type": "object",
        "properties": {
          "order_id": {"type": "string"}
        },
        "required": ["order_id"]
      }
    }
  ]
}

カスタムツールのルール：

name、description、input_schema は必須です
input_schema は "type": "object" の JSON Schema オブジェクトである必要があります
同一 Agent 内のカスタムツール名は大文字小文字を区別せずに一意である必要があります
カスタムツール名は Bash や Read などの組み込みツール名と衝突してはなりません
mcp__ で始まる名前は MCP ツール用に予約されています
カスタムツールはクライアントが実行するため、permission_policy はサポートされていません

user.custom_tool_result の返送フローについてはイベントを送信を参照してください。

ツール設定例

最小構成（CLI のみ）

{
  "tools": [
    {
      "type": "agent_toolset_20260401",
      "enabled_tools": ["Bash"]
    }
  ]
}

完全な開発環境

{
  "tools": [
    {
      "type": "agent_toolset_20260401",
      "enabled_tools": ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "WebFetch", "WebSearch"]
    }
  ]
}

ツール設定の更新

POST を使用して Agent のツール設定を更新します。リクエストには現在の version を含める必要があります。tools を指定した場合、保存されているツール配列が置き換えられます。

curl -X POST https://api.qoder.com/api/v1/cloud/agents/agent_abc123 \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "version": 1,
    "tools": [
      {
        "type": "agent_toolset_20260401",
        "enabled_tools": ["Bash", "Read", "Write", "Edit"]
      }
    ]
  }'

Agent の更新では、省略されたフィールドに対して merge セマンティクスが使用されます。tools、mcp_servers、skills などの配列フィールドは、明示的に指定された場合に全体が置き換えられます。楽観的並行制御のために version フィールドを含める必要があります：

指定した version が現在のバージョンと一致する場合 → 200、version が 1 増加
指定した version が古い場合 → 409 { error: { type: "conflict_error", message: "Version conflict. Expected version N, got M." }}

既存の Session には影響しません。新しい Session は更新後の設定を使用します。

現在のツール設定を確認

curl https://api.qoder.com/api/v1/cloud/agents/agent_abc123 \
  -H "Authorization: Bearer $QODER_PAT" | jq '.tools'

出力例：

[
  {
    "type": "agent_toolset_20260401",
    "enabled_tools": ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "WebFetch", "WebSearch"]
  }
]

よくある質問

Q：tools を設定しないとどうなりますか？ A：Agent はツールを一切使用できず、プレーンテキストの会話のみ可能です。Agent にツール機能を持たせるには、少なくとも [{"type":"agent_toolset_20260401"}] を指定してください（すべての組み込みツールが有効になります）。 Q：Session レベルでツール設定を上書きできますか？ A：現在はサポートされていません。ツール設定は Agent に紐付けられており、同一 Agent のすべての Session が同じツールセットを共有します。 Q：tools 配列の順序は重要ですか？ A：重要ではありません。Agent はタスクのコンテキストに基づいてどのツールを呼び出すかを自主的に判断します。 Q：バージョンサフィックスは時間とともに変わりますか？ A：はい。API が新しいバージョンのツールをリリースする際に、新しい日付サフィックスが導入されます。Changelog を確認し、最新バージョンを採用することをお勧めします。

次のステップ

権限ポリシー

ツール呼び出しの許可・確認・拒否を制御する。

Agent スキル

Agent にドメイン専門知識を付与する。

Agent の定義

Agent 設定を確認する。

Session の開始

セッションのライフサイクルを管理する。

​ツールの役割

​利用可能なツール

​現在のフォーマット：単一オブジェクト

​カスタム クライアントサイド ツール

​ツール設定例

​最小構成（CLI のみ）

​完全な開発環境

​ツール設定の更新

​現在のツール設定を確認

​よくある質問

​次のステップ