diff options
| -rw-r--r-- | packages/web/src/content/docs/custom-tools.mdx | 120 |
1 files changed, 61 insertions, 59 deletions
diff --git a/packages/web/src/content/docs/custom-tools.mdx b/packages/web/src/content/docs/custom-tools.mdx index 69a1783b7..77b237c8b 100644 --- a/packages/web/src/content/docs/custom-tools.mdx +++ b/packages/web/src/content/docs/custom-tools.mdx @@ -1,43 +1,69 @@ --- -title: Custom tools -description: Create custom tools to extend opencode capabilities. +title: Custom Tools +description: Create tools the LLM can call in opencode. --- Custom tools are functions you create that the LLM can call during conversations. They work alongside opencode's built-in tools like `read`, `write`, and `bash`. --- -## Tool structure +## Creating a tool -Tools are defined as `.ts/.js` files in the `.opencode/tool/` directory. They -can also be defined globally in `~/.config/opencode/tool/`. +Tools are defined as **TypeScript** or **JavaScript** files. -The easiest way to create tools is using the `tool()` helper which provides type safety and validation. Use `tool.schema` (which is just [Zod](https://zod.dev)) to define argument types: +--- + +### Location + +They can defined: -```ts title=".opencode/tool/database.ts" +- Locally by placing them in the `.opencode/tool/` directory of your project. +- Or globally, by placing them in `~/.config/opencode/tool/`. + +--- + +### Structure + +The easiest way to create tools is using the `tool()` helper which provides type-safety and validation. + +```ts title=".opencode/tool/database.ts" {1} import { tool } from "@opencode-ai/plugin" export default tool({ description: "Query the project database", args: { - query: tool.schema.string().describe("SQL query to execute"), + query: tool.schema.string().describe("SQL query to execute") }, async execute(args) { // Your database logic here return `Executed query: ${args.query}` - }, + } }) ``` +The **filename** becomes the **tool name**. The above creates a `database` tool. + +--- + +### Arguments + +You can use `tool.schema`, which is just [Zod](https://zod.dev), to define argument types. + +```ts "tool.schema" +args: { + query: tool.schema.string().describe("SQL query to execute") +} +``` + You can also import [Zod](https://zod.dev) directly and return a plain object: -```ts +```ts {6} import { z } from "zod" export default { description: "Tool description", args: { - param: z.string().describe("Parameter description"), + param: z.string().describe("Parameter description") }, async execute(args, context) { // Tool implementation @@ -46,13 +72,31 @@ export default { } ``` -The filename becomes the tool name. This creates a `database` tool. +--- + +## Context + +Tools receive context about the current session: + +```ts title=".opencode/tool/project.ts" {8} +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 } = context + return `Agent: ${agent}, Session: ${sessionID}, Message: ${messageID}` + }, +}) +``` --- ## Multiple tools per file -You can export multiple tools from a single file. Each export becomes a separate tool with the name `<filename>_<exportname>`: +You can also export multiple tools from a single file. Each export becomes **a separate tool** with the name **`<filename>_<exportname>`**: ```ts title=".opencode/tool/math.ts" import { tool } from "@opencode-ai/plugin" @@ -61,65 +105,23 @@ export const add = tool({ description: "Add two numbers", args: { a: tool.schema.number().describe("First number"), - b: tool.schema.number().describe("Second 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"), + b: tool.schema.number().describe("Second number") }, async execute(args) { return args.a * args.b - }, + } }) ``` This creates two tools: `math_add` and `math_multiply`. - ---- - -## Arguments - -Use `tool.schema` (which is just [Zod](https://zod.dev)) to define tool arguments with validation and descriptions: - -```ts title=".opencode/tool/calculator.ts" -import { tool } from "@opencode-ai/plugin" - -export default tool({ - description: "Perform mathematical calculations", - args: { - expression: tool.schema.string().describe("Mathematical expression to evaluate"), - precision: tool.schema.number().optional().describe("Decimal precision"), - }, - async execute(args) { - // Your calculation logic here - return `Result: ${eval(args.expression).toFixed(args.precision || 2)}` - }, -}) -``` - ---- - -## Context - -Tools receive context about the current session: - -```ts title=".opencode/tool/project.ts" -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 } = context - return `Agent: ${agent}, Session: ${sessionID}, Message: ${messageID}` - }, -}) -``` |