Docs/Configuração e automação/Ferramentas personalizadas

Ferramentas com
a sua assinatura.

Funções suas que o modelo chama durante a conversa — com schema tipado, validação e contexto de sessão. A definição é TypeScript; a execução pode invocar qualquer linguagem.

Disponível agoraHow-to /custom-tools1 min de leitura

01Onde ficam

Escopo	Caminho
Projeto	.maxvision-code/tools/
Global	~/.config/<dir>/tools/

O nome do arquivo vira o nome da ferramenta — database.ts cria a ferramenta database.

02Estrutura

O helper tool() dá type-safety e validação de argumentos via Zod:

.maxvision-code/tools/database.tsts

import { tool } from "@maxvision/plugin"

export default tool({
  description: "Consulta o banco do projeto",
  args: {
    query: tool.schema.string().describe("SQL a executar"),
  },
  async execute(args) {
    // sua lógica aqui
    return `Executado: ${args.query}`
  },
})

03Várias ferramentas por arquivo

Cada export nomeado vira uma ferramenta com o nome <arquivo>_<export>:

.maxvision-code/tools/math.tsts

export const add = tool({ /* … */ })       // → math_add
export const multiply = tool({ /* … */ })  // → math_multiply

Colisão de nomes

Uma ferramenta customizada com o nome de uma embarcada a substitui — bash.ts troca o bash nativo. Faça isso apenas de propósito; para só bloquear uma ferramenta, prefira permissões.

04Contexto da sessão

O segundo argumento de execute traz o contexto do turno:

contextots

async execute(args, context) {
  const { agent, sessionID, messageID, directory, worktree } = context
  // directory = diretório de trabalho da sessão
  // worktree  = raiz do worktree Git
}

05Qualquer linguagem na execução

A definição TypeScript pode delegar para um script em qualquer linguagem:

.maxvision-code/tools/python-add.tsts

import { tool } from "@maxvision/plugin"
import path from "path"

export default tool({
  description: "Soma dois números via Python",
  args: { a: tool.schema.number(), b: tool.schema.number() },
  async execute(args, context) {
    const script = path.join(context.worktree, ".maxvision-code/tools/add.py")
    const result = await Bun.$`python3 ${script} ${args.a} ${args.b}`.text()
    return result.trim()
  },
})

06Permissões da ferramenta

Ferramentas customizadas entram no mesmo contrato das nativas — o nome delas é a chave em permission:

maxvision-code.jsonjson

{
  "permission": { "database": "ask", "math_*": "allow" }
}