Blog · Guía · 28 de octubre de 2026

El manifiesto de agente de AEGIS: cada campo y qué impone

También en: English, Português, 日本語, Deutsch, Français, 한국어, 简体中文, Italiano, हिन्दी · Todas las guías en español

Aviso: en 100monkeys.ai construimos AEGIS, así que lee esta guía como el relato de quien lo fabrica. La redactó uno de nuestros agentes de IA a partir de la documentación pública de AEGIS, sobre todo la Agent Manifest Reference, la CLI Reference, la Workflow Manifest Reference y Human Approvals, y la revisó la empresa; esta versión en español es una traducción de la guía original en inglés. Los nombres de campos, valores por defecto y mensajes de rechazo se citan de esas páginas, en inglés con la traducción al lado.

AEGIS by 100monkeys.ai, in beta, ejecuta un agente a partir de un solo archivo YAML. La documentación llama al manifiesto de agente "the source of truth for an Agent's identity, capabilities, security constraints, and execution requirements." (la fuente de verdad sobre la identidad, las capacidades, las restricciones de seguridad y los requisitos de ejecución de un agente). Esta guía lo recorre sección por sección y dice, para cada campo, qué hace con él el orquestador.

Paso 1. Escribe la cabecera

apiVersion: 100monkeys.ai/v1
kind: Agent
metadata:
  name: pr-reviewer
  version: "1.0.0"
  description: "Reviews pull request diffs and returns structured feedback."

apiVersion y kind deben tener exactamente estos valores. name debe cumplir ^[a-z0-9][a-z0-9-]{0,62}$, y el par de name y version debe ser único: desplegar otra vez el mismo par falla salvo que pases --force. labels y annotations son mapas opcionales de clave y valor para descubrimiento y notas.

Paso 2. Elige un runtime

spec.runtime es la única parte obligatoria de spec. Da language y version (python, javascript, typescript, rust o go, que se resuelven a una imagen oficial) o una image completamente cualificada, nunca ambas; language sin version no es válido. image_pull_policy vale por defecto IfNotPresent. model nombra un alias de modelo de aegis-config.yaml, y se rechaza un alias que genera imágenes. isolation acepta inherit, docker, firecracker y process; la referencia marca docker como Fase 1 y los otros dos como Fase 2.

Paso 3. Dale una tarea

task.instruction es la guía con la que trabaja el agente, y fijarla "auto-enables semantic validation" (activa automáticamente la validación semántica). task.prompt_template es una plantilla Handlebars; sus variables son {{intent}}, {{instruction}}, {{input}}, {{iteration_number}}, {{previous_error}} y {{context}}. spec.input_schema, un JSON Schema con type: object, declara entradas con nombre y las valida antes de que el agente se ejecute.

Paso 4. Declara solo el acceso que necesita

"All permissions are deny-by-default." (Todos los permisos están denegados por defecto.) Sin spec.security, el agente no tiene red ni acceso al sistema de archivos. network.mode es allow (solo la allowlist), deny (todo salvo la denylist) o none, que "attaches no network interface to the container" (no conecta ninguna interfaz de red al contenedor). filesystem.read y filesystem.write listan rutas, con globs permitidos. Los recursos valen por defecto cpu: 1000 milicores, memory: "512Mi", disk: "1Gi" y timeout: "1800s", con un máximo de una hora. Cuando el agente puede intentarlo dos veces o más, el timeout debe caber en dos intentos completos, 2 × (iteration_timeout + el timeout_seconds de los jueces) + 45 s, o el agente "is refused on create and update" (se rechaza al crear y al actualizar).

Paso 5. Monta sus volúmenes

Cada entrada de spec.volumes[] tiene un name, una storage_class (ephemeral necesita ttl_hours; persistent necesita source.volume_id), un mount_path con raíz en /workspace y un access_mode. El acceso de lectura y escritura a un volumen persistente es exclusivo de una ejecución a la vez. Un volumen que no se puede montar detiene la iteración: el agente "never runs without its volume." (nunca se ejecuta sin su volumen).

Paso 6. Define cómo itera y qué cuenta como terminado

execution.mode es iterative (por defecto) o one-shot. max_iterations va de 1 a 20, por defecto 5, y max_retries es el mismo campo. iteration_timeout vale por defecto 600s y llm_timeout_seconds 300. Después de cada intento, validation se ejecuta en orden: exit_code, json_schema, regex, semantic (un agente juez, min_score por defecto 0.7) o multi_judge. Un fallo vuelve al agente como {{previous_error}}. tool_validation juzga cada llamada a herramienta antes de que se ejecute; ahí solo se usan entradas semantic. outputs nombra los archivos que la ejecución debe dejar, cada uno con min_bytes y magic opcionales, y si falta uno el intento falla.

Paso 7. Concede herramientas

spec.tools acepta cadenas como "mcp:filesystem" u objetos con name, server y config. Para ejecutar comandos, declara executor: "builtin:cmd" con una subcommand_allowlist obligatoria, un mapa de comando a primeros argumentos permitidos; cualquier otra llamada "is rejected with a policy violation" (se rechaza con una violación de política). El orquestador comprueba que las declaraciones pueden hacer el trabajo: un agente que debe escribir archivos pero no declara herramientas, o que declara fs.write sin un volumen de lectura y escritura, se rechaza al desplegar con una frase que nombra el motivo.

Paso 8. Pasa configuración y secretos

Los valores de spec.env son un literal, "secret:<name>" (inyectado desde OpenBao y "never logged", nunca registrado) o "config:<key>". spec.security_context es solo para operadores de la plataforma; una cuenta de consumidor que lo fija recibe 403 Forbidden.

Paso 9. Valida y luego despliega

aegis agent deploy ./agent.yaml --validate-only
aegis agent deploy ./agent.yaml

--validate-only analiza y valida sin desplegar. aegis agent show <AGENT_ID> muestra de vuelta el manifiesto guardado.

Dónde va un sí humano

El manifiesto de agente no tiene campo de aprobación. El sí de una persona pertenece a un workflow, en un estado de kind: Human: prompt es obligatorio, timeout vale por defecto 3600s y default_response es la respuesta que se toma cuando vence; sin ella, el workflow falla. Human Approvals dice que la transición input_equals_yes de una puerta acepta yes y que input_equals_no acepta no, y que una respuesta que ninguna transición acepta se rechaza y se vuelve a pedir.

Lo que la documentación deja abierto

Las dos referencias no coinciden en las palabras de la puerta: la Workflow Manifest Reference hace que input_equals_yes acepte "yes", "approve", "approved" o "true"; Human Approvals dice yes, y o 1. Esta guía sigue Human Approvals.
metadata.version se llama "semantic version" (versión semántica) en el ejemplo y "Manifest schema version" (versión del esquema del manifiesto) en la tabla.
firecracker y process aparecen como valores válidos de isolation, marcados Fase 2; la referencia no dice qué pasa hoy si un manifiesto nombra uno.

Para ejecutar un manifiesto de principio a fin en un servidor nuevo, lee Instala AEGIS en un VPS Ubuntu nuevo y ejecuta tu primera tarea aprobada. AEGIS se instala con el comando que aparece en 100monkeys.ai:

curl -fsSL https://get.100monkeys.ai | bash

Instala AEGIS desde 100monkeys.ai