Event Ingest

Stream behaviour events from your AI agents to Kakunin for real-time risk scoring and anomaly detection.

Overview

Every action your agent takes can be recorded as a behaviour event. Kakunin scores each event in real time and returns a risk band.

Supported Action Types

Action	Description
`tool_call`	Agent invoked an external tool or API
`message_sent`	Agent sent a message to a user or system
`data_access`	Agent read or queried a data source
`decision_made`	Agent made a significant autonomous decision
`error_occurred`	Agent encountered an error
`authentication_failure`	Agent failed to authenticate to an external service
`resource_usage`	Agent consumed compute, tokens, or quota
`policy_violation`	Agent attempted an action outside its allowed scope

Recording an Event

POST /v1/events

{
  "agent_id": "uuid",
  "action_type": "tool_call",
  "payload": {
    "tool": "web_search",
    "query": "EUR/USD spot rate",
    "duration_ms": 420
  }
}

Response 201:

{
  "data": {
    "id": "uuid",
    "agent_id": "uuid",
    "action_type": "tool_call",
    "risk_score": 0.12,
    "risk_band": "low",
    "occurred_at": "2026-05-17T10:00:00Z"
  }
}

Risk Bands

Band	Score Range	Behaviour
`low`	`< 0.3`	Normal operation
`medium`	`0.3 – 0.84`	Logged, monitored
`high`	`≥ 0.85`	Triggers auto-revocation check

Querying Events

GET /v1/events?agent_id={id}&band=high&limit=50

Filters:

Parameter	Type	Description
`agent_id`	uuid	Filter by agent
`band`	`low` \| `medium` \| `high`	Filter by risk band
`action_type`	string	Filter by action type
`before`	ISO 8601	Cursor for pagination (newest first)
`limit`	integer	Max results, capped at 100

Response:

{
  "data": [...],
  "has_next_page": true,
  "next_cursor": "2026-05-17T09:55:00.000Z"
}

Risk Scoring

Events are scored using AI-powered anomaly detection (Claude Haiku via OpenRouter). Scoring is synchronous — the score is returned in the 201 response.

High-risk events (≥ 0.85) write an audit_log entry and trigger an agent status review.