Skip to content

agent-setup.md

Latest commit

 

History

History
342 lines (254 loc) · 9.93 KB

agent-setup.md

File metadata and controls

342 lines (254 loc) · 9.93 KB

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