---
title: Anatomía de un agente
description: "Un agente no es un prompt: es un directorio de artefactos declarativos que el motor compila antes de cada ejecución, y que se versiona, revisa y publica como se revisa el código."
allan.topic: concept-article
allan.service: allan-registry
allan.date: 08/04/2026
allan.fuente: [internal/artifacts, internal/forge, internal/agents]
allan.audiencia: [usuario, admin, desarrollador]
allan.aplica_a: todos los planes
allan.terminos: [agente, version-de-agente, ambito, forge, herramienta-regulada]
---

No hay agentes empotrados en el motor. Un agente es un **directorio de
ficheros**, y esa decisión explica casi todo lo demás.

## Los artefactos

| Artefacto | Qué aporta |
|---|---|
| `AGENT.md` | Quién es y cómo se comporta |
| `agent.yaml` | Identidad, modelos, capacidades y herramientas permitidas |
| `SKILL.md` | Una habilidad concreta que puede cargar cuando hace falta |
| `*.flow.md` | Un flujo que acota la ejecución en un contexto |
| `*.prompt.md` | Instrucciones reutilizables |
| `*.eval.md` | Cómo se comprueba que sigue haciéndolo bien |
| `*.hook.md` | Qué ocurre en momentos concretos del ciclo |
| `*.memory.md` | Qué debe recordar y cómo |

El motor los escanea, valida y compila en el contexto de ejecución. Nada de esto
es código: es markdown y YAML declarativos.

## Por qué importa que sea un directorio

Porque todo lo que se puede hacer con ficheros se puede hacer con un agente. Se
versiona. Se revisa línea a línea. Se compara una versión con otra. Se publica.
Se retira.

Un agente cuyo comportamiento vive en una base de datos no se puede revisar; uno
cuyo comportamiento vive en ficheros, sí.

> [!SUGERENCIA]
> Antes de duplicar un agente para cambiarle algo, mire si lo que quiere cambiar
> son las instrucciones o solo las herramientas permitidas. Un duplicado duplica
> el mantenimiento para siempre.

## Del lenguaje natural al agente

No hace falta escribir esos ficheros a mano. Se describe en lenguaje natural qué
debe hacer el agente y la plataforma lo construye, con **dos puntos de revisión
humana**: uno sobre el diseño propuesto y otro sobre la validación del resultado.

Las sesiones de construcción vivas aparecen en la barra superior, con aviso de
cuántas esperan que alguien las mire.

## Versiones y ámbitos

Publicar crea una **versión**, y una versión publicada no se edita: se sustituye.
Volver atrás es promocionar de nuevo una anterior.

Al publicar se elige hasta dónde llega: solo para quien lo hizo, para toda la
organización, o para todas las organizaciones de la plataforma. Subir de ámbito
pone el agente en manos de gente que no lo escribió, y por eso no es inmediato:
genera una aprobación.

## Mejorar uno que ya existe

Distinto de construir uno nuevo. La mejora parte de la evidencia de sus fallos
—qué hizo mal, en qué ejecuciones— y propone cambios sobre esa base, no sobre una
intuición.