Core Concepts
Kaplaix’s data model is built around four primitives: tenants, agents, sessions, and events.
Tenants
A tenant is an isolated workspace. Every resource — agents, sessions, events, policies — belongs to exactly one tenant. Data is never shared across tenants.
Each tenant has one or more API keys (prefixed al_live_ or al_test_) used to authenticate SDK and HTTP requests.
Agents
An agent is a registered AI agent within a tenant. Each agent has a unique agentId (your chosen identifier, e.g. "support-bot") and metadata like name, framework, and environment.
Agents are created via the API or auto-registered on first event ingestion. Kaplaix builds a behavioral fingerprint (Agent DNA) for each agent over time, detecting drift from established baselines.
Sessions
A session groups a sequence of events from a single agent execution. Think of it as one “run” — from the agent receiving a task to completing it.
- Sessions are created implicitly when the first event arrives with a new
sessionId. - Each session tracks
eventCount,firstEventAt,lastEventAt, and is resolved to an agent. - Sessions can be queried, filtered (by agent, date range, search), and exported as evidence packages.
Events
Events are the atomic unit of observability. Every action your agent takes — tool calls, data access, approvals, environment changes — is captured as an event.
Event envelope
Every event shares a common envelope:
| Field | Type | Description |
|---|---|---|
eventId | UUID | Unique identifier (client-generated) |
agentId | string | Agent that produced the event |
sessionId | string | Session this event belongs to |
sourceTimestamp | ISO 8601 | When the event occurred |
category | string | One of the 7 canonical categories |
schemaVersion | string | Schema version (currently "1.0") |
payload | object | Category-specific data |
previousHash | string? | Hash of the previous event for chain integrity |
The 7 event categories
| Category | Purpose | Example |
|---|---|---|
identity | Agent identity assertion | Agent startup, version declaration |
reasoning | Decision trace | ”Decided to escalate to human” |
tool_api | Tool/API invocation | HTTP call, database query, file write |
browser_desktop | UI interaction | Screenshot, click, navigation |
data_movement | Data read/write/export | File export, record deletion |
approval | Human decision | Approve or reject an action |
environment | Runtime context | Sandbox mode, network segment |
See the full Event Schema reference for payload details.
Risk Engine
The Risk Engine scores every session across 10 dimensions aligned to the OWASP Agentic Top 10 (ASI01–ASI10). Each dimension produces a 0–100 score with explainable factors and actionable recommendations.
Risk is computed at read time from the session’s events — there is no pre-computation. Severity levels: low, medium, high, critical.
Policies
Policies define rules that govern what agents can do. Each policy contains:
- Rules — conditions matching event attributes (tool type, operation, target system, initiator type)
- Decisions —
allowed,requires_review, ordenied - Default decision — applied when no rule matches
Only one policy can be active per tenant at a time.
Guardian Mode
Guardian Mode enables pre-execution policy enforcement. Instead of logging events after the fact, the SDK checks with Kaplaix before the dangerous tool runs.
Three enforcement modes:
| Mode | Behavior |
|---|---|
log_only | Log policy decision, never block |
block | Block denied actions, throw error |
require_approval | Create pending action, wait for human decision |
Guardian Mode includes a circuit breaker to protect against cascading failures. See the Guardian API reference for details.
Evidence Packages
Evidence packages are signed ZIP exports containing:
- PDF report — human-readable session narrative
- JSON data — machine-readable event stream
- Manifest — file listing with SHA-256 checksums
- Digital signature — integrity verification
These are designed for auditors, regulators, and compliance teams.