mission-control/docs/agent-setup.md

Agent Setup Guide

This guide covers everything you need to configure agents in Mission Control: registration methods, SOUL personalities, working files, configuration, and liveness monitoring.

Agent Registration

There are three ways to register agents with Mission Control.

Method 1: API Self-Registration (Recommended for Autonomous Agents)

Agents register themselves at startup. This is the simplest path and requires no manual setup:

curl -X POST http://localhost:3000/api/agents/register \
  -H "Authorization: Bearer $MC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "scout",
    "role": "researcher",
    "capabilities": ["web-search", "summarization"],
    "framework": "claude-sdk"
  }'

Name rules: 1-63 characters, alphanumeric plus ., -, _. Must start with a letter or digit.

Valid roles: coder, reviewer, tester, devops, researcher, assistant, agent

The endpoint is idempotent — registering the same name again updates the agent's status to idle and refreshes last_seen. Rate-limited to 5 registrations per minute per IP.

Method 2: Manual Creation (UI or API)

Create agents through the dashboard UI or the API:

curl -X POST http://localhost:3000/api/agents \
  -H "Authorization: Bearer $MC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "aegis",
    "role": "reviewer",
    "status": "offline",
    "soul_content": "You are Aegis, the quality reviewer...",
    "config": {
      "dispatchModel": "9router/cc/claude-opus-4-6",
      "openclawId": "aegis"
    }
  }'

This requires operator role and supports additional fields like soul_content, config, and template.

Method 3: Config Sync (OpenClaw or Local Discovery)

Mission Control can auto-discover agents from:

OpenClaw config sync — Reads agents from your openclaw.json file:

curl -X POST http://localhost:3000/api/agents/sync \
  -H "Authorization: Bearer $MC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"source": "config"}'

Set OPENCLAW_CONFIG_PATH to point to your openclaw.json.

Local agent discovery — Scans standard directories for agent definitions:

curl -X POST http://localhost:3000/api/agents/sync \
  -H "Authorization: Bearer $MC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"source": "local"}'

Scanned directories:

• ~/.agents/ — Top-level agent directories or .md files
• ~/.codex/agents/ — Codex agent definitions
• ~/.claude/agents/ — Claude Code agent definitions
• ~/.hermes/skills/ — Hermes skill definitions

Agent directories are detected by the presence of marker files: soul.md, AGENT.md, identity.md, config.json, or agent.json.

Flat markdown files (Claude Code format) are also supported:

---
name: my-agent
description: A research assistant
model: claude-opus-4
tools: ["read", "write", "web-search"]
---
You are a research assistant specializing in competitive analysis...

SOUL.md — Agent Personality

SOUL is the personality and capability definition for an agent. It's a markdown file that gets injected into dispatch prompts, shaping how the agent approaches tasks.

What Goes in a SOUL

A SOUL defines:

• Identity — Who the agent is, its name, role
• Expertise — What domains it specializes in
• Behavior — How it approaches problems, communication style
• Constraints — What it should avoid, limitations

Example: Developer Agent

# Scout — Developer

You are Scout, a senior developer agent specializing in full-stack TypeScript development.

## Expertise
- Next.js, React, Node.js
- Database design (PostgreSQL, SQLite)
- API architecture and testing

## Approach
- Read existing code before proposing changes
- Write tests alongside implementation
- Keep changes minimal and focused

## Constraints
- Never commit secrets or credentials
- Ask for clarification on ambiguous requirements
- Flag security concerns immediately

Example: Researcher Agent

# Iris — Researcher

You are Iris, a research agent focused on gathering and synthesizing information.

## Expertise
- Web research and source verification
- Competitive analysis
- Data synthesis and report writing

## Approach
- Always cite sources with URLs
- Present findings in structured format
- Distinguish facts from inferences

## Output Format
- Use bullet points for key findings
- Include a "Sources" section at the end
- Highlight actionable insights

Example: Reviewer Agent

# Aegis — Quality Reviewer

You are Aegis, the quality gate for all agent work in Mission Control.

## Role
Review completed tasks for correctness, completeness, and quality.

## Review Criteria
- Does the output address all parts of the task?
- Are there factual errors or hallucinations?
- Is the work actionable and well-structured?

## Verdict Format
Respond with EXACTLY one of:

VERDICT: APPROVED
NOTES: <brief summary>

VERDICT: REJECTED
NOTES: <specific issues to fix>

Managing SOUL Content

Read an agent's SOUL:

curl -s http://localhost:3000/api/agents/1/soul \
  -H "Authorization: Bearer $MC_API_KEY" | jq

Response:

{
  "soul_content": "# Scout — Developer\n...",
  "source": "workspace",
  "available_templates": ["developer", "researcher", "reviewer"],
  "updated_at": 1711234567
}

The source field tells you where the SOUL was loaded from:

• workspace — Read from the agent's workspace soul.md file on disk
• database — Read from the MC database (no workspace file found)
• none — No SOUL content set

Update a SOUL:

curl -X PUT http://localhost:3000/api/agents/1/soul \
  -H "Authorization: Bearer $MC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"soul_content": "# Scout — Developer\n\nYou are Scout..."}'

Apply a template:

curl -X PUT http://localhost:3000/api/agents/1/soul \
  -H "Authorization: Bearer $MC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"template_name": "developer"}'

Templates support substitution variables: {{AGENT_NAME}}, {{AGENT_ROLE}}, {{TIMESTAMP}}.

SOUL content syncs bidirectionally — edits in the UI write back to the workspace soul.md file, and changes on disk are picked up on the next sync.

WORKING.md — Runtime Scratchpad

WORKING.md is an agent's runtime state file. It tracks:

• Current task context
• Intermediate results
• Session notes from the agent's perspective

Do not hand-edit WORKING.md — it's written and managed by the agent during task execution. If you need to give an agent persistent instructions, use SOUL.md instead.

Agent Configuration

Each agent has a JSON config object stored in the database. Key fields:

Field	Type	Description
openclawId	string	Gateway agent identifier (falls back to agent name)
dispatchModel	string	Model override for auto-dispatch (e.g., 9router/cc/claude-opus-4-6)
capabilities	string[]	List of agent capabilities
framework	string	Framework that created the agent (e.g., claude-sdk, crewai)

Example config:

{
  "openclawId": "scout",
  "dispatchModel": "9router/cc/claude-sonnet-4-6",
  "capabilities": ["code-review", "testing", "documentation"],
  "framework": "claude-sdk"
}

Update via API:

curl -X PUT http://localhost:3000/api/agents \
  -H "Authorization: Bearer $MC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": 1,
    "config": {
      "dispatchModel": "9router/cc/claude-opus-4-6"
    }
  }'

Heartbeat and Liveness

Mission Control tracks agent health through heartbeats.

How It Works

1. Agent sends POST /api/agents/{id}/heartbeat every 30 seconds
2. MC updates status to idle and refreshes last_seen
3. If no heartbeat for 10 minutes (configurable), agent is marked offline
4. Stale tasks (in_progress for 10+ min with offline agent) are requeued

Heartbeat Request

curl -X POST http://localhost:3000/api/agents/1/heartbeat \
  -H "Authorization: Bearer $MC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "token_usage": {
      "model": "claude-sonnet-4-6",
      "inputTokens": 1500,
      "outputTokens": 300
    }
  }'

The heartbeat response includes pending work items (assigned tasks, mentions, notifications), so agents can use it as both a keepalive and a lightweight work check.

Agent Status Values

Status	Meaning
offline	No recent heartbeat, agent is unreachable
idle	Online and ready for work
busy	Currently executing a task
sleeping	Paused by user (wake with POST /api/agents/{id}/wake)
error	Agent reported an error state

Agent Sources

The source field on each agent indicates how it was registered:

Source	Origin
manual	Created through UI or direct API call
self	Agent self-registered via /api/agents/register
local	Discovered from ~/.agents/, ~/.claude/agents/, etc.
config	Synced from openclaw.json
gateway	Registered by a gateway connection

Agent Templates

When creating agents via API, you can specify a template name to pre-populate the config:

curl -X POST http://localhost:3000/api/agents \
  -H "Authorization: Bearer $MC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "scout", "role": "coder", "template": "developer"}'

Templates define model tier, tool permissions, and default configuration. Available templates include:

• developer — Full coding toolset (read, write, edit, exec, bash)
• researcher — Read-only tools plus web and memory access
• reviewer — Read-only tools for code review and quality checks

What's Next

• Quickstart — 5-minute first agent tutorial
• Orchestration Patterns — Multi-agent workflows, auto-dispatch, quality review
• CLI Reference — Full CLI command reference