Agents

Agents are the core resource in Kakunin — they represent AI systems that need cryptographic identity and compliance monitoring.

Overview

An agent is any AI system you want to register, certify, and monitor. This could be a trading bot, a document processor, a customer-facing assistant, or any other automated system.

Agent Lifecycle

pending → active → suspended → retired
              ↑         |
              └─────────┘ (reactivate)

Status	Meaning
`pending`	Registered, awaiting first certificate
`active`	Certified and operational
`suspended`	Certificate revoked (risk threshold or manual)
`retired`	Permanently decommissioned

Create an Agent

POST /v1/agents

{
  "name": "trading-bot-prod",
  "model": "gpt-4o",
  "version": "1.0.0"
}

Response 201:

{
  "data": {
    "id": "uuid",
    "name": "trading-bot-prod",
    "model": "gpt-4o",
    "version": "1.0.0",
    "status": "pending",
    "tenant_id": "uuid",
    "created_at": "2026-05-17T00:00:00Z"
  }
}

List Agents

GET /v1/agents

Returns all agents for the authenticated tenant.

Certify an Agent

Issuing a certificate transitions the agent from pending to active and provisions an AgentMail inbox automatically.

POST /v1/agents/{id}/certify

See Certificates for full details.

Agent Inbox

After certification, each agent receives a dedicated email inbox at @agentmail.to. Inbound messages are stored in Supabase Storage and logged in the audit trail.