Herramientas personalizadas

Las herramientas personalizadas son funciones que creas que el LLM puede llamar durante las conversaciones. Funcionan junto con las herramientas integradas de OpenCode como read, write y bash.

---

Crear una herramienta

Las herramientas se definen como archivos TypeScript o JavaScript. Sin embargo, la definicion de la herramienta puede invocar scripts escritos en cualquier idioma — TypeScript o JavaScript solo se usa para la definicion de la herramienta en si.

---

Ubicacion

Pueden definirse:

• Localmente colocandolas en el directorio .opencode/tool/ de tu proyecto.
• O globalmente, colocandolas en ~/.config/opencode/tool/.

---

Estructura

La forma mas facil de crear herramientas es usar el asistente tool() que proporciona seguridad de tipos y validacion.

.opencode/tool/database.ts

import { tool } from "@opencode-ai/plugin"

export default tool({
  description: "Consultar la base de datos del proyecto",
  args: {
    query: tool.schema.string().describe("Consulta SQL a ejecutar"),
  },
  async execute(args) {
    // Tu logica de base de datos aqui
    return `Consulta ejecutada: ${args.query}`
  },
})

El nombre de archivo se convierte en el nombre de la herramienta. Lo anterior crea una herramienta database.

---

Varias herramientas por archivo

También puedes exportar varias herramientas desde un solo archivo. Cada exportacion se convierte en una herramienta separada con el nombre <nombrearchivo>_<nombreexport> :

.opencode/tool/math.ts

import { tool } from "@opencode-ai/plugin"

export const add = tool({
  description: "Sumar dos numeros",
  args: {
    a: tool.schema.number().describe("Primer numero"),
    b: tool.schema.number().describe("Segundo numero"),
  },
  async execute(args) {
    return args.a + args.b
  },
})

export const multiply = tool({
  description: "Multiplicar dos numeros",
  args: {
    a: tool.schema.number().describe("Primer numero"),
    b: tool.schema.number().describe("Segundo numero"),
  },
  async execute(args) {
    return args.a * args.b
  },
})

Esto crea dos herramientas: math_add y math_multiply.

---

Argumentos

Puedes usar tool.schema, que es simplemente Zod, para definir tipos de argumentos.

args: {
  query: tool.schema.string().describe("Consulta SQL a ejecutar")
}

También puedes importar Zod directamente y devolver un objeto simple:

import { z } from "zod"

export default {
  description: "Descripcion de la herramienta",
  args: {
    param: z.string().describe("Descripcion del parametro"),
  },
  async execute(args, context) {
    // Implementacion de la herramienta
    return "resultado"
  },
}

---

Contexto

Las herramientas reciben informacion sobre la sesion actual:

.opencode/tool/project.ts

import { tool } from "@opencode-ai/plugin"

export default tool({
  description: "Obtener informacion del proyecto",
  args: {},
  async execute(args, context) {
    // Acceder a la informacion del contexto
    const { agent, sessionID, messageID } = context
    return `Agente: ${agent}, Sesion: ${sessionID}, Mensaje: ${messageID}`
  },
})

---

Ejemplos

Escribir una herramienta en Python

Puedes escribir tus herramientas en cualquier idioma que desees. Aqui tienes un ejemplo que suma dos numeros usando Python.

Primero, crea la herramienta como un script Python:

.opencode/tool/add.py

import sys

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

Luego crea la definicion de la herramienta que lo invoca:

.opencode/tool/python-add.ts

import { tool } from "@opencode-ai/plugin"

export default tool({
  description: "Sumar dos numeros usando Python",
  args: {
    a: tool.schema.number().describe("Primer numero"),
    b: tool.schema.number().describe("Segundo numero"),
  },
  async execute(args) {
    const result = await Bun.$`python3 .opencode/tool/add.py ${args.a} ${args.b}`.text()
    return result.trim()
  },
})

Aqui estamos usando la utilidad Bun.$ para ejecutar el script Python.