Capitulo 5: Agentes Built-in

< Volver al Indice del Tutorial

OpenCode incluye 4 agentes integrados organizados en dos categorías: agentes primarios que usas directamente en la conversación principal y subagentes que invocas bajo demanda para tareas específicas. Además, cuenta con agentes ocultos que corren automáticamente en segundo plano para mantener la experiencia fluida.

Entender cómo funciona cada agente y cuándo usarlo es fundamental para aprovechar OpenCode al máximo. La diferencia entre un flujo de trabajo productivo y uno caótico muchas veces radica en elegir el agente correcto para cada fase del desarrollo.

Arquitectura de Agentes

OpenCode organiza sus agentes en tres categorías bien definidas:

graph TD
    A[Agentes OpenCode] --> B[Primarios]
    A --> C[Subagentes]
    A --> D[Ocultos]
    B --> E[Build - Default]
    B --> F[Plan - Restringido]
    C --> G[General - Multi-paso]
    C --> H[Explore - Solo lectura]
    D --> I[Compaction]
    D --> J[Title]
    D --> K[Summary]
    style B fill:#4CAF50,color:#fff
    style C fill:#2196F3,color:#fff
    style D fill:#9E9E9E,color:#fff

• Agentes primarios: Build y Plan. Son los que usas directamente en la conversación principal. Ciclas entre ellos con la tecla Tab.
• Subagentes: General y Explore. Se invocan desde un agente primario mediante la sintaxis @mention.
• Agentes ocultos: Compaction, Title y Summary. Corren de forma transparente sin intervención del usuario.

Esta separación no es arbitraria. Refleja una filosofía de diseño donde cada agente tiene un ámbito de responsabilidad claro, lo que evita que un solo agente acumule demasiado contexto o ejecute acciones fuera de su propósito.

Agentes Primarios

Los agentes primarios son los que controlas directamente. Siempre hay uno activo en tu sesión y puedes alternar entre ellos con la tecla Tab. Son el punto de entrada principal para toda interacción con OpenCode.

Build (Default)

Build es el agente principal y el que se activa por defecto al iniciar OpenCode. Tiene acceso total a todas las herramientas: lectura, escritura, edición de archivos, ejecución de comandos bash y todo lo necesario para desarrollo activo.

Capacidades completas:

• Leer archivos y rangos de líneas específicos
• Escribir archivos nuevos y sobrescribir existentes
• Editar archivos con reemplazos exactos de texto
• Ejecutar comandos shell (compilar, tests, git, etc.)
• Buscar con regex y patrones glob en el codebase
• Aplicar patches y diffs
• Consultar documentación web
• Gestionar listas de tareas

Cuándo usarlo:

• Desarrollo activo de funcionalidades nuevas
• Corrección de bugs y errores
• Refactorización de código existente
• Cualquier tarea que requiera modificar archivos o ejecutar comandos
• Integración de dependencias y configuración de proyectos

Build es el agente que más usarás en el día a día. Su acceso irrestricto lo hace ideal para sesiones de codificación donde necesitas iterar rápidamente entre escribir código, ejecutar tests y corregir errores. No tiene restricciones artificiales: si necesitas hacer algo, Build puede hacerlo.

Sin embargo, esa misma potencia es razón para ser consciente de cuándo no usarlo. Si estás explorando opciones o planificando antes de implementar, el agente Plan es más apropiado porque elimina el riesgo de modificaciones accidentales.

Plan

Plan es un agente restringido por diseño orientado al análisis y la planificación. Sus herramientas de edición (edit) y ejecución (bash) están configuradas en modo “ask” por defecto, lo que significa que antes de realizar cualquier modificación o ejecutar cualquier comando, el agente te pedirá aprobación explícita.

Esta restricción es intencional. Plan existe para las fases donde necesitas pensar antes de actuar: analizar un codebase desconocido, evaluar alternativas de diseño o crear un plan de trabajo antes de implementar.

Capacidades:

• Leer archivos y explorar el codebase libremente
• Buscar con regex y patrones glob sin restricciones
• Listar directorios y explorar estructura del proyecto
• Ejecutar bash y editar archivos solo con aprobación del usuario

Cuándo usarlo:

• Diseñar una arquitectura antes de implementarla
• Analizar un codebase que no conoces
• Evaluar opciones técnicas y tradeoffs
• Crear planes de trabajo detallados
• Revisar código existente para entender su funcionamiento
• Investigar la causa raíz de un bug antes de corregirlo

La ventaja de Plan no es solo técnica sino también cognitiva. Al saber que el agente no va a modificar nada sin tu aprobación, puedes explorar ideas libremente sin preocuparte por efectos secundarios. Esto fomenta un flujo de trabajo más deliberado donde primero entiendes el problema y luego actúas.

Diferencia clave con Build: Build ejecuta acciones directamente cuando el modelo lo decide. Plan requiere tu confirmación para cualquier acción que modifique el sistema. Esto no significa que Plan no pueda modificar nada, sino que siempre te preguntará antes de hacerlo.

Cambiar entre Build y Plan

Presiona Tab para alternar entre los agentes Build y Plan. El indicador en la interfaz muestra cuál está activo en todo momento.

stateDiagram-v2
    [*] --> Build: Inicio
    Build --> Plan: Tab
    Plan --> Build: Tab
    Build --> Build: Desarrollo activo
    Plan --> Plan: Analisis y planificacion

Este flujo cíclico es natural y refleja cómo trabajamos los desarrolladores:

1. Empiezas en Plan para entender el problema
2. Cambias a Build con Tab para implementar la solución
3. Vuelves a Plan si necesitas replantear algo o analizar un error inesperado
4. Regresas a Build para continuar la implementación

La transición es instantánea y mantiene el contexto de la conversación. No pierdes el historial ni el estado al cambiar de agente. Esto permite una alternancia fluida entre las fases de pensamiento y ejecución.

Subagentes

Los subagentes se invocan desde un agente primario usando la sintaxis @nombre. Se ejecutan como una sesión hija con su propio contexto independiente, lo que significa que tienen su propia ventana de conversación separada de la sesión principal.

La principal ventaja de los subagentes es la delegación. Puedes lanzar un subagente para que investigue algo mientras tú continúas trabajando en la sesión principal. Además, los subagentes pueden ejecutarse en paralelo: puedes lanzar múltiples @general simultáneamente para diferentes tareas.

General

General es un subagente con acceso completo a todas las herramientas, similar a Build. Está diseñado para tareas complejas de múltiples pasos que requieren investigación y ejecución autónoma.

La diferencia con Build es que General opera en una sesión hija independiente. Esto es útil cuando quieres delegar una tarea compleja sin contaminar el contexto de tu conversación principal.

Invocar:

@general investiga cómo funciona el sistema de autenticación y crea un diagrama

Cuándo usarlo:

• Investigación profunda que requiere leer múltiples archivos y correlacionar información
• Tareas de múltiples pasos donde quieres delegar trabajo completo
• Ejecución paralela: lanza varios @general simultáneamente para diferentes aspectos de un problema
• Tareas que generarían demasiado ruido en la conversación principal

Ejemplo de uso paralelo:

@general analiza las dependencias del módulo de pagos
@general investiga cómo se manejan los errores en el módulo de usuarios
@general revisa la configuración de CI/CD del proyecto

Los tres subagentes trabajan simultáneamente. Puedes navegar a cada sesión hija para revisar su progreso individual.

Nota importante: General tiene acceso completo excepto la herramienta “all”. Esto significa que puede leer, escribir, ejecutar comandos y hacer prácticamente todo lo que Build puede hacer, pero siempre como sesión delegada.

Explore

Explore es un subagente de solo lectura optimizado para velocidad y seguridad. No puede modificar archivos ni ejecutar comandos que alteren el sistema.

Invocar:

@explore encuentra todos los archivos que usan la función calculateTotal

Cuándo usarlo:

• Búsqueda rápida en el codebase sin riesgo de modificaciones
• Explorar la estructura de un proyecto desconocido
• Encontrar patrones, dependencias o usos de funciones específicas
• Obtener respuestas rápidas sobre el código cuando no necesitas modificar nada
• Mapear la arquitectura de un módulo antes de trabajar en él

Explore es especialmente útil cuando necesitas información pero no quieres que el subagente toque nada. Su naturaleza de solo lectura lo hace seguro para exploración libre.

Navegación entre Sesiones

Cuando invocas un subagente, se crea una sesión hija. OpenCode ofrece keybinds dedicados para navegar entre la sesión padre y las sesiones hijas:

Keybind	Acción
<Leader>+Down	Navegar a la sesión hija
<Leader>+Up	Volver a la sesión padre
<Leader>+Right	Siguiente sesión hija
<Leader>+Left	Sesión hija anterior

Esto te permite revisar el trabajo del subagente sin perder el contexto de tu conversación principal. Puedes ir y venir entre sesiones libremente.

Indicadores Visuales de Subagentes

La TUI (Terminal User Interface) muestra información detallada sobre las sesiones hijas activas:

• Conteo de tool calls pendientes en vez de un genérico “Running…” — ves exactamente cuántas herramientas está ejecutando el subagente
• Hints de keybinds para navegar a sesiones de subagentes activos — la interfaz te indica qué teclas presionar
• Spinners animados que indican qué herramienta está ejecutando cada subagente — puedes ver si está leyendo, buscando o ejecutando comandos
• Los comandos de navegación de sesiones se deshabilitan automáticamente cuando no hay sesión padre disponible

Esta información visual te permite monitorear el progreso de los subagentes sin necesidad de navegar a sus sesiones individuales. Es especialmente útil cuando tienes múltiples subagentes corriendo en paralelo.

Agentes Ocultos (Hidden)

Estos agentes corren automáticamente en segundo plano. No los invocas directamente ni interactúas con ellos, pero son fundamentales para el funcionamiento fluido de OpenCode. Trabajan silenciosamente para mantener la calidad de la experiencia.

Compaction

Se activa cuando la ventana de contexto del LLM se llena. Comprime el historial de la conversación manteniendo la información esencial y descartando lo redundante.

Este proceso es crítico para conversaciones largas. Sin compaction, llegarías al límite del contexto y el LLM perdería información importante. Compaction analiza qué información es relevante para la tarea actual y la preserva mientras elimina detalles que ya no son necesarios.

Cómo funciona:

1. Detecta que la ventana de contexto está cerca de su límite
2. Analiza el historial identificando información esencial vs. redundante
3. Genera un resumen comprimido que mantiene el contexto crítico
4. Reemplaza el historial largo por la versión comprimida
5. La conversación continúa sin que notes la transición

Title

Genera automáticamente un título descriptivo para cada sesión de conversación. Se ejecuta después de los primeros intercambios para nombrar la sesión de forma significativa.

Los títulos generados facilitan encontrar sesiones anteriores cuando necesitas volver a una conversación específica. En lugar de ver “Sesión 1”, “Sesión 2”, ves títulos como “Refactorización del módulo de pagos” o “Fix del bug de autenticación”.

Summary

Crea resúmenes de sesiones completadas. Útil para revisar después qué se hizo en cada conversación sin tener que releer todo el historial.

Los resúmenes capturan las decisiones tomadas, los archivos modificados y los resultados obtenidos. Son una referencia rápida que te ahorra tiempo cuando necesitas recordar qué se trabajó en una sesión anterior.

Tabla Resumen

Agente	Tipo	Herramientas	Caso de Uso
Build	Primario (default)	Todas	Desarrollo activo, escribir y modificar código
Plan	Primario	edit/bash en modo “ask”	Analizar, diseñar, planificar con aprobación
General	Subagente	Todas (excepto “all”)	Investigación multi-step, tareas complejas delegadas
Explore	Subagente	Solo lectura	Búsqueda rápida, explorar codebase
Compaction	Oculto	Interno	Comprimir contexto en conversaciones largas
Title	Oculto	Interno	Nombrar sesiones automáticamente
Summary	Oculto	Interno	Resumir sesiones completadas

Flujo de Trabajo Recomendado

El siguiente diagrama muestra el flujo ideal para una sesión de desarrollo completa:

flowchart LR
    A[Plan: Analizar problema] --> B[Plan: Diseñar solución]
    B --> C{Tab}
    C --> D[Build: Implementar]
    D --> E["@general: Investigar componente"]
    D --> F["@explore: Buscar patrones"]
    E --> G[Revisar resultado]
    F --> G
    G --> H{Necesita replantear?}
    H -->|Si| I{Tab}
    I --> A
    H -->|No| J[Build: Continuar]
    J --> K[Compaction: auto]

1. Inicia en Plan para analizar el problema y diseñar la solución sin riesgo de modificar nada
2. Cambia a Build con Tab para implementar la solución diseñada
3. Delega con @general tareas complejas de investigación que requieren múltiples pasos
4. Usa @explore para búsquedas rápidas sin salir de tu flujo principal
5. Vuelve a Plan si necesitas replantear algo que no salió como esperabas
6. Deja que Compaction maneje el contexto automáticamente en sesiones largas

Este modelo de agentes permite separar claramente las fases de pensamiento y ejecución. La planificación deliberada en Plan reduce errores, la implementación en Build es eficiente, y la delegación a subagentes permite paralelizar trabajo sin perder foco.

Patrones Avanzados

Investigación Paralela con General

Cuando enfrentas un problema complejo que involucra múltiples módulos, lanza subagentes en paralelo:

@general analiza el flujo de datos desde la API hasta el frontend
@general revisa las queries de la base de datos por problemas de N+1
@general investiga los tiempos de respuesta de los endpoints críticos

Cada subagente trabaja de forma independiente. Cuando todos terminan, revisas sus hallazgos en las sesiones hijas y sintetizas la información en tu sesión principal.

Exploración Segura antes de Refactorizar

Antes de una refactorización grande, usa Explore para mapear las dependencias:

@explore lista todos los archivos que importan desde el módulo de autenticación
@explore encuentra los tests que cubren la función processPayment
@explore busca todos los usos del tipo UserProfile en el proyecto

Con esta información, Plan puede diseñar la refactorización con conocimiento completo del impacto, y Build puede ejecutarla con confianza.

Sesiones Largas con Compaction

En sesiones de desarrollo extensas, Compaction se activa automáticamente. Para maximizar su efectividad:

• Sé explícito sobre las decisiones importantes para que Compaction las preserve
• Usa todowrite para registrar el plan de trabajo, ya que las listas de tareas persisten independientemente del contexto
• Si notas que el LLM pierde contexto, resume los puntos clave para refrescar la información

---

Siguiente: Capitulo 6: Agentes Custom —>