Agent Protocol

A standardised protocol for agent-server communication. Implement it in any language to build portable agents.

Overview

The Agent Protocol defines how agents register with a server, receive tasks, and report results. Communication happens over a local channel (in-process for embedded agents) or WebSocket (for standalone agents).

Lifecycle

1. Register — agent declares its name, version, and capabilities
2. Ready — server acknowledges and grants access to requested resources
3. Dispatch — server sends work items when triggers fire
4. Result — agent reports task completion (success, failure, or retry)
5. Heartbeat — periodic health checks to detect stuck agents
6. Shutdown — graceful stop with drain period for in-flight tasks

Message Format

All messages are JSON objects with a type field:

// Agent → Server: register on startup
{
  "type":    "register",
  "agent":   "cleanup-agent",
  "version": "1.0.0",
  "capabilities": ["database:read", "database:write"]
}

// Server → Agent: dispatch work
{
  "type":    "dispatch",
  "task_id": "abc-123",
  "trigger": "schedule",
  "config":  { "retention_days": 30 }
}

// Agent → Server: report result
{
  "type":    "result",
  "task_id": "abc-123",
  "status":  "success",
  "data":    { "deleted": 42 }
}

Message Types

Result Statuses