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
)を保持。 - ツールの発見: 動的にツールを発見することも可能:
- コマンドベースの発見: 設定で
toolDiscoveryCommand
が指定されている場合、そのコマンドを実行し、カスタムツールを記述した JSON を出力することが期待される。出力されたツールはDiscoveredTool
インスタンスとして登録される。 - 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
を拡張し、特定の機能に必要なメソッドを実装しています。
ツール実行フロー
- モデルリクエスト: モデルは、ユーザーのプロンプトと提供されたツールスキーマに基づいて、ツールを使用することを決定し、レスポンス内で
FunctionCall
パートを返却します。このパートには、ツール名と引数が指定されています。 - Core がリクエストを受信: Core はこの
FunctionCall
をパースします。 - ツール検索:
ToolRegistry
内で要求されたツールを検索します。 - パラメータ検証: ツールの
validateToolParams()
メソッドが呼び出されます。 - 確認(必要な場合):
- ツールの
shouldConfirmExecute()
メソッドが呼び出されます。 - このメソッドが確認用の詳細を返す場合、Core は CLI にこの情報を伝え、ユーザーにプロンプトを表示します。
- ユーザーの判断(例:実行、キャンセル)が Core に送り返されます。
- ツールの
- 実行: 検証および確認が完了した場合(または確認が不要な場合)、Core はツールの
execute()
メソッドを、指定された引数とAbortSignal
(キャンセル用)とともに呼び出します。 - 結果処理:
execute()
から返されたToolResult
が Core に受信されます。 - モデルへのレスポンス:
ToolResult
のllmContent
がFunctionResponse
としてパッケージ化され、モデルに送り返され、モデルがユーザー向けのレスポンス生成を続行できるようにします。 - ユーザーへの表示:
ToolResult
のreturnDisplay
が CLI に送られ、ユーザーにツールが何を行ったかが表示されます。
カスタムツールによる拡張
エンドユーザー向けの一般的なワークフローとして、ユーザーによる新規ツールの直接的なプログラムによる登録については、提供されているファイルには明確に記載されていませんが、アーキテクチャでは以下の方法で拡張をサポートしています:
- コマンドベースの検出: 上級ユーザーまたはプロジェクト管理者は、
settings.json
にtoolDiscoveryCommand
を定義できます。このコマンドは、core によって実行され、FunctionDeclaration
オブジェクトの JSON 配列を出力する必要があります。core はこれらをDiscoveredTool
インスタンスとして利用可能にします。対応するtoolCallCommand
が、これらのカスタムツールを実際に実行する役割を担います。 - MCP サーバー: より複雑なシナリオでは、1つ以上の MCP サーバーをセットアップし、
settings.json
のmcpServers
設定で構成できます。core はこれらのサーバーが公開するツールを検出して利用することが可能です。前述の通り、複数の MCP サーバーがある場合、ツール名には設定に記載されたサーバー名がプレフィックスとして付加されます(例:serverAlias__actualToolName
)。
このツールシステムにより、モデルの機能を柔軟かつ強力に拡張でき、Qwen Code をさまざまなタスクに対応可能な多機能なアシスタントにしています。