File size: 5,451 Bytes
3e05655 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 | ---
title: Ferramentas Personalizadas
description: 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 com as [ferramentas integradas](/docs/tools) 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.
```ts title=".opencode/tools/database.ts" {1}
import { tool } from "@opencode-ai/plugin"
export default tool({
description: "Consultar o banco de dados do projeto",
args: {
query: tool.schema.string().describe("Consulta SQL para executar"),
},
async execute(args) {
// Sua lógica de banco de dados aqui
return `Consulta executada: ${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>`**:
```ts title=".opencode/tools/math.ts"
import { tool } from "@opencode-ai/plugin"
export const add = tool({
description: "Adicionar dois números",
args: {
a: tool.schema.number().describe("Primeiro número"),
b: tool.schema.number().describe("Segundo número"),
},
async execute(args) {
return args.a + args.b
},
})
export const multiply = tool({
description: "Multiplicar dois números",
args: {
a: tool.schema.number().describe("Primeiro número"),
b: tool.schema.number().describe("Segundo número"),
},
async execute(args) {
return args.a * args.b
},
})
```
Isso cria duas ferramentas: `math_add` e `math_multiply`.
---
#### Colisões de nome com ferramentas integradas
Ferramentas personalizadas são chaveadas pelo nome da ferramenta. Se uma ferramenta personalizada usar o mesmo nome que uma ferramenta integrada, a ferramenta personalizada tem precedência.
Por exemplo, este arquivo substitui a ferramenta `bash` integrada:
```ts title=".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}`
},
})
```
:::note
Prefira nomes únicos, a menos que você queira intencionalmente substituir uma ferramenta integrada. Se você quiser desabilitar uma ferramenta integrada, mas não substituí-la, use [permissões](/docs/permissions).
:::
---
### Argumentos
Você pode usar `tool.schema`, que é apenas [Zod](https://zod.dev), para definir tipos de argumentos.
```ts "tool.schema"
args: {
query: tool.schema.string().describe("Consulta SQL para executar")
}
```
Você também pode importar [Zod](https://zod.dev) diretamente e retornar um objeto simples:
```ts {6}
import { z } from "zod"
export default {
description: "Descrição da ferramenta",
args: {
param: z.string().describe("Descrição do parâmetro"),
},
async execute(args, context) {
// Implementação da ferramenta
return "result"
},
}
```
---
### Contexto
As ferramentas recebem contexto sobre a sessão atual:
```ts title=".opencode/tools/project.ts" {8}
import { tool } from "@opencode-ai/plugin"
export default tool({
description: "Obter informações do projeto",
args: {},
async execute(args, context) {
// Acessar informações de contexto
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
### Escrevendo 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:
```python title=".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:
```ts title=".opencode/tools/python-add.ts" {10}
import { tool } from "@opencode-ai/plugin"
import path from "path"
export default tool({
description: "Adicionar dois números usando Python",
args: {
a: tool.schema.number().describe("Primeiro número"),
b: tool.schema.number().describe("Segundo número"),
},
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.$`](https://bun.com/docs/runtime/shell) para executar o script Python.
|