Agents and Roles
The lab's agent hierarchy: who exists, what each one does, who they hand off to, and what the explicit non-goals are.
Purpose
This page is the canonical reference for the lab's agent hierarchy. It documents the agents, their responsibilities, their handoffs, and the matrix that maps intent to agent.
The detailed per-agent pages are in this directory:
The context boundaries are in Context Boundaries.
The five agents
Coordinator
The user's primary point of contact. Routes requests to the appropriate specialized agent, manages sessions and memory, surfaces results.
| Aspect | Detail |
|---|---|
| Runs in | The main gateway process. |
| Port | 18789 (default). |
| Lifespan | Always on. |
| Trigger | The user's natural-language request. |
| Output | A natural-language response, possibly with artifacts. |
| Escalation | None (the Coordinator is the top of the hierarchy). |
Coding Assistant
The implementation arm. Delegates code-writing tasks to a sandboxed coding sub-agent through scoped prompts. Reviews, integrates, and tests the result.
| Aspect | Detail |
|---|---|
| Runs in | Invoked by the Coordinator (no dedicated gateway). |
| Sandbox | workspace-write by default. |
| Trigger | "code", "implement", "build" — the user wants code. |
| Output | The integrated code + test results. |
| Escalation | Returns to the Coordinator when the task is done or when it cannot proceed. |
The Coding Assistant does not write code directly. It delegates to the coding sub-agent. This is a hard rule documented in ADR-002.
Research Worker
The research specialist. Operates the Research Framework end-to-end. Parses queries, runs the phase DAG, persists artifacts, returns the report.
| Aspect | Detail |
|---|---|
| Runs in | The Scout gateway process. |
| Port | 18790 (default). |
| Trigger | "research", "find", "search" — the user wants information. |
| Output | A report.md file + a structured summary. |
| Escalation | Returns to the Coordinator with the result or the failure. |
The Research Worker is the only agent that writes to the research artifacts. The Coordinator reads them on demand.
Media Agent
The entertainment specialist. Handles media search, streaming source identification, and playback control to local and remote devices.
| Aspect | Detail |
|---|---|
| Runs in | The Scout gateway process (same as the Research Worker, different role). |
| Trigger | "play", "stream", "cast" — the user wants media. |
| Output | A playback result (initiated playback on the target device). |
| Escalation | Returns to the Coordinator with the result or the failure. |
The Media Agent has no persistent memory. It is stateless beyond its configuration.
Web Agent
The browser automation capability. Drives a Chromium-based browser through the OpenClaw browser control server, exposes the accessibility tree, supports common web flows.
| Aspect | Detail |
|---|---|
| Runs in | The main gateway process (same as the Coordinator). |
| Trigger | "browse", "open", "navigate" — the user wants to interact with a web page. |
| Output | A snapshot of the current page, or the result of a flow. |
| Escalation | Returns to the Coordinator with the result or the failure. |
The Web Agent is a thin layer over the OpenClaw browser tool. It does not maintain its own state; the browser holds the state.
Intent → agent matrix
| User says | Agent |
|---|---|
| "Research X for Y" | Research Worker |
| "Find me information about Z" | Research Worker |
| "Search the web for W" | Web Agent (or 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 (called by Media Agent or Coordinator) |
| "Generate a music track of X" | Media Lab Server (called by Media Agent or 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 (after research) |
The matrix is a guideline, not a hard rule. The Coordinator uses it as a starting point and asks a clarifying question when the intent is ambiguous.
Handoffs
Agents do not call each other directly. The Coordinator is the only agent that dispatches to others. The handoffs are:
| From | To | When |
|---|---|---|
| Coordinator | Research Worker | The user asks for research. |
| Coordinator | Coding Assistant | The user asks for code. |
| Coordinator | Media Agent | The user asks for media. |
| Coordinator | Web Agent | The user asks to browse. |
| Research Worker | Coordinator | The research is done; report is ready. |
| Research Worker | Coordinator | The research failed; Coordinator surfaces the error. |
| Coding Assistant | Coordinator | The code is integrated and tested. |
| Coding Assistant | Coordinator | The sub-agent is killed; Coordinator decides what to do. |
| Media Agent | Coordinator | The playback is initiated. |
| Media Agent | Coordinator | The playback failed; Coordinator surfaces the error. |
| Web Agent | Coordinator | The flow is complete; the snapshot is ready. |
| Web Agent | Coordinator | The flow failed; Coordinator decides what to do. |
The handoffs are all through the Coordinator. There is no agent-to-agent communication.
Non-goals
Each agent has explicit non-goals. The non-goals are what the agent does NOT do, even if the user asks.
| Agent | Non-goals |
|---|---|
| Coordinator | Does not execute tasks. Does not write code. |
| Coding Assistant | Does not write code directly. Does not commit or push. |
| Research Worker | Does not play media. Does not browse. Does not write code. |
| Media Agent | Does not research. Does not browse. Does not write code. |
| Web Agent | Does not play media. Does not research. Does not write code. |
The non-goals are the boundaries that prevent an agent from drifting outside its role. A non-goal violation is a bug.
Role separation
The agents are designed with strict role separation. The principles:
- One responsibility per agent. Each agent has a single primary responsibility.
- No shared state. Agents do not share memory or files except through the Coordinator or the artifact layer.
- No agent calls another directly. All inter-agent communication goes through the Coordinator.
- No agent bypasses the Coordinator. The Coordinator is the only entry point for the user.
- The Coding Assistant is a sub-agent, not an orchestrator. It does not route requests to other agents.
These principles are the basis for the Context Boundaries and the ADR-001 and ADR-002.
When to add a new agent
The lab adds a new agent when:
- A new responsibility emerges that no current agent can handle.
- The new responsibility is large enough to justify a separate process and a separate set of tools.
- The new responsibility is orthogonal to the existing agents (no overlap).
The lab does NOT add a new agent when:
- A small adjustment to an existing agent would suffice.
- The new responsibility is a one-off task.
- The new responsibility can be implemented as a tool for an existing agent.
The decision to add a new agent is recorded as an ADR.