Agent Registry

The agent registry tracks every AI agent connected to your Kanoniv tenant. Agents are auto-registered on first contact - no signup required. The registry provides visibility into which agents are online, what they're doing, and how to coordinate between them.

How It Works

When an agent first calls any Kanoniv API endpoint with an X-Agent-Name header (set via KANONIV_AGENT_NAME env var), it's automatically registered. No separate registration step.

Agent connects with KANONIV_AGENT_NAME=sdr-agent
  -> Auto-registered in agent_registry
  -> Status: online
  -> last_seen_at updated on every request

Status Detection

Agent status is determined automatically from last_seen_at:

Status	Condition	Meaning
online	Last seen < 5 minutes ago	Agent is actively making requests
idle	Last seen 5 min - 1 hour ago	Agent is connected but not active
offline	Last seen > 1 hour ago	Agent has disconnected

Instance Support

Multiple instances of the same agent type can run simultaneously (horizontal scaling). Each instance is uniquely identified by (tenant_id, name, instance_id).

# Two instances of the same SDR agent
KANONIV_AGENT_NAME=sdr-agent KANONIV_INSTANCE_ID=us-east npx @kanoniv/mcp
KANONIV_AGENT_NAME=sdr-agent KANONIV_INSTANCE_ID=eu-west npx @kanoniv/mcp

CLI Commands

# List all registered agents
kanoniv agent who

# Register with a description
kanoniv agent register --name "sdr-agent" --description "Qualifies inbound leads"

# Rename an agent (frees old name for reuse)
kanoniv agent rename old-name new-name

API Reference

Method	Path	Description
POST	/v1/agent-registry/	Register or update an agent
GET	/v1/agent-registry/	List all agents (with live status)
GET	/v1/agent-registry/:name	Get a specific agent
PUT	/v1/agent-registry/:name	Update agent metadata
POST	/v1/agent-registry/:name/rename	Rename (409 on conflict)
POST	/v1/agent-registry/:name/heartbeat	Update last_seen_at

Register / Update

POST /v1/agent-registry/
Content-Type: application/json
X-API-Key: kn_live_...

{
  "name": "sdr-agent",
  "description": "Qualifies inbound leads via email and enrichment",
  "capabilities": ["resolve", "memorize", "search"]
}

List Agents

GET /v1/agent-registry/
X-API-Key: kn_live_...

Response:

[
  {
    "name": "sdr-agent",
    "instance_id": "default",
    "status": "online",
    "description": "Qualifies inbound leads",
    "capabilities": ["resolve", "memorize", "search"],
    "last_seen_at": "2026-03-06T14:30:00Z",
    "registered_at": "2026-03-01T10:00:00Z"
  },
  {
    "name": "crm-agent",
    "instance_id": "default",
    "status": "idle",
    "description": "Syncs entities to Salesforce",
    "capabilities": ["resolve", "mutate"],
    "last_seen_at": "2026-03-06T14:10:00Z",
    "registered_at": "2026-03-02T09:00:00Z"
  }
]

Rename

POST /v1/agent-registry/old-name/rename
Content-Type: application/json
X-API-Key: kn_live_...

{ "new_name": "new-name" }

Returns 409 if new_name is already taken.

MCP Tools

Tool	Description
register_agent	Register or update the current agent
list_agents	List all agents with live status
rename_agent	Rename an agent

Example: Agent self-registration

On first connection, agents should register themselves:

{
  "tool": "register_agent",
  "arguments": {
    "description": "Qualifies inbound leads via email matching",
    "capabilities": ["resolve", "memorize", "search"]
  }
}

The agent name is automatically set from KANONIV_AGENT_NAME.

Sandbox

The agent registry is included in sandbox reset (POST /v1/sandbox/reset). All registered agents in the sandbox tenant are cleared.