Benutzerdefinierte Tools

Erstellen Sie Tools, die das LLM in opencode aufrufen kann.

Benutzerdefinierte Tools sind Funktionen, die Sie erstellen und die das LLM während Gesprächen aufrufen kann. Sie arbeiten zusammen mit opencodes integrierten Tools wie read, write und bash.

Ein Tool erstellen

Tools werden als TypeScript- oder JavaScript-Dateien definiert. Die Tool-Definition kann jedoch Skripte aufrufen, die in jeder Sprache geschrieben sind — TypeScript oder JavaScript wird nur für die Tool-Definition selbst verwendet.

Speicherort

Sie können definiert werden:

Lokal, indem Sie sie im .opencode/tools/-Verzeichnis Ihres Projekts platzieren.
Oder global, indem Sie sie in ~/.config/opencode/tools/ platzieren.

Struktur

Der einfachste Weg, Tools zu erstellen, ist die Verwendung des tool()-Helpers, der Typsicherheit und Validierung bietet.

.opencode/tools/database.ts

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}`
  },
})

Der Dateiname wird zum Tool-Namen. Das obige erstellt ein database-Tool.

Mehrere Tools pro Datei

Sie können auch mehrere Tools aus einer einzelnen Datei exportieren. Jeder Export wird zu einem separaten Tool mit dem Namen <filename>_<exportname>:

.opencode/tools/math.ts

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
  },
})

Dies erstellt zwei Tools: math_add und math_multiply.

Argumente

Sie können tool.schema verwenden, das einfach Zod (opens in a new tab) ist, um Argumenttypen zu definieren.

args: {
  query: tool.schema.string().describe("SQL query to execute")
}

Sie können auch Zod (opens in a new tab) direkt importieren und ein einfaches Objekt zurückgeben:

import { z } from "zod"
 
export default {
  description: "Tool description",
  args: {
    param: z.string().describe("Parameter description"),
  },
  async execute(args, context) {
    // Tool implementation
    return "result"
  },
}

Kontext

Tools erhalten Kontext über die aktuelle Sitzung:

.opencode/tools/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, directory, worktree } = context
    return `Agent: ${agent}, Session: ${sessionID}, Message: ${messageID}, Directory: ${directory}, Worktree: ${worktree}`
  },
})

Verwenden Sie context.directory für das Arbeitsverzeichnis der Sitzung. Verwenden Sie context.worktree für das Git-Worktree-Stammverzeichnis.

Beispiele

Ein Tool in Python schreiben

Sie können Ihre Tools in jeder gewünschten Sprache schreiben. Hier ist ein Beispiel, das zwei Zahlen mit Python addiert.

Erstellen Sie zunächst das Tool als Python-Skript:

.opencode/tools/add.py

import sys
 
a = int(sys.argv[1])
b = int(sys.argv[2])
print(a + b)

Erstellen Sie dann die Tool-Definition, die es aufruft:

.opencode/tools/python-add.ts

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()
  },
})

Hier verwenden wir das Bun.$ (opens in a new tab)-Utility, um das Python-Skript auszuführen.

Agent Skills SDK