Opencode - ensemble
La evolución del desarrollo asistido por Inteligencia Artificial ha pasado de los chats conversacionales genéricos a los agentes autónomos especializados. En el ecosistema de herramientas para la terminal, OpenCode se ha posicionado como un estándar de alto rendimiento gracias a su arquitectura modular de arnés (harness engineering) y su capacidad para ejecutar subagentes en sesiones hijas con contextos totalmente aislados.
Existe un plugin de OpenCode (Opencode-ensemble) en Github que te lo monta todo si quieres agentes para un entorno de desarrollo de softuare. También dispones de este plugin Opencode Multi Agent Suite (oh-my-opencode-slim), pero si quieres aprender como se hacen y hacerlo exactamente a tu medida y que cubra tus necesidades aquí va una guía para ello.
En esta guía práctica aprenderás a diseñar, configurar y desplegar tu propio equipo de agentes en OpenCode utilizando archivos Markdown con encabezados YAML (frontmatter). Además, analizaremos paso a paso dos ejemplos concretos de subagentes esenciales en cualquier flujo de software: un Auditor de Ciberseguridad y un Revisor de Calidad de Código.
1. ¿Por qué Crear Agentes Personalizados en OpenCode?
Cuando utilizas un modelo de lenguaje para todas las tareas del desarrollo (desde leer documentación hasta refactorizar o auditar), te enfrentas a dos grandes problemas:
- Saturación de la Ventana de Contexto: La lectura masiva de archivos y trazas de consola acumula miles de tokens en el historial del chat principal, encareciendo las peticiones y ralentizando las respuestas.
- Falta de Restricciones de Seguridad: Un agente que programa necesita permisos para editar archivos y ejecutar comandos, pero un agente de auditoría o revisión debería funcionar en modo solo lectura para evitar modificaciones no deseadas o comandos destructivos.
OpenCode resuelve esto permitiendo definir agentes con roles, modelos y permisos específicos. Cuando un agente principal delega una tarea a un subagente, este se ejecuta en una sesión hija independiente con el contexto limpio. Al finalizar su trabajo, el subagente se destruye y devuelve únicamente un resumen de alto nivel, manteniendo tu conversación principal ligera y económica.
2. Tipos de Agentes en OpenCode
Antes de escribir el primer archivo de configuración, es fundamental comprender los tres modos de agentes que soporta OpenCode:
Modo (mode) | Mecanismo de Invocación | Gestión de Contexto | Casos de Uso Ideales |
primary | Selección directa por el usuario en la terminal (conmutando con la tecla Tab). | Global: Mantiene la memoria y el hilo principal de la conversación. | Asistente principal de desarrollo (Build), planificación y diseño (Plan). |
subagent | Invocación explícita con @nombre o delegación automática según la descripción. | Aislado: Sesión hija efímera con contexto limpio; retorna solo un resumen. | Tareas acotadas como auditorías, búsquedas, tests, revisiones o refactorizaciones. |
all (Predeterminado) | Funciona como interfaz principal o como trabajador secundario según se requiera. | Adaptable según el punto de entrada. | Agentes híbridos de propósito general. |
3. Estructura y Ubicación de los Archivos de Configuración
En OpenCode, los agentes se definen mediante archivos Markdown .md estructurados en dos partes:
- Encabezado YAML (frontmatter): Contiene los metadatos de configuración (nombre, descripción, modelo, permisos y aleatoriedad).
- Cuerpo del archivo: Funciona directamente como el System Prompt o prompt de sistema que determina la identidad, reglas y comportamiento del agente.
Rutas de almacenamiento
Los agentes se descubren automáticamente en dos niveles de jerarquía:
- A nivel de Proyecto (Local):
.opencode/agents/<nombre>.md(Aplica exclusivamente al repositorio activo). - A nivel Global (Usuario):
~/.config/opencode/agents/<nombre>.md(Disponible en todos los proyectos de tu máquina).
Nota de convención: El nombre del archivo determina el identificador del agente. Por ejemplo, el archivo security-auditor.md crea el agente @security-auditor.
4. Anatomía del Encabezado YAML (Parámetros Disponibles)
Un encabezado YAML bien estructurado permite ajustar con precisión los parámetros operativos del agente:
---
description: "Descripción detallada del propósito del agente. CAMPO OBLIGATORIO."
mode: subagent # primary | subagent | all
model: anthropic/claude-sonnet-4-5 # Anula el modelo global para este agente
temperature: 0.1 # Control de aleatoriedad (0.0 a 1.0)
steps: 15 # Límite máximo de iteraciones del agente
color: "#ff5733" # Color hexadecimal o temático en la TUI
permission: # Reglas de autorización de herramientas
edit: deny
bash:
"*": deny
"git diff*": allow
---
Opciones clave del Frontmatter:
description(Obligatorio): Funciona como el activador semántico. El agente principal lee esta descripción para decidir cuándo delegarle tareas automáticamente.model: Permite asignar modelos potentes a tareas complejas y modelos rápidos/económicos (o locales vía Ollama/llama.cpp) a tareas mecánicas.permission: Define qué herramientas puede usar el agente. Las políticas posibles sonallow(permitir silenciosamente),ask(solicitar confirmación humana) ydeny(bloquear categóricamente).
5. Ejemplos Prácticos de Agentes Personalizados
A continuación, crearemos dos subagentes especializados utilizando la CLI de la terminal.
Ejemplo 1: security-auditor (Auditor de Ciberseguridad)
Este subagente está diseñado para inspeccionar el repositorio en busca de vulnerabilidades, claves o tokens en texto plano y fallos de autorización. Funciona bajo un perfil de seguridad estricto (solo lectura): tiene prohibida la edición de archivos y solo puede ejecutar comandos de inspección específicos como git diff o auditorías de dependencias.
Comando de creación desde la terminal:
# 1. Crear el directorio de agentes globales
mkdir -p ~/.config/opencode/agents
# 2. Escribir el subagente de seguridad
cat << 'EOF' > ~/.config/opencode/agents/security-auditor.md
---
description: Audita el código buscando vulnerabilidades de seguridad, credenciales expuestas y fallos de autorización.
mode: subagent
temperature: 0.1
permission:
edit: deny
bash:
"*": deny
"git diff*": allow
"npm audit*": allow
"pip audit*": allow
---
# Rol: Auditor de Seguridad
Eres un especialista en ciberseguridad y análisis estático de código. Tu objetivo es auditar los cambios recientes y la estructura del proyecto sin modificar ningún archivo en disco.
## Instrucciones de Análisis
1. **Detección de Secretos**: Busca claves de API, tokens OAuth, contraseñas o certificados expuestos en texto plano en el código o archivos de configuración (.env, config.json).
2. **Vulnerabilidades de Código**: Inspecciona inyecciones SQL, Cross-Site Scripting (XSS), fallos de sanitización de entrada y deserialización insegura.
3. **Auditoría de Dependencias**: Analiza el archivo de dependencias del proyecto buscando paquetes obsoletos con vulnerabilidades conocidas (CVE).
## Formato del Reporte
Devuelve un informe conciso clasificado por nivel de riesgo:
- 🔴 **Riesgo Crítico / Alto**: Vulnerabilidades explotables o secretos expuestos.
- 🟡 **Riesgo Medio**: Fallos en la validación de datos o configuraciones laxas.
- 🟢 **Riesgo Bajo / Buenas Prácticas**: Sugerencias de endurecimiento (*hardening*).
NUNCA intentes corregir los archivos directamente. Tu respuesta debe limitarse al diagnóstico.
EOF
Ejemplo 2: code-reviewer (Revisor de Calidad de Código)
Este subagente actúa como un revisor de código senior enfocado en los principios Clean Code, patrones de diseño SOLID y cobertura de pruebas. Al igual que el auditor, opera en modo de solo lectura para analizar el código modificado y emitir recomendaciones estructuradas sin alterar el código fuente.
Comando de creación desde la terminal:
# Escribir el subagente de revisión de código
cat << 'EOF' > ~/.config/opencode/agents/code-reviewer.md
---
description: Revisa cambios de código evaluando calidad, arquitectura, principios SOLID y manejo de errores.
mode: subagent
temperature: 0.1
permission:
edit: deny
bash:
"*": deny
"git diff*": allow
"npm run lint*": allow
"pytest*": allow
---
# Rol: Revisor de Calidad de Código (Code Reviewer)
Eres un Ingeniero de Software Senior. Tu objetivo es revisar los cambios recientes en el repositorio (`git diff`) y evaluar su mantenibilidad, legibilidad y corrección técnica.
## Criterios de Evaluación
1. **Calidad y Principios SOLID**: Evalúa la complejidad ciclomática, duplicación de código y cumplimiento de responsabilidad única.
2. **Manejo de Errores y Excepciones**: Comprueba que las promesas y bloques de código gestionen adecuadamente los fallos sin silenciar excepciones.
3. **Mantenibilidad y Estilo**: Verifica el uso de nombres descriptivos para variables y funciones, así como la coherencia con el linter del proyecto.
## Formato del Salida
Proporciona observaciones estructuradas señalando:
- **Archivo y Línea**: Ubicación exacta del punto a revisar.
- **Observación**: Descripción clara del problema identificado.
- **Sugerencia**: Ejemplo concreto de refactorización o mejora.
Si el cambio cumple con todos los estándares, confirma que el código está listo para ser integrado.
EOF
6. Cómo Utilizar e Invocar tus Subagentes
Una vez creados los archivos Markdown, OpenCode los cargará automáticamente. Tienes dos formas de ejecutarlos durante tu sesión de desarrollo:
1. Invocación Manual (@mention)
Puedes llamar a un subagente de forma explícita en cualquier momento dentro del chat de OpenCode:
> @security-auditor realiza una revisión de los últimos cambios antes de hacer commit
> @code-reviewer evalúa la refactorización realizada en el módulo src/auth.ts
2. Delegación Automática de Tareas
Cuando estés trabajando con un agente primario como Build o con un agente Orquestador, puedes pedirle que audite el código. El agente principal leerá la description de tus subagentes y activará el correspondiente de forma transparente:
> "He terminado de implementar la autenticación. Por favor, comprueba si hay vulnerabilidades de seguridad y revisa la calidad del código."
El agente primario lanzará en paralelo @security-auditor y @code-reviewer en sesiones hijas, recibirá sus resúmenes y te presentará una respuesta consolidada.
7. Buenas Prácticas y Consejos Avanzados
- Aplica el Principio de Mínimo Privilegio: Configura siempre
permission.edit: denyen subagentes cuyo rol sea únicamente el análisis o la auditoría. - Redacta Descripciones Precisas: La propiedad
descriptiones el único texto que lee el agente primario para decidir la delegación. Sé específico sobre el propósito y la activación del subagente. - Limita el Número de Pasos (
steps): Asigna un valor desteps: 10osteps: 15a los subagentes simples para evitar que entren en bucles interminables de búsqueda y controlar el consumo de tokens. - Combina Modelos Según el Coste: Asigna modelos de razonamiento avanzado (como Claude Sonnet o GPT-4o) para el orquestador principal o revisiones complejas, y utiliza modelos más económicos o locales para tareas mecánicas.
Conclusión
La creación de agentes personalizados en OpenCode permite transformar la terminal en un entorno de desarrollo distribuido de alta eficiencia. Al desacoplar la conversación principal de las tareas mecánicas de inspección, no solo proteges la calidad de tu código fuente, sino que optimizas drásticamente el consumo de tokens y el rendimiento de tus herramientas de Inteligencia Artificial.
Acerca del autor
