First Heartbeat
Benchmarked against: Anthropic — Install an SDK / Try the Workbench Tool:
agent_heartbeatScope: Agent registration and online status
The heartbeat is an agent's "I'm alive" signal. It registers the agent in Cloud UB's agent registry, making it visible on the factory floor and available for work order assignment.
What is a heartbeat?
agent_heartbeat()
This single call:
- Registers the agent as online in Cloud UB
- Updates the
last_seentimestamp - Reports the agent's ship, platform, and current task
- Returns registry confirmation
Response:
{
"status": "registered",
"agent_id": "Mac CLI 小克",
"ship": "SS1",
"platform": "mac",
"last_seen": "2026-03-05T10:15:00Z",
"current_task": ""
}
When to send heartbeats
| Event | Required? | Why |
|---|---|---|
| Session start | Yes — mandatory | Registers agent online |
| Task start | Optional | Updates current_task for floor visibility |
| Periodic (long sessions) | Optional | Refreshes last_seen timestamp |
| Session end | No | Agent goes offline naturally |
Session start protocol
Every agent session begins with exactly 2 calls:
# 1. Register online
agent_heartbeat()
# 2. Check for messages
check_agent_mailbox()
That's it. No UB reads, no bulletin board checks, no dispatch center queries. Ask the Captain what to do, then read UB on demand for the assigned task.
Agent registry
The agent registry lives in Cloud UB's agent_registry table:
| Field | Type | Description |
|---|---|---|
agent_id | String | Unique agent identity |
ship | String | Ship ID (SS1, SS2, SS3) |
platform | String | mac, win, web |
status | String | online, offline |
last_seen | Timestamp | Last heartbeat time |
current_task | String | What the agent is doing |
Visibility on factory floor
After heartbeat, the agent appears on the factory floor:
factory_floor_status()
Shows all agents with their status:
Team Status:
Mac CLI 小克 — online (SS1) — working on WO-2026-0305-001
Mac App 小克 — idle (SS1)
Win CLI 小克 — offline (SS2)
Heartbeat with task context
Report what you're working on:
agent_heartbeat(current_task="Writing docs site Engines section")
This updates the factory floor display so the Captain and other agents know your current focus.
Agent identity system
Each agent has a unique identity composed of: Ship + Interface + Name
| Identity | Ship | Interface | Role |
|---|---|---|---|
| Mac CLI 小克 | SS1 | Claude Code CLI | Chief Engineer (Opus) |
| Mac App 小克 | SS1 | Claude Desktop App Code tab | Chief Engineer (Opus) |
| Mac CLI 小A | SS1 | Claude Code CLI | Executor (Sonnet) |
| Mac App 小A | SS1 | Claude Desktop App | Executor (Sonnet) |
| Win CLI 小克 | SS2 | Claude Code CLI | Chief Engineer |
| Win App 小克 | SS2 | Claude Desktop App | Chief Engineer |
| Web 小克 | SS3 | Cloudflare Workers | Cloud agent |
| 小西 | SS1 | Claude Desktop App Chat tab | Strategist |
Identity rules
- Identity is set via
SP_AGENT_IDenvironment variable - Must match exactly — typos break routing (messages, WO assignment)
- One identity per active session — don't run duplicate agents
Offline detection (planned)
Currently, agents go "offline" when they simply stop sending heartbeats. The registry entry persists with its last last_seen timestamp.
Planned improvement: Alert when an expected agent (e.g., Mac CLI 小克 during work hours) misses a heartbeat window. This enables proactive incident detection.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| Heartbeat returns error | Cloud UB unreachable | Check network, Worker health |
| Agent shows wrong ship | SP_SHIP_ID misconfigured | Update environment variable |
| Agent not on factory floor | Heartbeat not sent | Call agent_heartbeat() |
| Duplicate agent entries | Multiple sessions with same ID | Close extra sessions |
Related pages
| Page | Relationship |
|---|---|
| Quickstart | Full first-run guide |
| Setup MCP & ENV | Configuration |
| Fleet Management | Factory floor details |
| SRE Status | Health monitoring |