Files
tf_code/packages/web/src/content/docs/es/agents.mdx
2026-02-10 20:22:30 +00:00

748 lines
19 KiB
Plaintext

---
title: Agentes
description: Configurar y utilizar agentes especializados.
---
Los agentes son asistentes de IA especializados que se pueden configurar para tareas y flujos de trabajo específicos. Le permiten crear herramientas enfocadas con indicaciones, modelos y acceso a herramientas personalizados.
:::tip
Utilice el agente del plan para analizar el código y revisar sugerencias sin realizar ningún cambio en el código.
:::
Puede 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. Puede recorrerlos usando la tecla **Tab** o la combinación de teclas `switch_agent` configurada. Estos agentes manejan su 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.
:::tip
Puede utilizar la tecla **Tab** para cambiar entre agentes principales durante una sesión.
:::
OpenCode viene con dos agentes principales integrados, **Build** y **Plan**. Bien
mira estos a continuación.
---
### Subagentes
Los subagentes son asistentes especializados que los agentes principales pueden invocar para tareas específicas. También puedes invocarlos manualmente **@ mencionándolos** en tus mensajes.
OpenCode viene con dos subagentes integrados, **General** y **Explore**. Veremos esto a continuación.
---
## Built-in
OpenCode viene con dos agentes primarios integrados y dos subagentes integrados.
---
### Use build
_Modo_: `primary`
Build es el agente principal **predeterminado** con todas las herramientas habilitadas. Este es el agente estándar para trabajos de desarrollo en los que necesita acceso completo a las operaciones de archivos y comandos del sistema.
---
### Use plan
_Modo_: `primary`
Un agente restringido diseñado para la planificación y el análisis. Utilizamos un sistema de permisos para brindarle más control y evitar cambios no deseados.
De forma predeterminada, todo lo siguiente está configurado en `ask`:
- `file edits`: todas las escrituras, parches y ediciones.
- `bash`: Todos los comandos bash
Este agente es útil cuando desea que LLM analice código, sugiera cambios o cree planes sin realizar modificaciones reales a su base de código.
---
### Use general
_Modo_: `subagent`
Un agente de uso general para investigar preguntas complejas y ejecutar tareas de varios pasos. Tiene acceso completo a las herramientas (excepto tareas pendientes), por lo que puede realizar cambios en los archivos cuando sea necesario. Utilícelo para ejecutar varias unidades de trabajo en paralelo.
---
### Use explore
_Modo_: `subagent`
Un agente rápido y de solo lectura para explorar bases de código. No se pueden modificar archivos. Úselo cuando necesite buscar rápidamente archivos por patrones, buscar palabras clave en el código o responder preguntas sobre el código base.
---
### Use compaction
_Modo_: `primary`
Agente de sistema oculto que compacta un contexto largo en un resumen más pequeño. Se ejecuta automáticamente cuando es necesario y no se puede seleccionar en la interfaz de usuario.
---
### Use title
_Modo_: `primary`
Agente del sistema oculto que genera títulos de sesión cortos. Se ejecuta automáticamente y no se puede seleccionar en la interfaz de usuario.
---
### Use summary
_Modo_: `primary`
Agente del sistema oculto que crea resúmenes de sesiones. Se ejecuta automáticamente y no se puede seleccionar en la interfaz de usuario.
---
## Uso
1. Para los agentes principales, use la tecla **Tab** para recorrerlos durante una sesión. También puede utilizar su combinación de teclas `switch_agent` configurada.
2. Se pueden invocar subagentes:
- **Automáticamente** por agentes principales para tareas especializadas según sus descripciones.
- Manualmente **@ mencionando** un subagente en tu mensaje. Por ejemplo.
```txt frame="none"
@general help me search for this function
```
3. **Navegación entre sesiones**: cuando los subagentes crean sus propias sesiones secundarias, puede navegar entre la sesión principal y todas las sesiones secundarias usando:
- **\<Leader>+Right** (or su combinación de teclas `session_child_cycle` configurada) para avanzar a través de padre → hijo1 → hijo2 → ... → padre
- **\<Leader>+Left** (or su combinación de teclas `session_child_cycle_reverse` configurada) para retroceder entre padre ← hijo1 ← hijo2 ← ... ← padre
Esto le permite cambiar sin problemas entre la conversación principal y el trabajo de subagente especializado.
---
## Configurar
Puede personalizar los agentes integrados o crear los suyos propios mediante la configuración. Los agentes se pueden configurar de dos maneras:
---
### JSON
Configure agentes en su archivo de configuración `opencode.json`:
```json title="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 puede definir agentes utilizando archivos de Markdown. Colócalos en:
- Global: `~/.config/opencode/agents/`
- Por proyecto: `.opencode/agents/`
```markdown title="~/.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 de 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
Utilice la opción `description` para proporcionar una breve descripción de lo que hace el agente y cuándo usarlo.
```json title="opencode.json"
{
"agent": {
"review": {
"description": "Reviews code for best practices and potential issues"
}
}
}
```
Esta es una opción de configuración **obligatoria**.
---
### Temperature
Controle la aleatoriedad y la creatividad de las respuestas de LLM con la configuración `temperature`.
Los valores más bajos hacen que las respuestas sean más centradas y deterministas, mientras que los valores más altos aumentan la creatividad y la variabilidad.
```json title="opencode.json"
{
"agent": {
"plan": {
"temperature": 0.1
},
"creative": {
"temperature": 0.8
}
}
}
```
Los valores de temperatura suelen oscilar entre 0,0 y 1,0:
- **0.0-0.2**: Respuestas muy enfocadas y deterministas, ideales para análisis y planificación de código.
- **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 la lluvia de ideas y la exploración.
```json title="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 utiliza valores predeterminados específicos del modelo; normalmente 0 para la mayoría de los modelos, 0,55 para los modelos Qwen.
---
### Max steps
Controle la cantidad máxima de iteraciones agentes que un agente puede realizar antes de verse obligado a responder solo con texto. Esto permite a los usuarios que desean controlar los costos establecer un límite a las acciones de agencia.
Si no se establece esto, el agente continuará iterando hasta que el modelo decida detenerse o el usuario interrumpa la sesión.
```json title="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 mensaje especial del sistema que le indica que responda con un resumen de su trabajo y las tareas restantes recomendadas.
:::caution
El campo heredado `maxSteps` está en desuso. Utilice `steps` en su lugar.
:::
---
### Disable
Establezca en `true` para deshabilitar el agente.
```json title="opencode.json"
{
"agent": {
"review": {
"disable": true
}
}
}
```
---
### Prompt
Especifique un archivo de aviso del sistema personalizado para este agente con la configuración `prompt`. El archivo de aviso debe contener instrucciones específicas para el propósito del agente.
```json title="opencode.json"
{
"agent": {
"review": {
"prompt": "{file:./prompts/code-review.txt}"
}
}
}
```
Esta ruta es relativa a donde se encuentra el archivo de configuración. Entonces esto funciona tanto para la configuración global OpenCode como para la configuración específica del proyecto.
---
### Model
Utilice la configuración `model` para anular el modelo de este agente. Útil para utilizar diferentes modelos optimizados para diferentes tareas. Por ejemplo, un modelo más rápido de planificación, un modelo más capaz de implementación.
:::tip
Si no especifica un modelo, los agentes primarios usarán el [modelo configurado globalmente](/docs/config#models), mientras que los subagentes usarán el modelo del agente primario que invocó al subagente.
:::
```json title="opencode.json"
{
"agent": {
"plan": {
"model": "anthropic/claude-haiku-4-20250514"
}
}
}
```
El ID del modelo en su configuración OpenCode usa el formato `provider/model-id`. Por ejemplo, si usa [OpenCode Zen](/docs/zen), usaría `opencode/gpt-5.1-codex` para GPT 5.1 Codex.
---
### Tools
Controle qué herramientas están disponibles en este agente con la configuración `tools`. Puede habilitar o deshabilitar herramientas específicas configurándolas en `true` o `false`.
```json title="opencode.json" {3-6,9-12}
{
"$schema": "https://opencode.ai/config.json",
"tools": {
"write": true,
"bash": true
},
"agent": {
"plan": {
"tools": {
"write": false,
"bash": false
}
}
}
}
```
:::note
La configuración específica del agente anula la configuración global.
:::
También puedes utilizar comodines para controlar varias herramientas a la vez. Por ejemplo, para desactivar todas las herramientas de un servidor MCP:
```json title="opencode.json"
{
"$schema": "https://opencode.ai/config.json",
"agent": {
"readonly": {
"tools": {
"mymcp_*": false,
"write": false,
"edit": false
}
}
}
}
```
[Más información sobre herramientas](/docs/tools).
---
### Permissions
Puede configurar permisos para administrar qué acciones puede realizar un agente. Actualmente, los permisos para las herramientas `edit`, `bash` y `webfetch` se pueden configurar para:
- `"ask"`: solicitar aprobación antes de ejecutar la herramienta
- `"allow"` — Permitir todas las operaciones sin aprobación
- `"deny"` — Desactiva la herramienta
```json title="opencode.json"
{
"$schema": "https://opencode.ai/config.json",
"permission": {
"edit": "deny"
}
}
```
Puede anular estos permisos por agente.
```json title="opencode.json" {3-5,8-10}
{
"$schema": "https://opencode.ai/config.json",
"permission": {
"edit": "deny"
},
"agent": {
"build": {
"permission": {
"edit": "ask"
}
}
}
}
```
También puede establecer permisos en los agentes de Markdown.
```markdown title="~/.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.
```
Puede establecer permisos para comandos bash específicos.
```json title="opencode.json" {7}
{
"$schema": "https://opencode.ai/config.json",
"agent": {
"build": {
"permission": {
"bash": {
"git push": "ask",
"grep *": "allow"
}
}
}
}
}
```
Esto puede tomar un patrón global.
```json title="opencode.json" {7}
{
"$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 de coincidencia tiene prioridad, coloque el comodín `*` primero y las reglas específicas después.
```json title="opencode.json" {8}
{
"$schema": "https://opencode.ai/config.json",
"agent": {
"build": {
"permission": {
"bash": {
"*": "ask",
"git status *": "allow"
}
}
}
}
}
```
[Más información sobre permisos](/docs/permissions).
---
### Mode
Controle el modo del agente con la configuración `mode`. La opción `mode` se utiliza para determinar cómo se puede utilizar el agente.
```json title="opencode.json"
{
"agent": {
"review": {
"mode": "subagent"
}
}
}
```
La opción `mode` se puede configurar en `primary`, `subagent` o `all`. Si no se especifica `mode`, el valor predeterminado es `all`.
---
### Hidden
Oculte un subagente del menú de autocompletar `@` con `hidden: true`. Útil para subagentes internos que solo deben ser invocados mediante programación por otros agentes a través de la herramienta Tarea.
```json title="opencode.json"
{
"agent": {
"internal-helper": {
"mode": "subagent",
"hidden": true
}
}
}
```
Esto sólo afecta la visibilidad del usuario en el menú de autocompletar. El modelo aún puede invocar agentes ocultos a través de la herramienta Tarea si los permisos lo permiten.
:::note
Sólo aplica para agentes `mode: subagent`.
:::
---
### Task permissions
Controle qué subagentes puede invocar un agente a través de la herramienta Tarea con `permission.task`. Utiliza patrones globales para una combinación flexible.
```json title="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 Tarea, por lo que el modelo no intentará invocarlo.
:::tip
Las reglas se evalúan en orden y la **última regla coincidente gana**. En el ejemplo anterior, `orchestrator-planner` coincide con `*` (denegar) y `orchestrator-*` (permitir), pero como `orchestrator-*` viene después de `*`, el resultado es `allow`.
:::
:::tip
Los usuarios siempre pueden invocar cualquier subagente directamente a través del menú de autocompletar `@`, incluso si los permisos de tarea del agente lo niegan.
:::
---
### Color
Personalice la apariencia visual del agente en la interfaz de usuario con la opción `color`. Esto afecta la forma en que aparece el agente en la interfaz.
Utilice un color hexadecimal válido (por ejemplo, `#FF5733`) o un color de tema: `primary`, `secondary`, `accent`, `success`, `warning`, `error`, `info`.
```json title="opencode.json"
{
"agent": {
"creative": {
"color": "#ff6b6b"
},
"code-reviewer": {
"color": "accent"
}
}
}
```
---
### Top P
Controle la diversidad de respuestas con la opción `top_p`. Alternativa a la temperatura para controlar la aleatoriedad.
```json title="opencode.json"
{
"agent": {
"brainstorm": {
"top_p": 0.9
}
}
}
```
Los valores oscilan entre 0,0 y 1,0. Los valores más bajos están más enfocados, los valores más altos son más diversos.
---
### Additional
Cualquier otra opción que especifique en la configuración de su agente se **pasará directamente** al proveedor como opciones de modelo. Esto le permite utilizar funciones y parámetros específicos del proveedor.
Por ejemplo, con los modelos de razonamiento de OpenAI, puedes controlar el esfuerzo de razonamiento:
```json title="opencode.json" {6,7}
{
"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. Consulte la documentación de su proveedor para conocer los parámetros disponibles.
:::tip
Ejecute `opencode models` para ver una lista de los modelos disponibles.
:::
---
## Create agents
Puede crear nuevos agentes usando el siguiente comando:
```bash
opencode agent create
```
Este comando interactivo:
1. Preguntar dónde guardar al agente; global o específico del proyecto.
2. Descripción de lo que debe hacer el agente.
3. Genere un indicador y un identificador del sistema adecuados.
4. Le permite seleccionar a qué herramientas puede acceder el agente.
5. Finalmente, cree un archivo Markdown con la configuración del agente.
---
## Casos de uso
A continuación se muestran algunos casos de uso comunes para diferentes agentes.
- **Build agent**: trabajo de desarrollo completo con todas las herramientas habilitadas
- **Plan agent**: Análisis y planificación sin realizar cambios
- **Review agent**: revisión de código con acceso de solo lectura más herramientas de documentación
- **Debug agent**: centrado en la investigación con bash y herramientas de lectura habilitadas
- **Docs agent**: escritura de documentación con operaciones de archivos pero sin comandos del sistema.
---
## Ejemplos
A continuación se muestran algunos agentes de ejemplo que pueden resultarle útiles.
:::tip
¿Tiene un agente que le gustaría compartir? [Enviar un PR](https://github.com/anomalyco/opencode).
:::
---
### Documentation agent
```markdown title="~/.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
```
---
### Security auditor
```markdown title="~/.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
```