Coordinator
El agente de control principal. El punto de contacto primario del usuario; rutea requests al specialized agent adecuado, gestiona sesiones y memoria, y surface los resultados.
Status
Implemented. El Coordinator es el entry point always-on del usuario. Es el único agente con el que el usuario interactúa directamente en el flujo de lenguaje natural.
Role
El Coordinator es responsable de:
- Recibir la request en lenguaje natural del usuario.
- Entender el intent (research, coding, media, web, mixed).
- Rutear la request al specialized agent adecuado (Research Worker, Coding Assistant, Media Agent, Web Agent).
- Gestionar la sesión (state, memory, context).
- Surfacing el resultado de vuelta al usuario.
- Hacer clarifying questions cuando el intent es ambiguo.
El Coordinator no ejecuta tasks directamente. Es un router, state manager e user interface — no un executor.
Architecture
El Coordinator corre en el main gateway process. Tiene los siguientes componentes:
| Component | Purpose |
|---|---|
| Gateway | La interfaz HTTP/gRPC que recibe las requests del usuario. |
| Request Parser | Tokeniza y parsea la request. |
| Intent Resolver | Mapea la request a uno o más agentes. |
| Router | Dispatcha la request al/los agent(s) seleccionado(s). |
| Memory Layer | Lee/escribe la long-term y daily memory. |
| Session Store | Mantiene el session state. |
| Skill Loader | Activa los skills relevantes. |
| Result Aggregator | Combina resultados de múltiples agentes cuando hace falta. |
Ports and processes
El Coordinator corre en el main gateway process. Los puertos son:
| Port | Process | Purpose |
|---|---|---|
| 18789 | Main gateway | La API HTTP del Coordinator. |
| 18790 | Scout gateway | El gateway del Research Worker. |
| 18800 | Browser CDP | El puerto CDP del browser automation. |
El Coordinator puede alcanzar al Research Worker a través
de su gateway en 127.0.0.1:18790. El browser automation
se alcanza a través de la herramienta browser en el
puerto CDP.
El gateway está supervisado por launchd en macOS o
systemd en Linux. Comando de restart (macOS):
Configuration
El Coordinator se configura por el main configuration file del framework. Los campos relevantes:
| Field | Type | Default | Purpose |
|---|---|---|---|
coordinator.port | integer | 18789 | El puerto del gateway. |
coordinator.max_concurrent | integer | 1 | Máx. requests concurrentes del usuario. |
coordinator.session_timeout_s | integer | 3600 | Idle session timeout. |
coordinator.memory_enabled | boolean | true | Si la memory layer está activa. |
coordinator.skills_enabled | boolean | true | Si el skill loader está activo. |
Los cambios de configuración requieren autorización explícita del usuario.
Routing
El router del Coordinator mapea una request a uno o más agents. Las routing rules son:
| Intent keyword | Agent | Notes |
|---|---|---|
| "research", "find", "search" | Research Worker | "research X for Y" → Research Worker. |
| "code", "implement", "build" | Coding Assistant | "implement X in repo Y" → Coding Assistant. |
| "play", "stream", "cast" | Media Agent | "play X on TV" → Media Agent. |
| "browse", "open", "navigate" | Web Agent | "go to URL" → Web Agent. |
| Mixed intents | Multi-agent | Split por intent; agregar results. |
Cuando el intent es ambiguo, el Coordinator hace una clarifying question. La pregunta se formula para ser informativa sin ser verbosa.
El router está implementado por los componentes
IntentResolver y Router. El router se puede
configurar con custom rules; las default rules cubren
los casos comunes.
Multi-agent requests
Algunas requests abarcan múltiples agents. Por ejemplo, "find a hotel in Barcelona for September and add it to my calendar" es una request de research + calendar. El Coordinator:
- Splitea la request por intent.
- Rutea cada parte al agent adecuado.
- Agrega los resultados.
- Surfacing el resultado combinado al usuario.
La agregación es naive (concatenación con separadores) a menos que se configure una regla de agregación más sofisticada. No se espera que el Coordinator razone entre agents; delega eso al result aggregator.
Memory
El Coordinator es el dueño de la long-term memory layer. La memory layer está documentada en Memory and Context. El resumen:
MEMORY.mdes la long-term, curated memory. Se carga solo en la main session.memory/YYYY-MM-DD.mdes el daily log. Un fichero por día.- Los artefactos de skill (SKILL.md, TOOL.md) los carga el skill loader cuando se activa el skill.
El Coordinator decide qué escribir a memoria y cuándo. La default policy es: escribir decisiones significativas, escribir lessons learned, no escribir secretos. La policy es configurable.
Sessions
El Coordinator mantiene el session state. Una sesión es una conversación continua entre el usuario y el Coordinator. La sesión tiene:
- Un
session_idúnico. - Un start time y un last activity time.
- Un puntero al memory context actual.
- Una lista de agent requests in-flight.
Las sesiones se almacenan en el session store. El default backend es el local filesystem; el Coordinator se puede configurar para usar una database.
El session timeout es configurable (default 1 hora de idle time). Tras el timeout, la sesión se archiva.
Skills
El Coordinator usa el skill loader para activar los
skills relevantes. Un skill es un fichero markdown
(SKILL.md) que describe una capacidad y su workflow.
El skill loader está en
{workspace-root}/.agents/skills/.
El Coordinator activa un skill cuando:
- La request matchea las trigger phrases del skill.
- El skill está en el allowlist del usuario.
El skill loader devuelve las instrucciones del skill, que el Coordinator sigue. El Coordinator no modifica las instrucciones del skill; las ejecuta tal cual.
Request lifecycle
Una request fluye a través del Coordinator así:
El Coordinator loguea la request y el resultado en el
session log. El session log está en
{workspace-root}/sessions/<session_id>/log.jsonl.
User interface
El Coordinator expone un pequeño CLI para operaciones ad-hoc. El CLI es el main entry point del framework. Los comandos documentados son:
| Command | Purpose |
|---|---|
{cli} session list | Listar active sessions. |
{cli} session resume {id} | Reanudar una sesión pausada. |
{cli} session end {id} | Terminar una sesión. |
{cli} memory search "{query}" | Buscar en la memory layer. |
{cli} memory write "{content}" | Append al daily log de hoy. |
{cli} skill list | Listar skills disponibles. |
{cli} skill activate {name} | Activar un skill. |
El cheatsheet completo está en Cheatsheet → Coordinator.
Failure modes
| Failure | Coordinator response |
|---|---|
| The gateway is unreachable | Devolver un error "service unavailable" al usuario. |
| The Research Worker is unreachable | Surface el error; ofrecer reintentar más tarde. |
| The Coding Assistant is killed by timeout | Aplicar el procedure Coding Assistant killed by timeout. |
| A request is ambiguous | Hacer una clarifying question. |
| The session has expired | Ofrecer reanudar la sesión. |
| The memory layer is full | Aplicar la retention policy. |
| The skill loader fails | Loguear el error; continuar sin el skill. |
El failure catalog completo está en Failure Catalog.
Future work
- Multi-user sessions. Permitir que múltiples usuarios compartan un Coordinator (con sesiones per-user).
- Voice interface. Añadir una interfaz basada en voz.
- Proactive suggestions. Surfacing de información relevante al usuario según el contexto.
- Cross-session memory. Compartir memoria entre sesiones de forma controlada.