Agents and Roles
La jerarquía de agentes del lab: quién existe, qué hace cada uno, a quién hace handoff y cuáles son los non-goals explícitos.
Propósito
Esta página es la referencia canónica de la jerarquía de agentes del lab. Documenta los agentes, sus responsabilidades, sus handoffs y la matriz que mapea intent a agent.
Las páginas detalladas per-agent están en este directorio:
Los context boundaries están en Context Boundaries.
Los cinco agentes
Coordinator
El punto de contacto primario del usuario. Rutea requests al specialized agent adecuado, gestiona sesiones y memoria, y surface resultados.
| Aspect | Detail |
|---|---|
| Runs in | El main gateway process. |
| Port | 18789 (default). |
| Lifespan | Always on. |
| Trigger | La request en lenguaje natural del usuario. |
| Output | Una respuesta en lenguaje natural, posiblemente con artifacts. |
| Escalation | Ninguna (el Coordinator está en la cima de la jerarquía). |
Coding Assistant
El brazo de implementación. Delega tasks de code-writing a un coding sub-agent sandboxed a través de scoped prompts. Revisa, integra y testea el resultado.
| Aspect | Detail |
|---|---|
| Runs in | Invocado por el Coordinator (sin gateway dedicado). |
| Sandbox | workspace-write por defecto. |
| Trigger | "code", "implement", "build" — el usuario quiere código. |
| Output | El código integrado + resultados de tests. |
| Escalation | Vuelve al Coordinator cuando la task termina o cuando no puede continuar. |
El Coding Assistant no escribe código directamente. Delega al coding sub-agent. Esta es una hard rule documentada en ADR-002.
Research Worker
El especialista en research. Opera el Research Framework de extremo a extremo. Parsea queries, corre el phase DAG, persiste artefacts, devuelve el report.
| Aspect | Detail |
|---|---|
| Runs in | El Scout gateway process. |
| Port | 18790 (default). |
| Trigger | "research", "find", "search" — el usuario quiere información. |
| Output | Un fichero report.md + un summary estructurado. |
| Escalation | Vuelve al Coordinator con el resultado o con el fallo. |
El Research Worker es el único agente que escribe los research artifacts. El Coordinator los lee bajo demanda.
Media Agent
El especialista en entretenimiento. Maneja búsqueda de media, identificación de fuentes de streaming y control de playback a dispositivos locales y remotos.
| Aspect | Detail |
|---|---|
| Runs in | El Scout gateway process (mismo que el Research Worker, distinto rol). |
| Trigger | "play", "stream", "cast" — el usuario quiere media. |
| Output | Un resultado de playback (playback iniciado en el dispositivo target). |
| Escalation | Vuelve al Coordinator con el resultado o con el fallo. |
El Media Agent no tiene memoria persistente. Es stateless más allá de su configuración.
Web Agent
La capacidad de browser automation. Maneja un browser basado en Chromium a través del OpenClaw browser control server, expone el accessibility tree, soporta los web flows comunes.
| Aspect | Detail |
|---|---|
| Runs in | El main gateway process (mismo que el Coordinator). |
| Trigger | "browse", "open", "navigate" — el usuario quiere interactuar con una página web. |
| Output | Un snapshot de la página actual, o el resultado de un flow. |
| Escalation | Vuelve al Coordinator con el resultado o con el fallo. |
El Web Agent es una thin layer sobre la herramienta browser de OpenClaw. No mantiene su propio state; el browser guarda el state.
Matriz intent → agent
| User says | Agent |
|---|---|
| "Research X for Y" | Research Worker |
| "Find me information about Z" | Research Worker |
| "Search the web for W" | Web Agent (o Research Worker) |
| "Implement this in repo Y" | Coding Assistant |
| "Build me a tool that does X" | Coding Assistant |
| "Add feature Z to project W" | Coding Assistant |
| "Play X on the TV" | Media Agent |
| "Stream Y to the speaker" | Media Agent |
| "Cast Z to the Chromecast" | Media Agent |
| "Generate an image of W" | Media Lab Server (llamado por Media Agent o Coordinator) |
| "Generate a music track of X" | Media Lab Server (llamado por Media Agent o Coordinator) |
| "Open URL Y in the browser" | Web Agent |
| "Find hotels in W for date X" | Research Worker + Web Agent |
| "Book a hotel in W for date X" | Web Agent (tras research) |
La matriz es una guideline, no una hard rule. El Coordinator la usa como punto de partida y hace una clarifying question cuando el intent es ambiguo.
Handoffs
Los agents no se llaman entre sí directamente. El Coordinator es el único agent que dispatcha a los demás. Los handoffs son:
| From | To | When |
|---|---|---|
| Coordinator | Research Worker | El usuario pide research. |
| Coordinator | Coding Assistant | El usuario pide código. |
| Coordinator | Media Agent | El usuario pide media. |
| Coordinator | Web Agent | El usuario pide browse. |
| Research Worker | Coordinator | El research termina; el report está listo. |
| Research Worker | Coordinator | El research falla; el Coordinator surface el error. |
| Coding Assistant | Coordinator | El código está integrado y testeado. |
| Coding Assistant | Coordinator | El sub-agent es matado; el Coordinator decide qué hacer. |
| Media Agent | Coordinator | El playback se inicia. |
| Media Agent | Coordinator | El playback falla; el Coordinator surface el error. |
| Web Agent | Coordinator | El flow se completa; el snapshot está listo. |
| Web Agent | Coordinator | El flow falla; el Coordinator decide qué hacer. |
Los handoffs son todos a través del Coordinator. No hay comunicación agent-to-agent.
Non-goals
Cada agent tiene non-goals explícitos. Los non-goals son lo que el agent NO hace, incluso si el usuario lo pide.
| Agent | Non-goals |
|---|---|
| Coordinator | No ejecuta tasks. No escribe código. |
| Coding Assistant | No escribe código directamente. No hace commit ni push. |
| Research Worker | No reproduce media. No navega. No escribe código. |
| Media Agent | No hace research. No navega. No escribe código. |
| Web Agent | No reproduce media. No hace research. No escribe código. |
Los non-goals son los boundaries que evitan que un agent derive fuera de su rol. Una violación de non-goal es un bug.
Role separation
Los agentes están diseñados con role separation estricta. Los principios:
- One responsibility per agent. Cada agent tiene una única responsabilidad primaria.
- No shared state. Los agents no comparten memoria ni ficheros excepto a través del Coordinator o de la artifact layer.
- No agent calls another directly. Toda la comunicación inter-agent pasa por el Coordinator.
- No agent bypasses the Coordinator. El Coordinator es el único entry point para el usuario.
- The Coding Assistant is a sub-agent, not an orchestrator. No rutea requests a otros agents.
Estos principios son la base de los Context Boundaries y de los ADR-001 y ADR-002.
Cuándo añadir un nuevo agent
El lab añade un nuevo agent cuando:
- Emerge una responsabilidad nueva que ningún agent actual puede manejar.
- La nueva responsabilidad es lo bastante grande para justificar un proceso separado y un conjunto separado de herramientas.
- La nueva responsabilidad es ortogonal a los agents existentes (no hay overlap).
El lab NO añade un nuevo agent cuando:
- Bastaría con un pequeño ajuste a un agent existente.
- La nueva responsabilidad es una task one-off.
- La nueva responsabilidad se puede implementar como una herramienta para un agent existente.
La decisión de añadir un nuevo agent se registra como un ADR.