Pular para o conteúdo

Ferramentas Personalizadas

Crie ferramentas que o LLM pode chamar em opencode.

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


Criando uma ferramenta

As 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 tipo 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 acima cria uma ferramenta database.


Múltiplas ferramentas por arquivo

Você também pode exportar várias 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 é apenas Zod, para definir tipos de argumentos.

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

Você também pode importar Zod 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

As 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 worktree do git.


Exemplos

Escreva uma ferramenta em Python

Você pode escrever suas ferramentas em qualquer linguagem que desejar. Aqui está um exemplo que adiciona 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)

Em seguida, crie a definição da ferramenta que a 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.$ para executar o script Python.