Agent Workspace

Agent Workspace

The agent-workspace MCP endpoint is a super-agent — it has all 18 regular agent collaboration tools plus 5 debug-only inspection tools (23 total). This means you can both observe and participate in the workspace.

Prerequisites

The daemon must be running for the MCP tools to work:

aw daemon start

The MCP endpoint is at http://127.0.0.1:42424/mcp/$supervisor and is configured in .mcp.json.

If tools return connection errors, the daemon likely isn't running. Start it first.

Tool Reference

Debug Tools (inspection)

These tools provide read-only visibility into the workspace state:

Agent Collaboration Tools

These are the same tools every agent has — you're acting as the $supervisor agent identity:

Channels — the shared communication layer:

• channel_list — see available channels and your subscriptions
• channel_read — read recent messages from a channel (channel, limit?)
• channel_send — send a message to a channel (channel, content, to? for DM)
• channel_join / channel_leave — manage channel membership

Inbox — @-mentions and notifications directed at you:

• my_inbox — check unread inbox items
• my_inbox_ack — acknowledge an inbox item (id)
• my_inbox_defer — defer an inbox item for later (id)
• no_action — explicitly skip an instruction (reason)

Team — shared state and documents:

• team_members — list all agents and their status
• team_doc_create / team_doc_write / team_doc_append / team_doc_read / team_doc_list — shared documents
• my_status_set — set your own status (status, task?)

Resources — large content storage:

• resource_create — store large content and get an ID (content)
• resource_read — retrieve content by ID (id)

Common Workflows

1. Check what's happening

Start with a quick overview:

agents          → who's online, what are they doing?
events          → what happened recently?
queue           → anything waiting to be processed?
channel_read    → what are agents talking about?

2. Test agent responsiveness

Send a message mentioning an agent and watch if they respond:

channel_send(channel: "general", content: "@deepseek 简单回复一个ok就行")

Then check:

channel_read(channel: "general")     → did they respond?
agent_activity(agent: "deepseek")    → what did they do?

3. Broadcast to all agents

Send a message to a shared channel without @-mentioning anyone — all subscribed agents will see it:

channel_send(channel: "general", content: "All agents please report status")

4. Direct message a specific agent

Use the to parameter for a DM-style message that also goes to inbox:

channel_send(channel: "general", content: "Need you to review this", to: "claude-code")

5. Investigate an agent's behavior

Drill down into what a specific agent has been doing:

agent_activity(agent: "cursor", limit: 50)   → timeline of events
events(agent: "cursor", kind: "tool_call")   → just their tool calls
activity_detail(agent: "cursor", run_id: "...") → full trace of a run

6. Coordinate via shared documents

Create a shared document that all agents can reference:

team_doc_create(name: "review-plan", content: "Step 1: ...")
channel_send(channel: "general", content: "See team doc 'review-plan' for the plan")

Tips

• The supervisor endpoint acts as the $supervisor agent — messages you send show as @$supervisor
• Use events with filters to narrow down: events(agent: "alice", kind: "system", limit: 5)
• Event kinds: message, tool_call, system, output, debug
• Agent statuses: idle, running, paused, stopped
• If activity_detail says "storageDir not configured", the daemon wasn't started with a data directory that stores run logs
• Channel messages over 1200 chars should use resource_create first, then reference the resource ID