エージェントツール - - Alibaba Cloud ドキュメントセンター

ツールは、エージェントの機能を決定します。エージェントの作成または更新時に tools フィールドを設定することで、その機能を正確に制御できます。

重要

新しい Qoder CN のドキュメントサイトが公開されました。このサイトのコンテンツは、最新の製品機能や変更点を反映していない場合があります。最新の製品ドキュメントについては、docs.qoder.cn をご参照ください。

ツールの役割

タスクの実行時、エージェントは tools の設定に基づき、呼び出し可能な機能を決定します。すべてのツールは、単一のオブジェクト { "type": "agent_toolset_20260401", "enabled_tools": [...] } を通じて設定し、enabled_tools 配列でアトミックツールを選択的に有効化します。

enabled_tools が空でない許可リストである場合、リストに含まれないツールはモデルから認識されず、呼び出しは試行されません。enabled_tools が省略されるか、空の配列である場合、すべての組み込みツールがモデルに公開されます。tools フィールド自体が省略されるか、[] に設定されている場合、モデルはツールスキーマを一切受け取りません (下記のよくある質問をご参照ください)。

利用可能なツール

ツール名 (enabled_tools の値)	目的	典型的なユースケース
`Bash`	シェルコマンドの実行	依存関係のインストール、スクリプトの実行、curl を使用した API の呼び出し
`Read`	ファイルの読み取り	マウントされたファイルの表示、コードの読み取り
`Write`	ファイルの書き込み (作成/上書き)	レポートの生成、出力の作成
`Edit`	ファイルの部分的な編集	設定の変更、コードの編集
`Glob`	Glob パターンによるファイル一覧の取得	コードファイルの検索
`Grep`	ファイル内容の検索	文字列の特定
`WebFetch`	単一ページの HTTP GET	ドキュメント/ページの取得
`WebSearch`	Web 検索	情報の検索
`DeliverArtifacts`	システム予約ツール。「すべてオン」のセット (`enabled_tools` が省略または空の場合) に含まれます。	`enabled_tools` で明示的に宣言することは推奨されません。

注：

ツール名は Bash のようにキャピタライズされ (bash ではありません)、イベントストリームでも大文字で表示されます。
enabled_tools を省略するか、空の配列 [] を渡すと、すべての組み込みツール (上記の DeliverArtifacts を含む) が有効になります。エージェントでツールを一切使用させない場合は、tools フィールド全体を省略するか、[] に設定します。
enabled_tools 内の各ツール名は検証されます。不明な名前 (例: "Foo") を書き込むと、400： "unknown tool name 'Foo'" が返されます。
古いツールごとのオブジェクトスキーマ (例: {"type": "bash_20250124"}) はサポートされなくなりました。

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

ツール設定は、enabled_tools 配列を介して特定のツールを切り替える単一のオブジェクトです：

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

エージェント作成時の設定：

curl -X POST https://api.qoder.com.cn/api/v1/cloud/agents \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "dev-agent",
    "model": "ultimate",
    "instructions": "You are a development assistant",
    "tools": [
      {
        "type": "agent_toolset_20260401",
        "enabled_tools": ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "WebFetch", "WebSearch"]
      }
    ]
  }'

設定例

最小構成 (CLI のみ)

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

フル開発スタック

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

新しいバージョンの作成 (PUT による完全な置換)

PUT を使用して、ツール設定を更新したエージェントの新しいバージョンを作成します：

curl -X PUT https://api.qoder.com.cn/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"]
      }
    ]
  }'

PUT はパッチではなく、完全な置換です。含まれていないフィールドはクリアされます。楽観的同時実行制御のために、version フィールドを含める必要があります： - 指定されたバージョンが現在のバージョンと一致する場合： 200 が返され、バージョンが 1 増加します。 - 指定されたバージョンが古い場合： 409 { error: { type: "conflict_error", message: "Version conflict. Expected version N, got M." }} が返されます。既存のセッションは影響を受けず、新しいセッションは更新された設定を使用します。

現在のツール設定の確認

curl https://api.qoder.com.cn/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: エージェントは利用できるツールを持たず、プレーンテキストでの会話しか行うことができません。エージェントに何らかのツール機能を持たせるには、少なくとも [{"type":"agent_toolset_20260401"}] (すべての組み込みツールが有効になります) を渡す必要があります。

Q：セッションレベルでツールをオーバーライドできますか？ A：現在はできません。ツール設定はエージェントに紐づけられており、そのエージェントのすべてのセッションが同じツールセットを共有します。

Q: tools の順序は関係ありますか？ A: いいえ。エージェントはタスクのコンテキストに基づいて、呼び出すツールを判断します。

Q：バージョンのサフィックスは将来変更されますか？ A：はい。新しいツールバージョンがリリースされると、日付付きの新しいサフィックスが導入されます。変更履歴を確認し、最新のサフィックスを採用してください。