Ferramentas Personalizadas

Crie ferramentas que o LLM pode chamar no opencode.

Ferramentas personalizadas são funções que você cria e que o LLM pode chamar durante conversas. Elas funcionam junto com as ferramentas integradas do opencode como read, write e bash.

Criando uma ferramenta

Ferramentas são definidas como arquivos TypeScript ou JavaScript. No entanto, a definição da ferramenta pode invocar scripts escritos em qualquer linguagem — TypeScript ou JavaScript é usado apenas para a definição da ferramenta em si.

Localização

Elas podem ser definidas:

Localmente, colocando-as no diretório .opencode/tools/ do seu projeto.
Ou globalmente, colocando-as em ~/.config/opencode/tools/.

Estrutura

A maneira mais fácil de criar ferramentas é usando o helper tool() que fornece segurança de tipos e validação.

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

O nome do arquivo se torna o nome da ferramenta. O código acima cria uma ferramenta database.

Múltiplas ferramentas por arquivo

Você também pode exportar múltiplas ferramentas de um único arquivo. Cada exportação se torna uma ferramenta separada com o nome <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
  },
})

Isso cria duas ferramentas: math_add e math_multiply.

Argumentos

Você pode usar tool.schema, que é simplesmente Zod (opens in a new tab), para definir tipos de argumentos.

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

Você também pode importar Zod (opens in a new tab) diretamente e retornar um objeto simples:

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

Contexto

Ferramentas recebem contexto sobre a sessão atual:

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

Use context.directory para o diretório de trabalho da sessão. Use context.worktree para a raiz do git worktree.

Exemplos

Escrever uma ferramenta em Python

Você pode escrever suas ferramentas em qualquer linguagem que desejar. Aqui está um exemplo que soma dois números usando Python.

Primeiro, crie a ferramenta como um script Python:

.opencode/tools/add.py

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

Então crie a definição da ferramenta que o invoca:

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

Aqui estamos usando o utilitário Bun.$ (opens in a new tab) para executar o script Python.

Habilidades de Agente SDK