Capitulo 6: Agentes Custom

< Volver al Indice del Tutorial

Los agentes built-in cubren los casos de uso generales, pero los proyectos reales tienen necesidades específicas que no se pueden resolver con agentes genéricos. OpenCode permite crear agentes custom con prompts, herramientas, permisos y modelos personalizados, dándote control total sobre el comportamiento de cada agente.

Por qué Crear Agentes Custom

Cada proyecto tiene flujos de trabajo únicos. Un proyecto de microservicios necesita agentes diferentes a una aplicación mobile o un sitio estático. Con agentes custom puedes codificar ese conocimiento específico una sola vez y reutilizarlo en cada sesión.

Ejemplos de agentes especializados:

• Review: un agente de solo lectura especializado en code review que busca bugs, code smells y problemas de seguridad
• Debug: un agente con acceso a logs y herramientas de depuración que sigue un protocolo sistemático de diagnóstico
• Docs: un agente que solo puede escribir documentación, manteniendo consistencia de estilo y formato
• Testing: un agente enfocado en crear y ejecutar tests con conocimiento de los frameworks del proyecto
• Deploy: un agente con comandos específicos de despliegue y validaciones pre-deploy
• Security: un agente de auditoría que analiza vulnerabilidades sin capacidad de modificar código

En lugar de explicar el contexto cada vez que inicias una sesión, lo defines una vez en la configuración del agente. El system prompt, las herramientas habilitadas y los permisos quedan fijos, garantizando consistencia en cada invocación.

Dos Formas de Configurar

OpenCode ofrece dos métodos complementarios para definir agentes custom. Ambos son igualmente válidos y la elección depende de la complejidad del agente y tus preferencias de organización.

1. JSON (opencode.json)

Define agentes directamente en el archivo de configuración del proyecto. Ideal para agentes con prompts cortos o cuando quieres toda la configuración centralizada en un solo lugar.

{
  "agent": {
    "review": {
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-4-20250514",
      "description": "Reviews code for best practices",
      "temperature": 0.3,
      "steps": 50,
      "color": "blue",
      "permission": {
        "edit": "deny",
        "bash": "deny"
      }
    }
  }
}

Este formato es compacto y permite ver toda la configuración del proyecto de un vistazo. La clave del objeto (review en este caso) se convierte en el nombre del agente para invocarlo.

2. Markdown (archivos .md)

Define agentes como archivos Markdown individuales. Es la mejor opción para agentes con prompts largos o cuando quieres versionarlos de forma independiente. El contenido Markdown después del frontmatter se usa como el system prompt del agente.

---
description: Auditoria de seguridad
mode: subagent
permission:
  edit: deny
  bash: deny
---
Analiza vulnerabilidades y riesgos de seguridad.
Revisa inputs sin sanitizar, secretos expuestos y dependencias desactualizadas.
NUNCA modifiques archivos. Solo reporta hallazgos.

La ventaja del formato Markdown es que el system prompt puede ser tan largo y detallado como necesites, con formato rico que incluye listas, secciones y ejemplos. Esto es crucial para agentes especializados que necesitan instrucciones elaboradas.

Wizard Interactivo

La forma más fácil de crear un agente custom es usando el wizard integrado:

opencode agent create

Este comando te guía paso a paso para configurar:

1. Nombre del agente: identificador único para invocarlo
2. Descripción: texto que aparece en la interfaz y que el LLM lee
3. Modo: primario (Tab) o subagente (@mention)
4. Herramientas habilitadas: qué puede y qué no puede hacer
5. System prompt: instrucciones específicas para el agente
6. Ubicación del archivo: global o por proyecto

El wizard genera el archivo Markdown en la ubicación correcta, listo para usar. Es la forma recomendada para tu primer agente custom.

Ubicación de Archivos

Los agentes en formato Markdown se pueden ubicar en dos niveles, siguiendo el patrón de configuración global vs. proyecto que OpenCode usa consistentemente.

Global (todos los proyectos)

~/.config/opencode/agents/mi-agente.md

Disponible en cualquier proyecto donde uses OpenCode. Ideal para agentes genéricos que usas en todos tus proyectos, como un reviewer general o un agente de documentación con tu estilo personal.

Por Proyecto

.opencode/agents/mi-agente.md

Solo disponible en ese proyecto específico. Los agentes de proyecto tienen prioridad sobre los globales si comparten el mismo nombre. Esto permite personalizar un agente global para las necesidades específicas de un proyecto.

Esta jerarquía de prioridad es poderosa: puedes tener un agente review global con tus estándares generales y un review por proyecto que añade reglas específicas del framework o las convenciones del equipo.

flowchart TD
    A[Busca agente por nombre] --> B{Existe en proyecto?}
    B -->|Si| C[".opencode/agents/nombre.md"]
    B -->|No| D{Existe global?}
    D -->|Si| E["~/.config/opencode/agents/nombre.md"]
    D -->|No| F{Existe en opencode.json?}
    F -->|Si| G[Configuracion JSON]
    F -->|No| H[Agente no encontrado]

Opciones de Configuración

Cada agente custom acepta un conjunto completo de opciones que controlan su comportamiento, modelo, permisos y apariencia.

Opciones Básicas

Opción	Requerido	Descripción
description	Sí	Descripción del agente mostrada en la interfaz
mode	No	primary, subagent o all (default: all)
prompt	No	System prompt personalizado (en JSON; en Markdown es el cuerpo)

Modelo y Parámetros

Opción	Default	Descripción
model	Hereda del padre	Override del modelo LLM para este agente
temperature	Depende del modelo	Creatividad de las respuestas (0.0 - 1.0)
top_p	Depende del modelo	Diversidad del muestreo
steps	Sin límite	Número máximo de iteraciones del agente

La opción model es especialmente útil para asignar modelos más económicos a agentes que no necesitan máxima capacidad. Por ejemplo, un agente de títulos puede usar un modelo rápido y barato, mientras que un agente de review complejo puede usar el modelo más capaz disponible.

La opción steps limita cuántas iteraciones puede hacer el agente. Es una medida de seguridad para evitar que un agente entre en un bucle infinito o consuma demasiados tokens en una sola tarea.

Herramientas y Permisos

Opción	Descripción
tools	Lista de herramientas habilitadas con su nivel de permiso
permission	Permisos globales por herramienta: ask, allow o deny

Los permisos se definen por herramienta individual, dándote control granular sobre lo que cada agente puede hacer. Esto implementa el principio de mínimo privilegio: cada agente solo tiene acceso a lo que necesita.

Apariencia

Opción	Descripción
color	Color del agente en la interfaz TUI
hidden	Si es true, el agente no aparece en la lista visible

Modos de Agente

El modo determina cómo se accede al agente:

• primary: Aparece como opción principal junto a Build y Plan. Se cicla con la tecla Tab. Ideal para agentes que usas frecuentemente como alternativa a Build o Plan.
• subagent: Se invoca con @nombre desde otro agente. Se ejecuta como sesión hija independiente. Ideal para tareas delegadas.
• all: Funciona en ambos modos. Puedes acceder vía Tab o via @nombre. Es el modo por defecto y el más flexible.

flowchart LR
    subgraph Primarios
        A[Build] <-->|Tab| B[Plan]
        B <-->|Tab| C[Review custom]
    end
    subgraph Subagentes
        D["@general"]
        E["@explore"]
        F["@docs custom"]
    end
    A -->|"@docs"| F
    B -->|"@general"| D
    C -->|"@explore"| E

Ejemplo Completo: Agente Review en JSON

Un agente de code review que solo puede leer archivos y buscar, sin capacidad de modificar nada:

{
  "agent": {
    "review": {
      "description": "Code reviewer - analiza codigo sin modificar",
      "mode": "primary",
      "model": "anthropic/claude-sonnet-4-20250514",
      "temperature": 0.3,
      "steps": 50,
      "color": "blue",
      "prompt": "Eres un reviewer experto. Analiza el codigo buscando bugs, problemas de seguridad, code smells y oportunidades de mejora. NUNCA modifiques archivos.",
      "permission": {
        "read": "allow",
        "grep": "allow",
        "glob": "allow",
        "list": "allow",
        "write": "deny",
        "edit": "deny",
        "bash": "deny"
      }
    }
  }
}

Con temperature: 0.3 el agente es más determinista y consistente en sus análisis. Con steps: 50 limitamos las iteraciones para que no se extienda indefinidamente. Con color: "blue" lo diferenciamos visualmente de los otros agentes.

Al definirlo como primary, puedes cambiar a él con Tab y pedirle que revise archivos o secciones del codebase con la tranquilidad de que no modificará nada gracias a los permisos deny en write, edit y bash.

Ejemplo Completo: Agente Review en Markdown

El mismo agente definido como archivo .opencode/agents/review.md:

---
description: "Code reviewer - analiza codigo sin modificar"
mode: primary
model: "anthropic/claude-sonnet-4-20250514"
temperature: 0.3
steps: 50
color: blue
permission:
  read: allow
  grep: allow
  glob: allow
  list: allow
  write: deny
  edit: deny
  bash: deny
---

Eres un reviewer experto. Analiza el código buscando:

## Checklist de Review

- **Bugs**: errores lógicos, condiciones de carrera, null references
- **Seguridad**: inputs sin sanitizar, secretos hardcodeados, inyecciones SQL/XSS
- **Code smells**: funciones largas, duplicación, acoplamiento excesivo
- **SOLID**: violaciones de responsabilidad única, inversión de dependencias
- **Performance**: queries N+1, renders innecesarios, cálculos repetidos

## Formato de Reporte

Para cada hallazgo reporta:
1. Archivo y línea
2. Severidad (crítica/alta/media/baja)
3. Descripción del problema
4. Sugerencia de corrección

NUNCA modifiques archivos. Solo reporta tus hallazgos.

La ventaja del formato Markdown es evidente: el system prompt puede incluir estructura rica con secciones, listas y formato que sería incómodo en JSON. Para agentes con instrucciones detalladas, Markdown es claramente superior.

Ejemplo: Agente Docs (Subagente)

Un agente especializado en crear y editar documentación:

{
  "agent": {
    "docs": {
      "description": "Escritor de documentacion tecnica",
      "mode": "subagent",
      "prompt": "Eres un tecnico especializado en documentacion. Crea y actualiza archivos de documentacion. Solo trabaja con archivos .md, .mdx y .txt.",
      "permission": {
        "read": "allow",
        "write": "allow",
        "edit": "allow",
        "grep": "allow",
        "glob": "allow",
        "list": "allow",
        "bash": "deny"
      }
    }
  }
}

Invocar con:

@docs crea la documentación para el módulo de autenticación

Al ser subagente, se ejecuta en una sesión hija. Puedes seguir trabajando en tu sesión principal mientras el agente docs genera la documentación en paralelo.

Configurar el Agente por Defecto

Puedes cambiar el agente que se activa al iniciar OpenCode:

{
  "default_agent": "plan"
}

Esto es útil si prefieres empezar siempre en modo análisis antes de implementar. El default_agent acepta cualquier nombre de agente, incluyendo los custom que hayas definido.

Buenas Prácticas

Principio de Mínimo Privilegio

Deshabilita herramientas que el agente no necesita. Un agente de review no necesita write ni bash. Un agente de docs no necesita bash. Cuantas menos herramientas tenga un agente, menor es el riesgo de acciones no deseadas y más enfocado es su comportamiento.

Prompts Claros y Específicos

Describe exactamente qué debe y qué no debe hacer el agente. Los LLMs siguen mejor instrucciones explícitas. Incluye:

• El rol del agente (“Eres un reviewer experto”)
• Lo que debe hacer (analizar, reportar, crear)
• Lo que NO debe hacer (“NUNCA modifiques archivos”)
• El formato esperado de salida (checklists, reportes, código)

Agentes de Proyecto en Git

Prefiere .opencode/agents/ para agentes específicos del proyecto y versiónalos con git. Así todo el equipo tiene los mismos agentes disponibles y los cambios en las instrucciones quedan rastreados en el historial del repositorio.

Nombres Descriptivos

Usa nombres que indiquen claramente el propósito del agente. review, docs, deploy-staging son buenos nombres. agent1, helper, custom no lo son.

Limita Steps para Agentes Focalizados

Agentes como review o docs no deberían iterar indefinidamente. Limitar steps a 30-50 evita bucles costosos y fuerza al agente a ser conciso y directo.

Elige el Modelo Apropiado

No todos los agentes necesitan el modelo más caro. Un agente de títulos o formateo puede usar un modelo rápido y económico. Reserva los modelos premium para agentes de review complejo o investigación profunda.

---

Siguiente: Capitulo 7: Herramientas Built-in —>