Agentes

Configura y usa agentes especializados.

Los agentes son asistentes de IA especializados que pueden configurarse para tareas y flujos de trabajo específicos. Te permiten crear herramientas enfocadas con prompts personalizados, modelos y acceso a herramientas.

Consejo: Usa el agente plan para analizar código y revisar sugerencias sin hacer cambios en el código.

Puedes cambiar entre agentes durante una sesión o invocarlos con la mención @.

Tipos

Hay dos tipos de agentes en OpenCode: agentes primarios y subagentes.

Agentes primarios

Los agentes primarios son los asistentes principales con los que interactúas directamente. Puedes alternar entre ellos usando la tecla Tab o tu combinación de teclas switch_agent configurada. Estos agentes manejan tu conversación principal. El acceso a herramientas se configura mediante permisos — por ejemplo, Build tiene todas las herramientas habilitadas mientras que Plan está restringido.

Consejo: Puedes usar la tecla Tab para cambiar entre agentes primarios durante una sesión.

OpenCode viene con dos agentes primarios integrados: Build y Plan. Los veremos a continuación.

Subagentes

Los subagentes son asistentes especializados que los agentes primarios pueden invocar para tareas específicas. También puedes invocarlos manualmente mencionándolos con @ en tus mensajes.

OpenCode viene con dos subagentes integrados: General y Explore. Los veremos a continuación.

Integrados

OpenCode viene con dos agentes primarios integrados y dos subagentes integrados.

Usar build

Modo: primary

Build es el agente primario predeterminado con todas las herramientas habilitadas. Este es el agente estándar para trabajo de desarrollo donde necesitas acceso completo a operaciones de archivos y comandos del sistema.

Usar plan

Modo: primary

Un agente restringido diseñado para planificación y análisis. Usamos un sistema de permisos para darte más control y prevenir cambios no deseados. Por defecto, todos los siguientes están configurados como ask:

file edits: Todas las escrituras, parches y ediciones
bash: Todos los comandos bash

Este agente es útil cuando quieres que el LLM analice código, sugiera cambios o cree planes sin hacer modificaciones reales a tu código base.

Usar general

Modo: subagent

Un agente de propósito general para investigar preguntas complejas y ejecutar tareas de múltiples pasos. Tiene acceso completo a herramientas (excepto todo), por lo que puede hacer cambios en archivos cuando sea necesario. Úsalo para ejecutar múltiples unidades de trabajo en paralelo.

Usar explore

Modo: subagent

Un agente rápido de solo lectura para explorar código base. No puede modificar archivos. Úsalo cuando necesites encontrar archivos rápidamente por patrones, buscar palabras clave en el código o responder preguntas sobre el código base.

Usar compaction

Modo: primary

Agente del sistema oculto que compacta contexto largo en un resumen más pequeño. Se ejecuta automáticamente cuando es necesario y no es seleccionable en la interfaz.

Usar title

Modo: primary

Agente del sistema oculto que genera títulos cortos de sesión. Se ejecuta automáticamente y no es seleccionable en la interfaz.

Usar summary

Modo: primary

Agente del sistema oculto que crea resúmenes de sesión. Se ejecuta automáticamente y no es seleccionable en la interfaz.

Uso

Para agentes primarios, usa la tecla Tab para alternar entre ellos durante una sesión. También puedes usar tu combinación de teclas switch_agent configurada.
Los subagentes pueden invocarse:
- Automáticamente por agentes primarios para tareas especializadas basadas en sus descripciones.
- Manualmente mencionando con @ un subagente en tu mensaje. Por ejemplo:
```
@general help me search for this function
```
Navegación entre sesiones: Cuando los subagentes crean sus propias sesiones hijas, puedes navegar entre la sesión padre y todas las sesiones hijas usando:
- <Leader>+Right (o tu combinación session_child_cycle configurada) para avanzar: padre → hijo1 → hijo2 → … → padre
- <Leader>+Left (o tu combinación session_child_cycle_reverse configurada) para retroceder: padre ← hijo1 ← hijo2 ← … ← padre
Esto te permite cambiar sin problemas entre la conversación principal y el trabajo especializado del subagente.

Configurar

Puedes personalizar los agentes integrados o crear los tuyos propios mediante configuración. Los agentes pueden configurarse de dos maneras:

JSON

Configura agentes en tu archivo de configuración opencode.json:

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {
      "mode": "primary",
      "model": "anthropic/claude-sonnet-4-20250514",
      "prompt": "{file:./prompts/build.txt}",
      "tools": {
        "write": true,
        "edit": true,
        "bash": true
      }
    },
    "plan": {
      "mode": "primary",
      "model": "anthropic/claude-haiku-4-20250514",
      "tools": {
        "write": false,
        "edit": false,
        "bash": false
      }
    },
    "code-reviewer": {
      "description": "Reviews code for best practices and potential issues",
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-4-20250514",
      "prompt": "You are a code reviewer. Focus on security, performance, and maintainability.",
      "tools": {
        "write": false,
        "edit": false
      }
    }
  }
}

Markdown

También puedes definir agentes usando archivos markdown. Colócalos en:

Global: ~/.config/opencode/agents/
Por proyecto: .opencode/agents/

~/.config/opencode/agents/review.md

---
description: Reviews code for quality and best practices
mode: subagent
model: anthropic/claude-sonnet-4-20250514
temperature: 0.1
tools:
  write: false
  edit: false
  bash: false
---
 
You are in code review mode. Focus on:
 
- Code quality and best practices
- Potential bugs and edge cases
- Performance implications
- Security considerations
 
Provide constructive feedback without making direct changes.

El nombre del archivo markdown se convierte en el nombre del agente. Por ejemplo, review.md crea un agente review.

Opciones

Veamos estas opciones de configuración en detalle.

Description

Usa la opción description para proporcionar una breve descripción de lo que hace el agente y cuándo usarlo.

opencode.json

{
  "agent": {
    "review": {
      "description": "Reviews code for best practices and potential issues"
    }
  }
}

Esta es una opción de configuración requerida.

Temperature

Controla la aleatoriedad y creatividad de las respuestas del LLM con la configuración temperature.

Valores más bajos hacen las respuestas más enfocadas y deterministas, mientras que valores más altos aumentan la creatividad y variabilidad.

opencode.json

{
  "agent": {
    "plan": {
      "temperature": 0.1
    },
    "creative": {
      "temperature": 0.8
    }
  }
}

Los valores de temperature típicamente van de 0.0 a 1.0:

0.0-0.2: Respuestas muy enfocadas y deterministas, ideales para análisis de código y planificación
0.3-0.5: Respuestas equilibradas con algo de creatividad, buenas para tareas de desarrollo general
0.6-1.0: Respuestas más creativas y variadas, útiles para lluvia de ideas y exploración

opencode.json

{
  "agent": {
    "analyze": {
      "temperature": 0.1,
      "prompt": "{file:./prompts/analysis.txt}"
    },
    "build": {
      "temperature": 0.3
    },
    "brainstorm": {
      "temperature": 0.7,
      "prompt": "{file:./prompts/creative.txt}"
    }
  }
}

Si no se especifica temperature, OpenCode usa valores predeterminados específicos del modelo; típicamente 0 para la mayoría de modelos, 0.55 para modelos Qwen.

Max steps

Controla el número máximo de iteraciones agénticas que un agente puede realizar antes de ser forzado a responder solo con texto. Esto permite a los usuarios que desean controlar costos establecer un límite en las acciones agénticas.

Si no se establece, el agente continuará iterando hasta que el modelo elija detenerse o el usuario interrumpa la sesión.

opencode.json

{
  "agent": {
    "quick-thinker": {
      "description": "Fast reasoning with limited iterations",
      "prompt": "You are a quick thinker. Solve problems with minimal steps.",
      "steps": 5
    }
  }
}

Cuando se alcanza el límite, el agente recibe un prompt del sistema especial instruyéndolo a responder con un resumen de su trabajo y tareas restantes recomendadas.

Precaución: El campo heredado maxSteps está obsoleto. Usa steps en su lugar.

Disable

Establece a true para deshabilitar el agente.

opencode.json

{
  "agent": {
    "review": {
      "disable": true
    }
  }
}

Prompt

Especifica un archivo de prompt del sistema personalizado para este agente con la configuración prompt. El archivo de prompt debe contener instrucciones específicas para el propósito del agente.

opencode.json

{
  "agent": {
    "review": {
      "prompt": "{file:./prompts/code-review.txt}"
    }
  }
}

Esta ruta es relativa a donde se encuentra el archivo de configuración. Así que esto funciona tanto para la configuración global de OpenCode como para la configuración específica del proyecto.

Model

Usa la configuración model para anular el modelo para este agente. Útil para usar diferentes modelos optimizados para diferentes tareas. Por ejemplo, un modelo más rápido para planificación, un modelo más capaz para implementación.

Consejo: Si no especificas un modelo, los agentes primarios usan el modelo configurado globalmente mientras que los subagentes usarán el modelo del agente primario que invocó al subagente.

opencode.json

{
  "agent": {
    "plan": {
      "model": "anthropic/claude-haiku-4-20250514"
    }
  }
}

El ID del modelo en tu configuración de OpenCode usa el formato provider/model-id. Por ejemplo, si estás usando OpenCode Zen, usarías opencode/gpt-5.1-codex para GPT 5.1 Codex.

Tools

Controla qué herramientas están disponibles en este agente con la configuración tools. Puedes habilitar o deshabilitar herramientas específicas estableciéndolas a true o false.

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "tools": {
    "write": true,
    "bash": true
  },
  "agent": {
    "plan": {
      "tools": {
        "write": false,
        "bash": false
      }
    }
  }
}

Nota: La configuración específica del agente anula la configuración global.

También puedes usar comodines para controlar múltiples herramientas a la vez. Por ejemplo, para deshabilitar todas las herramientas de un servidor MCP:

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "readonly": {
      "tools": {
        "mymcp_*": false,
        "write": false,
        "edit": false
      }
    }
  }
}

Aprende más sobre herramientas.

Permissions

Puedes configurar permisos para gestionar qué acciones puede tomar un agente. Actualmente, los permisos para las herramientas edit, bash y webfetch pueden configurarse como:

"ask" — Solicitar aprobación antes de ejecutar la herramienta
"allow" — Permitir todas las operaciones sin aprobación
"deny" — Deshabilitar la herramienta

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "deny"
  }
}

Puedes anular estos permisos por agente.

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "deny"
  },
  "agent": {
    "build": {
      "permission": {
        "edit": "ask"
      }
    }
  }
}

También puedes establecer permisos en agentes Markdown.

~/.config/opencode/agents/review.md

---
description: Code review without edits
mode: subagent
permission:
  edit: deny
  bash:
    "*": ask
    "git diff": allow
    "git log*": allow
    "grep *": allow
  webfetch: deny
---
 
Only analyze code and suggest changes.

Puedes establecer permisos para comandos bash específicos.

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {
      "permission": {
        "bash": {
          "git push": "ask",
          "grep *": "allow"
        }
      }
    }
  }
}

Esto puede usar un patrón glob.

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {
      "permission": {
        "bash": {
          "git *": "ask"
        }
      }
    }
  }
}

Y también puedes usar el comodín * para gestionar permisos para todos los comandos. Como la última regla coincidente tiene precedencia, pon el comodín * primero y las reglas específicas después.

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {
      "permission": {
        "bash": {
          "*": "ask",
          "git status *": "allow"
        }
      }
    }
  }
}

Aprende más sobre permisos.

Mode

Controla el modo del agente con la configuración mode. La opción mode se usa para determinar cómo puede usarse el agente.

opencode.json

{
  "agent": {
    "review": {
      "mode": "subagent"
    }
  }
}

La opción mode puede establecerse a primary, subagent o all. Si no se especifica mode, el valor predeterminado es all.

Hidden

Oculta un subagente del menú de autocompletado @ con hidden: true. Útil para subagentes internos que solo deben ser invocados programáticamente por otros agentes a través de la herramienta Task.

opencode.json

{
  "agent": {
    "internal-helper": {
      "mode": "subagent",
      "hidden": true
    }
  }
}

Esto solo afecta la visibilidad del usuario en el menú de autocompletado. Los agentes ocultos aún pueden ser invocados por el modelo a través de la herramienta Task si los permisos lo permiten.

Nota: Solo aplica a agentes con mode: subagent.

Task permissions

Controla qué subagentes puede invocar un agente a través de la herramienta Task con permission.task. Usa patrones glob para coincidencia flexible.

opencode.json

{
  "agent": {
    "orchestrator": {
      "mode": "primary",
      "permission": {
        "task": {
          "*": "deny",
          "orchestrator-*": "allow",
          "code-reviewer": "ask"
        }
      }
    }
  }
}

Cuando se establece a deny, el subagente se elimina completamente de la descripción de la herramienta Task, por lo que el modelo no intentará invocarlo.

Consejo: Las reglas se evalúan en orden, y la última regla coincidente gana. En el ejemplo anterior, orchestrator-planner coincide tanto con * (deny) como con orchestrator-* (allow), pero como orchestrator-* viene después de *, el resultado es allow.

Consejo: Los usuarios siempre pueden invocar cualquier subagente directamente a través del menú de autocompletado @, incluso si los permisos de tarea del agente lo denegarían.

Color

Personaliza la apariencia visual del agente en la interfaz con la opción color. Esto afecta cómo aparece el agente en la interfaz.

Usa un color hexadecimal válido (ej. #FF5733) o color del tema: primary, secondary, accent, success, warning, error, info.

opencode.json

{
  "agent": {
    "creative": {
      "color": "#ff6b6b"
    },
    "code-reviewer": {
      "color": "accent"
    }
  }
}

Top P

Controla la diversidad de respuestas con la opción top_p. Alternativa a temperature para controlar la aleatoriedad.

opencode.json

{
  "agent": {
    "brainstorm": {
      "top_p": 0.9
    }
  }
}

Los valores van de 0.0 a 1.0. Valores más bajos son más enfocados, valores más altos más diversos.

Additional

Cualquier otra opción que especifiques en tu configuración de agente será pasada directamente al proveedor como opciones del modelo. Esto te permite usar características y parámetros específicos del proveedor.

Por ejemplo, con los modelos de razonamiento de OpenAI, puedes controlar el esfuerzo de razonamiento:

opencode.json

{
  "agent": {
    "deep-thinker": {
      "description": "Agent that uses high reasoning effort for complex problems",
      "model": "openai/gpt-5",
      "reasoningEffort": "high",
      "textVerbosity": "low"
    }
  }
}

Estas opciones adicionales son específicas del modelo y proveedor. Consulta la documentación de tu proveedor para parámetros disponibles.

Consejo: Ejecuta opencode models para ver una lista de los modelos disponibles.

Crear agentes

Puedes crear nuevos agentes usando el siguiente comando:

opencode agent create

Este comando interactivo:

Preguntará dónde guardar el agente: global o específico del proyecto.
Descripción de lo que debe hacer el agente.
Generará un prompt del sistema e identificador apropiados.
Te permitirá seleccionar qué herramientas puede acceder el agente.
Finalmente, creará un archivo markdown con la configuración del agente.

Casos de uso

Aquí hay algunos casos de uso comunes para diferentes agentes.

Agente Build: Trabajo de desarrollo completo con todas las herramientas habilitadas
Agente Plan: Análisis y planificación sin hacer cambios
Agente Review: Revisión de código con acceso de solo lectura más herramientas de documentación
Agente Debug: Enfocado en investigación con herramientas bash y lectura habilitadas
Agente Docs: Escritura de documentación con operaciones de archivos pero sin comandos del sistema

Ejemplos

Aquí hay algunos agentes de ejemplo que podrías encontrar útiles.

Consejo: ¿Tienes un agente que te gustaría compartir? Envía un PR (opens in a new tab).

Agente de documentación

~/.config/opencode/agents/docs-writer.md

---
description: Writes and maintains project documentation
mode: subagent
tools:
  bash: false
---
 
You are a technical writer. Create clear, comprehensive documentation.
 
Focus on:
 
- Clear explanations
- Proper structure
- Code examples
- User-friendly language

Auditor de seguridad

~/.config/opencode/agents/security-auditor.md

---
description: Performs security audits and identifies vulnerabilities
mode: subagent
tools:
  write: false
  edit: false
---
 
You are a security expert. Focus on identifying potential security issues.
 
Look for:
 
- Input validation vulnerabilities
- Authentication and authorization flaws
- Data exposure risks
- Dependency vulnerabilities
- Configuration security issues

Reglas Modelos