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 as conversas. Elas funcionam junto às 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.

Local

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

Múltiplas ferramentas por arquivo

Você também pode exportar múltiplas ferramentas de um único arquivo. Cada export 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.

Colisões de nome com ferramentas integradas

As ferramentas personalizadas são indexadas pelo nome da ferramenta. Se uma ferramenta personalizada usar o mesmo nome de uma ferramenta integrada, a ferramenta personalizada tem precedência.

Por exemplo, este arquivo substitui a ferramenta bash integrada:

.opencode/tools/bash.ts

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

Nota: Prefira nomes únicos, a menos que você queira intencionalmente substituir uma ferramenta integrada. Se você quiser desabilitar uma ferramenta integrada, mas não sobrescrevê-la, use permissões.

Argumentos

Você pode usar tool.schema, que é apenas o Zod (opens in a new tab), para definir os tipos dos argumentos.

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

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

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

Exemplos

Escrever uma ferramenta em Python

Você pode escrever suas ferramentas em qualquer linguagem que quiser. 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)

Depois 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