カスタムツール
opencode で LLM が呼び出せるツールを作成します。
カスタムツールは、会話中に LLM が呼び出せる関数です。opencode の組み込みツール（read、write、bash など）と連携して動作します。
ツールの作成
ツールは TypeScript または JavaScript ファイルとして定義します。ただし、ツール定義は任意の言語で書かれたスクリプトを呼び出すことができます。TypeScript や JavaScript はツール定義自体にのみ使用されます。
配置場所
ツールは以下の場所に定義できます：
- ローカル：プロジェクトの
.opencode/tools/ディレクトリに配置 - またはグローバル：
~/.config/opencode/tools/に配置
構造
ツールを作成する最も簡単な方法は、型安全性と検証を提供する tool() ヘルパーを使用することです。
import { tool } from "@opencode-ai/plugin"
export default tool({
description: "Query the project database",
args: {
query: tool.schema.string().describe("SQL query to execute"),
},
async execute(args) {
// Your database logic here
return `Executed query: ${args.query}`
},
})ファイル名がツール名になります。上記のコードは database ツールを作成します。
1ファイルで複数ツール
1つのファイルから複数のツールをエクスポートすることもできます。各エクスポートは <filename>_<exportname> という名前の個別のツールになります：
import { tool } from "@opencode-ai/plugin"
export const add = tool({
description: "Add two numbers",
args: {
a: tool.schema.number().describe("First number"),
b: tool.schema.number().describe("Second number"),
},
async execute(args) {
return args.a + args.b
},
})
export const multiply = tool({
description: "Multiply two numbers",
args: {
a: tool.schema.number().describe("First number"),
b: tool.schema.number().describe("Second number"),
},
async execute(args) {
return args.a * args.b
},
})これにより、math_add と math_multiply の2つのツールが作成されます。
引数
tool.schema（実際には Zod (opens in a new tab)）を使用して引数の型を定義できます。
args: {
query: tool.schema.string().describe("SQL query to execute")
}Zod (opens in a new tab) を直接インポートしてプレーンオブジェクトを返すこともできます：
import { z } from "zod"
export default {
description: "Tool description",
args: {
param: z.string().describe("Parameter description"),
},
async execute(args, context) {
// Tool implementation
return "result"
},
}コンテキスト
ツールは現在のセッションに関するコンテキスト情報を受け取ります：
import { tool } from "@opencode-ai/plugin"
export default tool({
description: "Get project information",
args: {},
async execute(args, context) {
// Access context information
const { agent, sessionID, messageID, directory, worktree } = context
return `Agent: ${agent}, Session: ${sessionID}, Message: ${messageID}, Directory: ${directory}, Worktree: ${worktree}`
},
})セッションの作業ディレクトリには context.directory を使用します。git worktree のルートには context.worktree を使用します。
例
Python でツールを書く
任意の言語でツールを書くことができます。以下は Python を使用して2つの数値を加算する例です。
まず、Python スクリプトとしてツールを作成します：
import sys
a = int(sys.argv[1])
b = int(sys.argv[2])
print(a + b)次に、それを呼び出すツール定義を作成します：
import { tool } from "@opencode-ai/plugin"
import path from "path"
export default tool({
description: "Add two numbers using Python",
args: {
a: tool.schema.number().describe("First number"),
b: tool.schema.number().describe("Second number"),
},
async execute(args, context) {
const script = path.join(context.worktree, ".opencode/tools/add.py")
const result = await Bun.$`python3 ${script} ${args.a} ${args.b}`.text()
return result.trim()
},
})ここでは Bun.$ (opens in a new tab) ユーティリティを使用して Python スクリプトを実行しています。