Capitulo 8: Custom Tools

< Volver al Indice del Tutorial

Las herramientas built-in cubren operaciones generales, pero cada proyecto tiene necesidades unicas. Las custom tools te permiten crear funciones que el LLM puede llamar durante las conversaciones, extendiendo sus capacidades con logica especifica de tu proyecto.

Que son las Custom Tools

Una custom tool es una funcion que defines en la configuracion de OpenCode. Cuando el LLM determina que necesita ejecutar esa funcion, la invoca con los parametros apropiados. Es como darle al LLM acceso a scripts y comandos que tu disenas.

Las custom tools trabajan junto a las herramientas built-in. El LLM elige cual usar segun el contexto de la conversacion.

Definir Custom Tools

Las custom tools se definen en opencode.json bajo la seccion de herramientas personalizadas:

{
  "tools": {
    "mi-tool": {
      "description": "Descripcion de lo que hace la herramienta",
      "command": "comando a ejecutar",
      "parameters": {
        "param1": {
          "type": "string",
          "description": "Descripcion del parametro"
        }
      }
    }
  }
}

Cada tool necesita:

• description: Texto que el LLM lee para decidir cuando usar la herramienta
• command: El comando o script que se ejecuta
• parameters: Parametros que el LLM puede pasar al comando

Casos de Uso

Integrar con APIs Internas

Conectar el LLM con servicios internos de tu organizacion:

• Consultar el estado de un servicio
• Obtener informacion de una base de datos interna
• Interactuar con herramientas de gestion de proyectos

Ejecutar Scripts Especificos

Automatizar tareas recurrentes del proyecto:

• Correr suites de tests con configuracion especifica
• Ejecutar migraciones de base de datos
• Generar reportes de cobertura

Conectar con Servicios Propios

Extender el flujo de trabajo con servicios externos:

• Deploy a ambientes de staging o produccion
• Notificar a canales de comunicacion
• Actualizar dashboards o metricas

Custom Tools vs MCP

Es importante entender la diferencia:

Aspecto	Custom Tools	MCP
Complejidad	Simple, un comando	Protocolo completo con servidor
Scope	Local al proyecto	Estandarizado, compartible
Configuracion	Solo opencode.json	Requiere servidor MCP
Uso ideal	Scripts y comandos locales	Integraciones complejas y reutilizables

Custom tools son la opcion rapida y simple para necesidades locales. MCP (Model Context Protocol) es el protocolo estandarizado para integraciones mas complejas y compartibles entre proyectos y herramientas.

Si tu necesidad es ejecutar un script o comando, usa custom tools. Si necesitas una integracion robusta con un servicio externo que multiples proyectos podrian usar, considera MCP.

Configurar Permisos

Las custom tools siguen el mismo sistema de permisos que las built-in:

{
  "tools": {
    "run-tests": {
      "description": "Ejecuta la suite de tests del proyecto",
      "command": "npm test",
      "permission": "allow"
    },
    "deploy-staging": {
      "description": "Despliega a staging",
      "command": "scripts/deploy.sh staging",
      "permission": "ask"
    }
  }
}

• allow: la herramienta se ejecuta sin confirmacion (para operaciones seguras)
• ask: pide confirmacion antes de ejecutar (para operaciones con efectos secundarios)
• deny: deshabilita la herramienta temporalmente

Ejemplo: Tool para Tests

Una herramienta para ejecutar tests de un framework especifico con opciones comunes:

{
  "tools": {
    "test": {
      "description": "Ejecuta tests. Puede correr todos los tests, un archivo especifico o tests que coincidan con un patron",
      "command": "bun test",
      "permission": "allow",
      "parameters": {
        "file": {
          "type": "string",
          "description": "Archivo o patron de test a ejecutar. Ejemplo: auth.test.ts",
          "required": false
        },
        "watch": {
          "type": "boolean",
          "description": "Ejecutar en modo watch",
          "required": false
        }
      }
    }
  }
}

Con esta herramienta, puedes decirle al LLM:

• “Corre los tests” → ejecuta bun test
• “Corre los tests de autenticacion” → ejecuta bun test auth.test.ts
• “Corre los tests en modo watch” → ejecuta bun test --watch

El LLM mapea tu instruccion en lenguaje natural a los parametros correctos.

Ejemplo: Tool para Deploy a Staging

Una herramienta controlada para despliegues:

{
  "tools": {
    "deploy-staging": {
      "description": "Despliega la rama actual al ambiente de staging. Ejecuta build, tests y luego el deploy. Requiere confirmacion del usuario",
      "command": "scripts/deploy.sh",
      "permission": "ask",
      "parameters": {
        "environment": {
          "type": "string",
          "description": "Ambiente de deploy: staging o preview",
          "required": true
        },
        "skip-tests": {
          "type": "boolean",
          "description": "Omitir tests antes del deploy",
          "required": false
        }
      }
    }
  }
}

El permiso ask asegura que siempre veras una confirmacion antes de que se ejecute el deploy. La descripcion detallada ayuda al LLM a saber cuando sugerir esta herramienta.

Buenas Practicas

• Descripciones claras: el LLM decide cuando usar la herramienta basandose en la descripcion. Se especifico.
• Permisos apropiados: usa allow solo para operaciones de solo lectura o sin efectos secundarios
• Parametros opcionales: marca como required: false los parametros que tienen defaults razonables
• Idempotencia: disenar tools que puedan ejecutarse multiples veces sin efectos inesperados
• Validacion en el script: agrega validaciones en tus scripts, no dependas solo del LLM para pasar parametros correctos
• Logging: que tus scripts impriman informacion clara sobre lo que hacen para que el LLM pueda interpretar el resultado

---

Siguiente: Capitulo 9: Proveedores Cloud —>