---
name: agent-orchestration
description: How to use the agent registry, leases, and orchestrator for multi-agent workflows
tags: [agents, orchestration, delegation, leases]
category: system
---
## Steps
1. **Agent Registry:**
   - agent-list — list all registered agents (ID, type, capabilities, status)
   - agent-register <name> <capabilities> — register a new agent (capabilities: comma-separated like "code,research")
   - agent-unregister <id> — remove an agent
   - agent-status <id> — detailed status including uptime, task history

2. **A2A Scratchpad (agent communication bus):**
   - a2a-post <to> <type> <capability> <payload...> — post a message to an agent
   - a2a-poll [agentId] — poll for pending messages (default: current agent or "user")
   - a2a-ack <msgId> <result...> — acknowledge a message with result
   - a2a-reject <msgId> <error...> — reject a message with error
   - a2a-status — show scratchpad stats per agent
   - a2a-prune — cleanup expired messages
   - Messages live in /_agents/scratchpad.json (shared VFS file, no central broker)
   - Agents auto-register on spawn, auto-unregister on kill

3. **Leases (time-bound contracts):**
   - lease-create <agent-id> <ttl-seconds> — create a lease with watchdog timer
   - lease-list — show active leases with remaining TTL
   - lease-revoke <lease-id> — terminate a lease early
   - lease-renew <lease-id> <ttl-seconds> — extend a lease

3. **Orchestrator (spawn, delegate, kill):**
   - orchestrator-spawn <type> <capabilities> — spawn a new agent automatically (registers + creates lease)
   - orchestrator-kill <agent-id> — kill an agent (revokes lease + unregisters)
   - orchestrate — list all active agents with their orchestrator state
   - orchestrator-purge — kill all idle/expired agents
   - orchestrator-status — full system status: active, idle, dead agents

4. **AI tool integration:**
   - AI tools list_agents, delegate_task, spawn_agent are available in the AI system prompt
   - The AI can auto-spawn worker agents for sub-tasks
   - Each agent gets its own VFS workspace at /agents/<agent-id>/

5. **When to use:**
   - User needs parallel task execution → orchestrator-spawn coder + researcher
   - Time-bound automation → lease-create with short TTL
   - System cleanup → orchestrator-purge to kill stale agents