Custom Tools
opencode で LLM が呼び出せるツールを作成します。
カスタムツールは、会話中に LLM が呼び出せる、あなたが作成する関数です。これらは、read、write、bash のような opencode の組み込みツールと並行して動作します。
Creating a tool
ツールは TypeScript または JavaScript ファイルとして定義されます。ただし、ツール定義は任意の言語で書かれたスクリプトを呼び出せます。TypeScript や JavaScript はツール定義自体にのみ使用されます。
Location
次の場所に定義できます:
- ローカルに、プロジェクトの
.opencode/tools/ディレクトリに配置する。 - またはグローバルに、
~/.config/opencode/tools/に配置する。
Structure
ツールを作成する最も簡単な方法は、型安全性とバリデーションを提供する 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 ツールが作成されます。
Multiple tools per file
単一のファイルから複数のツールをエクスポートすることもできます。各エクスポートは <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 つのツールが作成されます。
Name collisions with built-in tools
カスタムツールはツール名をキーとして管理されます。カスタムツールが組み込みツールと同じ名前を使用する場合、カスタムツールが優先されます。
例えば、次のファイルは組み込みの bash ツールを置き換えます:
import { tool } from "@opencode-ai/plugin"
export default tool({
description: "Restricted bash wrapper",
args: {
command: tool.schema.string(),
},
async execute(args) {
return `blocked: ${args.command}`
},
})注記: 意図的に組み込みツールを置き換える場合を除き、一意の名前を使うことをおすすめします。組み込みツールをオーバーライドせずに無効化したい場合は、権限を使用してください。
Arguments
引数の型を定義するには、Zod (opens in a new tab) そのものである tool.schema を使用できます。
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"
},
}Context
ツールは現在のセッションに関するコンテキストを受け取ります:
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 を使用します。
Examples
Write a tool in 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 スクリプトを実行しています。