Agentes

Configura y usa agentes especializados.

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

Consejo: Usa el agente plan para analizar código y revisar sugerencias sin realizar ningún cambio 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 recorrerlos con la tecla Tab, o con tu atajo switch_agent configurado. Estos agentes manejan tu conversación principal. El acceso a las 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 incluye 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 incluye tres subagentes integrados, General, Explore y Scout. Los veremos a continuación.

Integrados

OpenCode incluye dos agentes primarios integrados y tres subagentes integrados.

Usar build

Modo: primary

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

Usar plan

Modo: primary

Un agente restringido diseñado para la planificación y el análisis. Usamos un sistema de permisos para darte más control y prevenir cambios no deseados. De forma predeterminada, 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 realizar ninguna modificación real en tu base de código.

Usar general

Modo: subagent

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

Usar explore

Modo: subagent

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

Usar scout

Modo: subagent

Un agente de solo lectura para documentación externa e investigación de dependencias. Úsalo cuando necesites clonar un repositorio de dependencias en la caché administrada de OpenCode, inspeccionar el código fuente de una biblioteca o contrastar el código local con implementaciones upstream sin modificar tu espacio de trabajo.

Usar compaction

Modo: primary

Agente de sistema oculto que compacta contextos largos en un resumen más pequeño. Se ejecuta automáticamente cuando es necesario y no se puede seleccionar en la interfaz.

Usar title

Modo: primary

Agente de sistema oculto que genera títulos cortos para las sesiones. Se ejecuta automáticamente y no se puede seleccionar en la interfaz.

Usar summary

Modo: primary

Agente de sistema oculto que crea resúmenes de las sesiones. Se ejecuta automáticamente y no se puede seleccionar en la interfaz.

Uso

Para los agentes primarios, usa la tecla Tab para recorrerlos durante una sesión. También puedes usar tu atajo switch_agent configurado.
Los subagentes se pueden invocar:
- Automáticamente por los agentes primarios para tareas especializadas según sus descripciones.
- Manualmente mencionando con @ un subagente en tu mensaje. Por ejemplo.
```
@general ayúdame a buscar esta función
```
Navegación entre sesiones: cuando los subagentes crean sesiones hijas, usa session_child_first (predeterminado: <Leader>+Down) para entrar en la primera sesión hija desde la sesión padre.
Una vez que estés en una sesión hija, usa:
- session_child_cycle (predeterminado: Right ) para pasar a la siguiente sesión hija
- session_child_cycle_reverse (predeterminado: Left ) para pasar a la sesión hija anterior
- session_parent (predeterminado: Up ) para volver a la sesión padre
Esto te permite cambiar entre la conversación principal y el trabajo especializado de los subagentes.

Configuración

Puedes personalizar los agentes integrados o crear los tuyos propios mediante la configuración. Los agentes se pueden configurar 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}",
      "permission": {
        "edit": "allow",
        "bash": "allow"
      }
    },
    "plan": {
      "mode": "primary",
      "model": "anthropic/claude-haiku-4-20250514",
      "permission": {
        "edit": "deny",
        "bash": "deny"
      }
    },
    "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.",
      "permission": {
        "edit": "deny"
      }
    }
  }
}

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
permission:
  edit: deny
  bash: deny
---
 
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 obligatoria.

Temperature

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

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

opencode.json

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

Los valores de temperatura suelen ir de 0.0 a 1.0:

0.0-0.2 : respuestas muy enfocadas y deterministas, ideales para el análisis de código y la planificación
0.3-0.5 : respuestas equilibradas con algo de creatividad, buenas para tareas generales de desarrollo
0.6-1.0 : respuestas más creativas y variadas, útiles para hacer 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 ninguna temperatura, OpenCode usa los valores predeterminados específicos del modelo; típicamente 0 para la mayoría de los modelos, 0.55 para los modelos Qwen.

Max steps

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

Si esto no se establece, el agente seguirá iterando hasta que el modelo decida 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 de sistema especial que le indica que responda con un resumen de su trabajo y las tareas restantes recomendadas.

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

Disable

Establécelo en true para deshabilitar el agente.

opencode.json

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

Prompt

Especifica un archivo de prompt de 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 la ubicación del archivo de configuración. Por lo tanto, 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 de este agente. Útil para usar diferentes modelos optimizados para diferentes tareas. Por ejemplo, un modelo más rápido para la planificación, un modelo más capaz para la 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ó el 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 usas OpenCode Zen, usarías opencode/gpt-5.1-codex para GPT 5.1 Codex.

Tools (obsoleto)

tools está obsoleto. Prefiere el campo permission del agente para nuevas configuraciones, actualizaciones y un control más detallado.

Te permite controlar qué herramientas están disponibles en este agente. Puedes habilitar o deshabilitar herramientas específicas estableciéndolas en true o false. En la configuración tools de un agente, true equivale al permiso {"*": "allow"} y false equivale al permiso {"*": "deny"}.

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 en las entradas heredadas de tools para controlar varias 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
      }
    }
  }
}

Más información sobre las herramientas.

Permissions

Puedes configurar permisos para administrar qué acciones puede realizar un agente. Cada clave de permiso se puede establecer en:

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

Las claves de permiso disponibles son:

Clave	Herramientas que controla
`read`	`read`
`edit`	`write`, `edit`, `apply_patch`
`glob`	`glob`
`grep`	`grep`
`list`	`list`
`bash`	`bash`
`task`	`task`
`external_directory`	Cualquier herramienta que lea o escriba archivos fuera del worktree del proyecto
`todowrite`	`todowrite`, `todoread`
`webfetch`	`webfetch`
`websearch`	`websearch`
`lsp`	`lsp`
`skill`	`skill`
`question`	`question`
`doom_loop`	Prompts de recuperación cuando un agente parece atascado

read, edit, glob, grep, list, bash, task, external_directory, lsp y skill aceptan una acción abreviada ("allow" | "ask" | "deny") o un objeto de glob/patrón → acción para un control detallado. Las claves restantes aceptan únicamente la acción abreviada.

Nota: Las claves de permiso se comparan como patrones comodín contra el nombre de la herramienta subyacente, por lo que la misma sintaxis funciona para las integradas, las personalizadas y las herramientas MCP; por ejemplo, "mymcp_*": "deny" deniega todas las herramientas de un servidor MCP, y "mymcp_search": "ask" apunta a una sola.

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 recibir 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 administrar los permisos de todos los comandos. Dado que la última regla coincidente tiene prioridad, coloca 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"
        }
      }
    }
  }
}

Más información sobre los permisos.

Mode

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

opencode.json

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

La opción mode se puede establecer en primary, subagent o all. Si no se especifica ningún mode, su valor predeterminado es all.

Hidden

Oculta un subagente del menú de autocompletado @ con hidden: true. Útil para subagentes internos que solo deberían ser invocados programáticamente por otros agentes mediante la herramienta Task.

opencode.json

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

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

Nota: Solo se aplica a los agentes mode: subagent.

Task permissions

Controla qué subagentes puede invocar un agente mediante la herramienta Task con permission.task. Usa patrones glob para una coincidencia flexible.

opencode.json

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

Cuando se establece en deny, el subagente se elimina por completo 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 gana la última regla coincidente. 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 mediante el 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 a cómo aparece el agente en la interfaz.

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

opencode.json

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

Top P

Controla la diversidad de las 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. Los valores más bajos son más enfocados, los valores más altos más diversos.

Additional

Cualquier otra opción que especifiques en la configuración de tu agente se pasará directamente al proveedor como opciones del modelo. Esto te permite usar funciones 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 del proveedor. Consulta la documentación de tu proveedor para conocer los 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:

Pregunta dónde guardar el agente; global o específico del proyecto.
Pide una descripción de lo que debe hacer el agente.
Genera un prompt de sistema y un identificador apropiados.
Te permite seleccionar qué permisos debe tener el agente (todo lo que no selecciones queda denegado).
Finalmente, crea un archivo markdown con la configuración del agente.

Casos de uso

Estos son 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 realizar cambios
Agente review : revisión de código con acceso de solo lectura más herramientas de documentación
Agente debug : enfocado en la investigación con las herramientas bash y read habilitadas
Agente docs : redacción de documentación con operaciones de archivos pero sin comandos del sistema

Ejemplos

Estos son 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
permission:
  bash: deny
---
 
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
permission:
  edit: deny
---
 
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