# Agentes {#agents}

> Elige un agente integrado, sustituye su system prompt o crea uno propio para una tarea concreta.

Un perfil de agente define su forma de trabajar: system prompt, modelo, herramientas, permisos, límites y capacidad de delegar. Puedes sustituir por completo el system prompt de cualquier agente integrado, incluido Marshall, el principal por defecto.

Usa `/agent` para elegir el agente principal de la siguiente tarea. Usa un [Extension Profile](/es-ES/guide/extension-profiles) para elegir las extensiones instaladas que tendrá disponibles.

## Elige entre los agentes integrados {#choose-from-the-built-in-fleet}

Clarvis incluye cinco agentes listos para usar, sin generar archivos.

| Agente     | Uso principal                                                                                |
| ---------- | -------------------------------------------------------------------------------------------- |
| `marshall` | Programación general: investiga, implementa y delega trabajo acotado cuando resulta útil.    |
| `admiral`  | Ejecutar flujos reutilizables y coordinar ejecuciones independientes de agentes principales. |
| `coder`    | Una implementación acotada; pensado principalmente como subagente.                           |
| `explorer` | Investigación de solo lectura con pruebas concretas.                                         |
| `planner`  | Desglosar trabajo, dependencias, riesgos y criterios de finalización, sin escribir.          |

Abre `/agent` para cambiar el agente activo. **Intro** cambia solo la sesión actual. Pulsa **S** en el selector para guardar el agente como valor global o del espacio de trabajo. El valor del espacio tiene prioridad sobre el global.

## Crea un agente {#create-an-agent}

El editor integrado crea el archivo a partir de una plantilla de solo lectura:

1. Abre `/settings/agents`.
2. Pulsa **Ctrl+T** y elige ámbito global o del espacio.
3. Pulsa **A**, escribe un nombre como `reviewer` y pulsa **Intro**.
4. Abre el agente y revisa descripción, permisos, herramientas, modelo, límite de iteraciones, política de creación de subagentes e instrucciones.
5. Pulsa **Ctrl+S** después de cambiar un campo.
6. Si lo has creado en el espacio, aprueba la nueva configuración ejecutable con `/workspace-trust`.
7. Abre `/agent`, selecciona `reviewer` y pulsa **Intro** para usarlo en la sesión. Pulsa **S** solo si debe ser el valor persistente por defecto.

<figure class="tui-shot">
  <img src="/images/tui/agents-step-1-list.svg" width="14064" height="7536" alt="Lista de ajustes de agentes en el ámbito del espacio de trabajo con la acción de añadir" loading="lazy" decoding="async" />
  <figcaption><strong>Pasos 1 y 2.</strong> Abre el editor y elige el ámbito del archivo.</figcaption>
</figure>

<figure class="tui-shot">
  <img src="/images/tui/agents-step-2-name.svg" width="14064" height="7536" alt="Diálogo de agente nuevo que solicita el nombre reviewer" loading="lazy" decoding="async" />
  <figcaption><strong>Paso 3.</strong> Usa un nombre estable en minúsculas. El editor parte de una plantilla de solo lectura.</figcaption>
</figure>

<figure class="tui-shot">
  <img src="/images/tui/agents-step-3-details.svg" width="14064" height="7536" alt="Editor de reviewer con descripción, permisos, herramientas, modelo, límite, política de subagentes e instrucciones" loading="lazy" decoding="async" />
  <figcaption><strong>Pasos 4 y 5.</strong> Revisa todos los campos y concede solo los permisos necesarios.</figcaption>
</figure>

<figure class="tui-shot">
  <img src="/images/tui/workspace-trust-review.svg" width="14064" height="7536" alt="Solicitud de confianza para aprobar una definición de agente del espacio de trabajo" loading="lazy" decoding="async" />
  <figcaption><strong>Paso 6.</strong> El agente no estará disponible hasta aprobar su huella exacta.</figcaption>
</figure>

<figure class="tui-shot">
  <img src="/images/tui/agents-step-4-picker.svg" width="14064" height="7536" alt="Selector con los agentes integrados y el agente propio reviewer" loading="lazy" decoding="async" />
  <figcaption><strong>Paso 7.</strong> Usa <code>reviewer</code> en la sesión o guárdalo explícitamente como valor por defecto.</figcaption>
</figure>

La plantilla inicial puede leer el espacio, pero no editarlo ni ejecutar comandos. Añade permisos solo si el trabajo los necesita.

### Crea el archivo manualmente {#create-the-file-yourself}

Las definiciones son archivos Markdown cuyo nombre identifica al agente. No existe un `agent.md` genérico. Para crear manualmente un agente `reviewer` del espacio:

```bash
mkdir -p .clarvis/agents
$EDITOR .clarvis/agents/reviewer.md
```

Guarda esta definición completa en `.clarvis/agents/reviewer.md`:

```md
---
description: Reviews changes without modifying the workspace.
tools: []
grants:
  - read_workspace
  - use_skills
iteration_limit: 12
---

You are a read-only reviewer. Inspect the requested surface, verify claims against current source,
and report findings in severity order with precise file references. Do not edit files or run
mutating commands.
```

Aprueba el archivo con `/workspace-trust` y selecciónalo en `/agent`. Como agente principal, hereda el modelo por defecto configurado. Un `model: provider/model` declarado tiene prioridad cuando actúa como subagente; para el principal prevalece el modelo elegido por el usuario.

Campos habituales:

| Campo              | Significado                                                                                       |
| ------------------ | ------------------------------------------------------------------------------------------------- |
| `description`      | Finalidad que aparece en el selector.                                                             |
| `model`            | Modelo opcional del subagente; para el principal prevalece el valor del usuario.                  |
| `tools`            | Herramientas MCP con nombre separado por punto, como `project.search`.                            |
| `grants`           | Capacidades integradas: acceso a archivos, comandos, skills o flujos.                             |
| `can_spawn`        | Agentes que puede iniciar este agente principal.                                                  |
| `default_spawn`    | Subagente por defecto; también debe figurar en `can_spawn`.                                       |
| `iteration_limit`  | Punto de revisión flexible del principal en `escalate`; en otro caso, límite estricto por agente. |
| `reasoning_effort` | `off`, `minimal`, `low`, `medium`, `high`, `xhigh` o `max`.                                       |
| `budget`           | Política opcional de presupuesto de ejecución.                                                    |

El cuerpo Markdown después del cierre `---` es el system prompt. Los campos anteriores, llamados _frontmatter_, definen permisos y otras opciones.

Las herramientas nativas proceden de los permisos:

| Permiso          | Capacidad                                                                  |
| ---------------- | -------------------------------------------------------------------------- |
| `read_workspace` | Inspección de solo lectura del espacio.                                    |
| `edit_workspace` | Modificar archivos y leerlos.                                              |
| `run_commands`   | Ejecutar comandos, editar y leer.                                          |
| `ask_user`       | Pedir información al operador; solo tiene sentido en el agente de entrada. |
| `use_skills`     | Descubrir y cargar skills.                                                 |
| `workflow`       | Gestionar flujos desde un agente de entrada.                               |

`tools` enumera herramientas MCP con el formato `server.tool`. No concede acceso a archivos ni al intérprete de comandos.

::: warning Atención
Los permisos proceden de `grants` y de las herramientas seleccionadas, no del texto del prompt. Concede solo el acceso necesario.
:::

## Sustituye un agente integrado {#override-a-built-in-agent}

### Sustituye todo el system prompt {#replace-the-entire-system-prompt}

Crea un archivo con el nombre del agente integrado. Por ejemplo, guarda esto como `.clarvis/agents/marshall.md` para sustituir el system prompt de Marshall en un proyecto:

```md
---
description: A coding agent for this project's maintenance work.
---

You maintain this project. Read its contribution guide before making changes.
Keep fixes small, use the existing code style, and run the checks for the affected code.
Explain what changed, how you checked it, and anything that remains unresolved.
Ask before publishing a release or changing production infrastructure.
```

Aprueba el archivo con `/workspace-trust`. Su cuerpo Markdown sustituye todo el prompt integrado: no se añade al final. El mismo método sirve para Admiral, Coder, Explorer y Planner. Usa `~/.clarvis/agents/<name>.md` para aplicar la sustitución a distintos proyectos.

El ejemplo cambia el prompt y mantiene los permisos integrados y los campos omitidos. Los permisos siguen dependiendo de `grants` y `tools`. Clarvis también añade el contexto necesario para la tarea actual: sustituir el prompt no elimina el resto del contexto de ejecución.

### Cambia ajustes sin sustituir el prompt integrado {#change-settings-while-keeping-the-built-in-prompt}

Un archivo con nombre integrado modifica solo los campos que contiene. El nombre del archivo determina el agente. Puedes crearlo desde `/settings/agents` o en el directorio `agents/` global o del espacio. Estos son ejemplos mínimos completos para cada agente:

`.clarvis/agents/marshall.md`:

```md
---
iteration_limit: 60
compaction:
  prompt: |
    Preserve accepted decisions, current implementation state, failed approaches, unresolved risks,
    and the exact next action. Keep concrete file paths and validation results.
---
```

`.clarvis/agents/admiral.md`:

```md
---
iteration_limit: 60
---
```

`.clarvis/agents/coder.md`:

```md
---
iteration_limit: 40
---
```

`.clarvis/agents/explorer.md`:

```md
---
iteration_limit: 40
---
```

`.clarvis/agents/planner.md`:

```md
---
iteration_limit: 40
---
```

Los campos omitidos conservan sus valores integrados. Una lista vacía elimina la lista heredada. Deja vacío el cuerpo Markdown para conservar el system prompt integrado. Un cuerpo no vacío o `base_prompt` sustituye el prompt completo.

Un archivo aprobado del espacio tiene prioridad sobre uno global del mismo nombre. Clarvis usa solo el archivo seleccionado para modificar los campos integrados. Los campos avanzados `budget`, `compaction`, `retry` y `call_timeout_ms` requieren actualmente edición manual. En llamadas en streaming, `call_timeout_ms` mide inactividad y se reinicia con progreso de texto, razonamiento o entrada de herramientas; antes del primer progreso observable, es un límite absoluto.

Las claves desconocidas se conservan por compatibilidad futura, pero no cambian el comportamiento. Comprueba la escritura de los campos: `/doctor` detecta valores inválidos, pero una clave mal escrita puede no tener efecto.

### Asigna un presupuesto propio a un agente de entrada {#give-one-entry-agent-its-own-run-budget}

Usa un presupuesto de perfil si este agente necesita límites distintos de los generales:

```md
---
description: Reviews one bounded change without modifying the workspace.
grants:
  - read_workspace
iteration_limit: 20
budget:
  on_exceed: stop
  total_token_limit: 100000
  timeout_ms: 300000
---

Review the requested change and report findings with precise evidence. Do not modify files.
```

Se aplica cuando el perfil es el agente de entrada y sustituye por completo el presupuesto general. Para un subagente, `iteration_limit` sigue siendo un límite estricto.

### Sustituye el prompt de compactación {#override-the-compaction-prompt}

La opción admitida es `compaction.prompt` dentro de la definición del agente, como en el ejemplo de Marshall. No existe un archivo independiente `compaction-prompt.md` ni un prompt de compactación general en `settings.json`.

Primero se resuelve el agente efectivo: archivo aprobado del espacio, archivo global del mismo nombre o definición integrada, en ese orden. Su `compaction.prompt` no vacío sustituye el prompt de resumen de ese agente. Si falta, sigue activo el integrado. Clarvis añade en cualquier caso el objetivo actual del principal o la tarea del subagente a la petición de compactación.

Para desactivar el resumen mediante LLM y usar descarte mecánico en un agente:

```md
---
compaction:
  prompt_mode: none
---
```

`prompt_mode: none` no puede combinarse con `compaction.prompt`.

Si una sustitución tiene un formato inválido, Clarvis mantiene intacto el agente integrado e informa del archivo rechazado en `/doctor`. Un agente propio nuevo inválido no tiene alternativa integrada y queda indisponible.

## Elige ámbito global o del espacio de trabajo {#choose-global-or-workspace-scope}

Usa `~/.clarvis/agents/<name>.md` para un agente disponible en cualquier proyecto, o `<workspace>/.clarvis/agents/<name>.md` para una definición específica. Si existe, `$CLARVIS_HOME` sustituye a `~/.clarvis`. Tras aprobarse, la definición del espacio prevalece sobre la global del mismo nombre.

También puedes gestionarlas en `/settings/agents`. Un agente integrado puede restablecerse o copiarse con otro nombre; no se puede eliminar ni renombrar directamente.

## Consulta también {#see-also}

- [Flujos de trabajo](/es-ES/guide/workflows)
- [Ámbitos y confianza](/es-ES/explanation/scopes-and-trust)
- [Configuración](/es-ES/reference/configuration)
- [Skills](/es-ES/guide/skills)

---

[HTML canónico](https://clarvis.dev/es-ES/guide/agents)

[Índice de documentación](https://clarvis.dev/es-ES/llms.txt)