Skip to Content
CoreQwen Code Core: Tools API

Qwen Code Core: Tools API

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

## コアコンセプト
 
- **Tool (`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 (`tool-registry.ts`)**: 以下の責務を持つクラス（`ToolRegistry`）：
  - **ツールの登録**: 利用可能なすべての組み込みツール（例：`ReadFileTool`、`ShellTool`）を保持。
  - **ツールの発見**: 動的にツールを発見することも可能：
    - **コマンドベースの発見**: 設定で `tools.toolDiscoveryCommand` が指定されていれば、そのコマンドを実行。出力される JSON からカスタムツールを読み込み、`DiscoveredTool` インスタンスとして登録。
    - **MCP ベースの発見**: `mcp.mcpServerCommand` が設定されていれば、Model Context Protocol (MCP) サーバーに接続してツール一覧を取得し、`DiscoveredMCPTool` として登録。
  - **スキーマの提供**: 登録されたすべてのツールの `FunctionDeclaration` スキーマをモデルに公開し、利用可能なツールとその使用方法を認識させる。
  - **ツールの取得**: コアが実行時に名前で特定のツールを取得できるようにする。

組み込みツール

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

  • ファイルシステムツール:
    • LSTool (ls.ts): ディレクトリの内容を一覧表示します。
    • ReadFileTool (read-file.ts): 単一のファイルの内容を読み込みます。absolute_path パラメータを受け取り、これは絶対パスである必要があります。
    • WriteFileTool (write-file.ts): ファイルに内容を書き込みます。
    • GrepTool (grep.ts): ファイル内のパターンを検索します。
    • GlobTool (glob.ts): glob パターンに一致するファイルを検索します。
    • EditTool (edit.ts): ファイルに対してインプレースで変更を実行します（多くの場合、確認が必要です）。
    • ReadManyFilesTool (read-many-files.ts): 複数のファイルまたは glob パターンから内容を読み込んで結合します（CLI の @ コマンドで使用されます）。
  • 実行ツール:
    • ShellTool (shell.ts): 任意の shell コマンドを実行します（慎重なサンドボックス化とユーザー確認が必要です）。
  • Web ツール:
    • WebFetchTool (web-fetch.ts): URL から内容を取得します。
    • WebSearchTool (web-search.ts): Web 検索を実行します。
  • メモリツール:
    • MemoryTool (memoryTool.ts): AI のメモリとやり取りします。

これらの各ツールは 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はじめに