Skip to Content
CoreQwen Code Core: Tools API

Qwen Code Core: Tools API

Qwen Code のコア（packages/core）には、ツールを定義・登録・実行するための堅牢なシステムが備わっています。これらのツールはモデルの機能を拡張し、ローカル環境とのやり取り、Web コンテンツの取得、単純なテキスト生成を超えたさまざまなアクションの実行を可能にします。

## コアコンセプト
 
- **ツール (`tools.ts`)**: すべてのツールに共通するインターフェースと、その基底クラス（`BaseTool`）を定義します。各ツールは以下の要素を持つ必要があります：
  - `name`: モデルへのAPI呼び出しで使用される一意の内部名。
  - `displayName`: ユーザーに表示される分かりやすい名前。
  - `description`: モデルに提供される、ツールが何を行うかを明確に説明する文。
  - `parameterSchema`: ツールが受け取るパラメータを定義するJSONスキーマ。モデルが正しくツールを呼び出すために重要です。
  - `validateToolParams()`: 入力されたパラメータを検証するためのメソッド。
  - `getDescription()`: 実行前に、特定のパラメータを使ってツールが何を行うかを人間が読める形式で返すメソッド。
  - `shouldConfirmExecute()`: 実行前にユーザー確認が必要かどうかを判定するメソッド（例：破壊的な操作など）。
  - `execute()`: ツールの主要な処理を行い、`ToolResult` を返すコアメソッド。
 
- **`ToolResult` (`tools.ts`)**: ツール実行結果の構造を定義するインターフェース：
  - `llmContent`: LLMに送り返される履歴に含める事実情報。単純な文字列でも、画像や音声などのリッチコンテンツに対応した `PartListUnion`（`Part` オブジェクトと文字列の配列）でも可。
  - `returnDisplay`: CLI上で表示するためのユーザー向け文字列（多くの場合Markdown）または特別なオブジェクト（例：`FileDiff`）。
 
- **リッチコンテンツの返却**: ツールは単純なテキストだけでなく、複数のリッチコンテンツを返すことも可能です。`llmContent` には `PartListUnion` を指定でき、これは `Part` オブジェクト（画像・音声等）と `string` の混合配列を受け入れます。これにより、1回のツール実行で複数のリッチコンテンツを返すことが可能になります。
 
- **ツールレジストリ (`tool-registry.ts`)**: 次の責務を持つクラス（`ToolRegistry`）です：
  - **ツール登録**: 利用可能な組み込みツール群（例：`ListFiles`, `ReadFile`）を保持します。
  - **ツール探索**: 動的にツールを発見することもできます：
    - **コマンドベースの探索**: 設定で `tools.toolDiscoveryCommand` が指定されている場合、そのコマンドを実行し、出力されたカスタムツール情報をJSONとして読み込んで、`DiscoveredTool` インスタンスとして登録します。
    - **MCPベースの探索**: `mcp.mcpServerCommand` が設定されていれば、Model Context Protocol (MCP) サーバーに接続して利用可能なツール一覧を取得し、`DiscoveredMCPTool` として登録します。
  - **スキーマ提供**: 登録済みツールの `FunctionDeclaration` スキーマをモデル側に公開することで、どのツールが利用可能でどのように使うべきかを伝えます。
  - **ツール取得**: コアロジックから任意のツール名で対象ツールを取得し、実行できるようにします。

組み込みツール

コアには、あらかじめ定義された一連のツールが含まれており、通常は packages/core/src/tools/ に配置されています。これには以下が含まれます：

  • ファイルシステムツール:
    • ListFiles (ls.ts): ディレクトリの内容を一覧表示します。
    • ReadFile (read-file.ts): 単一のファイルの内容を読み取ります。absolute_path パラメータを受け取り、これは絶対パスである必要があります。
    • WriteFile (write-file.ts): ファイルに内容を書き込みます。
    • ReadManyFiles (read-many-files.ts): 複数のファイルまたは glob パターンから内容を読み取り、結合します（CLI の @ コマンドで使用）。
    • Grep (grep.ts): ファイル内のパターンを検索します。
    • Glob (glob.ts): glob パターンに一致するファイルを検索します。
    • Edit (edit.ts): ファイルに対してインプレースでの変更を実行します（多くの場合、確認が必要）。
  • 実行ツール:
    • Shell (shell.ts): 任意の shell コマンドを実行します（慎重なサンドボックス化とユーザー確認が必要）。
  • Web ツール:
    • WebFetch (web-fetch.ts): URL から内容を取得します。
    • WebSearch (web-search.ts): Web 検索を実行します。
  • メモリーツール:
    • SaveMemory (memoryTool.ts): AI のメモリーとやり取りします。
  • プランニングツール:
    • Task (task.ts): 特化したサブエージェントにタスクを委譲します。
    • TodoWrite (todoWrite.ts): 構造化されたタスクリストを作成・管理します。
    • ExitPlanMode (exitPlanMode.ts): プランモードを終了し、通常の操作に戻ります。

これらの各ツールは BaseTool を拡張し、特定の機能に必要なメソッドを実装しています。

ツール実行フロー

  1. モデルリクエスト: モデルは、ユーザーのプロンプトと提供されたツールスキーマに基づいて、ツールを使用することを決定し、レスポンス内で FunctionCall パートを返却します。このパートには、ツール名と引数が指定されています。
  2. Core がリクエストを受信: Core はこの FunctionCall をパースします。
  3. ツール検索: ToolRegistry 内で要求されたツールを検索します。
  4. パラメータバリデーション: ツールの validateToolParams() メソッドが呼び出されます。
  5. 確認（必要な場合）:
    • ツールの shouldConfirmExecute() メソッドが呼び出されます。
    • このメソッドが確認用の詳細情報を返す場合、Core はその内容を CLI に伝え、ユーザーにプロンプトを表示させます。
    • ユーザーの判断（例：実行、キャンセル）が Core に送り返されます。
  6. 実行: バリデーションおよび確認が完了した場合（または確認が不要な場合）、Core はツールの execute() メソッドを、指定された引数と AbortSignal（キャンセル用）とともに呼び出します。
  7. 結果処理: execute() から返される ToolResult が Core に受け取られます。
  8. モデルへのレスポンス: ToolResult の llmContent が FunctionResponse としてパッケージ化され、モデルに送り返され、モデルはユーザー向けのレスポンス生成を継続できます。
  9. ユーザーへの表示: ToolResult の returnDisplay が CLI に送られ、ユーザーに対してツールが何を行ったかが表示されます。

カスタムツールによる拡張

エンドユーザー向けの標準的なワークフローとしては明記されていませんが、提供されたファイル内ではユーザーが新しいツールを直接プログラムで登録する方法は詳細に説明されていません。ただし、アーキテクチャ上は以下の方法で拡張が可能です：

  • コマンドベースの検出： 上級ユーザーまたはプロジェクト管理者は、settings.json 内に tools.toolDiscoveryCommand を定義できます。このコマンドは、core によって実行され、その結果として FunctionDeclaration オブジェクトの JSON 配列を出力する必要があります。core はこれらの情報をもとに、DiscoveredTool インスタンスとして利用可能にします。そして実際にカスタムツールを実行するのは、対応する tools.toolCallCommand の役割となります。
  • MCP サーバー： より複雑なシナリオに対応するには、1つ以上の MCP サーバーをセットアップし、settings.json の mcpServers 設定から設定を行います。core はこれらのサーバーが公開しているツールを検出して使用することが可能になります。前述の通り、複数の MCP サーバーがある場合、ツール名には設定上のサーバー名がプレフィックスとして付加されます（例：serverAlias__actualToolName）。

このツールシステムにより、モデルの機能を柔軟かつ強力に拡張でき、Qwen Code をさまざまなタスクに対応できる多機能なアシスタントとして活用することが可能になります。

Last updated on
Memory Import Processorはじめに