Strumenti personalizzati

Gli strumenti personalizzati sono funzioni che crei che il LLM puo chiamare durante le conversazioni. Lavorano insieme agli strumenti integrati di OpenCode come read, write e bash.

---

Creare uno strumento

Gli strumenti sono definiti come file TypeScript o JavaScript. Tuttavia, la definizione dello strumento puo richiamare script scritti in qualsiasi linguaggio — TypeScript o JavaScript viene usato solo per la definizione dello strumento stesso.

---

Posizione

Possono essere definiti:

• Localmente inserendoli nella directory .opencode/tool/ del tuo progetto.
• Oppure globalmente, inserendoli in ~/.config/opencode/tool/.

---

Struttura

Il modo piu semplice per creare strumenti e usare l’helper tool() che fornisce la sicurezza dei tipi e la convalida.

.opencode/tool/database.ts

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

export default tool({
  description: "Interroga il database del progetto",
  args: {
    query: tool.schema.string().describe("Query SQL da eseguire"),
  },
  async execute(args) {
    // La tua logica di database qui
    return `Query eseguita: ${args.query}`
  },
})

Il nome del file diventa il nome dello strumento. Quanto sopra crea uno strumento database.

---

Pi strumenti per file

Puoi anche esportare pi strumenti da un singolo file. Ogni esportazione diventa uno strumento separato con il nome <nomefile>_<nomeesport> :

.opencode/tool/math.ts

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

export const add = tool({
  description: "Somma due numeri",
  args: {
    a: tool.schema.number().describe("Primo numero"),
    b: tool.schema.number().describe("Secondo numero"),
  },
  async execute(args) {
    return args.a + args.b
  },
})

export const multiply = tool({
  description: "Moltiplica due numeri",
  args: {
    a: tool.schema.number().describe("Primo numero"),
    b: tool.schema.number().describe("Secondo numero"),
  },
  async execute(args) {
    return args.a * args.b
  },
})

Crea due strumenti: math_add e math_multiply.

---

Argomenti

Puoi usare tool.schema, che e semplicemente Zod, per definire i tipi di argomenti.

args: {
  query: tool.schema.string().describe("Query SQL da eseguire")
}

Puoi anche importare Zod direttamente e restituire un oggetto semplice:

import { z } from "zod"

export default {
  description: "Descrizione dello strumento",
  args: {
    param: z.string().describe("Descrizione del parametro"),
  },
  async execute(args, context) {
    // Implementazione dello strumento
    return "risultato"
  },
}

---

Contesto

Gli strumenti ricevono informazioni sulla sessione corrente:

.opencode/tool/project.ts

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

export default tool({
  description: "Ottieni informazioni sul progetto",
  args: {},
  async execute(args, context) {
    // Accedi alle informazioni del contesto
    const { agent, sessionID, messageID } = context
    return `Agente: ${agent}, Sessione: ${sessionID}, Messaggio: ${messageID}`
  },
})

---

Esempi

Scrivere uno strumento in Python

Puoi scrivere i tuoi strumenti in qualsiasi linguaggio tu desideri. Ecco un esempio che aggiunge due numeri usando Python.

Prima, crea lo strumento come script Python:

.opencode/tool/add.py

import sys

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

Poi crea la definizione dello strumento che lo richiama:

.opencode/tool/python-add.ts

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

export default tool({
  description: "Somma due numeri usando Python",
  args: {
    a: tool.schema.number().describe("Primo numero"),
    b: tool.schema.number().describe("Secondo numero"),
  },
  async execute(args) {
    const result = await Bun.$`python3 .opencode/tool/add.py ${args.a} ${args.b}`.text()
    return result.trim()
  },
})

Qui stiamo usando l’utilita Bun.$ per eseguire lo script Python.