Kernel Docs

Kernel
Documentation.

Kernel is the runtime behavior control layer for AI agents performing consequential financial actions. Use these docs to evaluate actions, capture outcomes, investigate reviews, and deploy Kernel in production.

Start quickstart API reference

Base URLs

Hosted: https://api.runtime-trust.com
Self-hosted: http://localhost:8080
Auth: Authorization: Bearer <api_key>
Kernel also supports WorkOS SSO for team-based access control on hosted deployments.

Why Kernel exists

AI agents increasingly approve refunds, payments, purchases, and other financial actions autonomously. Existing controls validate individual requests. Kernel evaluates agent behavior over time and returns an execution decision before the business system acts.

Agent -> Kernel -> Business System
Action -> Evaluation -> Decision -> Operator -> Outcome -> History

What problem it solves: Agent behavior changes over time — amounts creep up, policies get stretched, and individual checks miss the trajectory. Kernel detects the pattern.

Who it's for: Teams running production AI agents that execute financial actions — refunds, payments, vendor payouts, and purchase approvals.

Integration time

Kernel is designed for minimal time-to-value. Most teams go from zero to production in under a day.

SDK

30 minutes

Install the Python SDK, configure your API key, and call evaluate() in your agent loop.

REST API

2–4 hours

Integrate via POST /evaluate and PUT /evaluations/{id}/review. Works with any language.

Production rollout

1 day

Deploy in observation mode, tune thresholds, enable enforcement. Roll out per agent or per action type.

Code delta

The change is one decision gate before execution.

# Today — direct execution
refund(amount=150.00)

# Tomorrow — gated through Kernel
decision = kernel.evaluate(agent_id, session_id, action_type, amount)

if decision == "ALLOW":
  refund(amount=150.00)
elif decision == "REVIEW":
  queue_for_operator_review(evaluation_id)
else:
  stop_execution(reason)

ALLOW

The action is within policy and behavior remains consistent. Execute normally.

REVIEW

The action is unusual or near a boundary. Route it to an operator workflow.

BLOCK

The action exceeds the configured block boundary. Do not execute.

How it works

Request shape

Every evaluation requires these fields:

Field	Type	Required	Description
`agent_id`	string	Yes	Agent performing the action.
`session_id`	string	Yes	Session or workflow identifier.
`action_type`	string	Yes	Action being evaluated, such as `refund` or `vendor_payment`.
`amount`	number	Yes	Financial amount in USD.
`metadata`	object	No	Structured context used for review and analysis.

Response shape

Every evaluation returns:

{
  "decision": "REVIEW",
  "risk_score": 0.58,
  "trust_score": 0.72,
  "reason": "Amount is near the configured review boundary",
  "signals": [],
  "failure_classes_detected": ["Optimization Drift"],
  "evaluation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "observation_mode": false,
  "interaction_count": 5,
  "proposed_action": {"type": "refund", "amount": 150.0},
  "trust_signals": [],
  "runtime_version": "1.0.0",
  "signal_version": "1",
  "trust_model_version": "1",
  "taxonomy_version": "1",
  "config_version": "a1b2c3d4"
}

Field	Description
`decision`	`ALLOW`, `REVIEW`, or `BLOCK`.
`risk_score`	Float 0–1. Higher means more likely to exceed policy.
`trust_score`	Float 0–1. Higher means the agent's behavior is consistent with past patterns.
`reason`	Human-readable explanation of the decision.
`signals`	List of detected behavioral signals that contributed to the decision.
`failure_classes_detected`	Failure classifications such as Optimization Drift or Policy Boundary.
`evaluation_id`	UUID for outcome capture, history, and review.
`observation_mode`	When `true`, Kernel returns a decision but enforcement is advisory.
`interaction_count`	Number of interactions in the current session so far.
`proposed_action`	The action that was evaluated, with its type and amount.
`trust_signals`	Detailed behavioral signals with IDs, descriptions, and failure classes.
`runtime_version`	Version of the runtime used for this evaluation.
`signal_version`	Version of the signal detection logic.
`trust_model_version`	Version of the trust model used to compute scores.
`taxonomy_version`	Version of the failure class taxonomy.
`config_version`	Config snapshot identifier for traceability.

Decision lifecycle

Kernel evaluates actions, your application enforces decisions, and outcomes are recorded.

1. Agent requests execution
| 2. Application calls POST /evaluate
| 3. Kernel returns decision + evaluation_id
| 4. Application executes, queues, or stops
| 5. Application reports outcome via PUT /evaluations/{id}/review
| 6. Kernel records the session trail for investigation

Outcome capture

After the application acts on the decision, report the result so review trails stay complete.

PUT /evaluations/{evaluation_id}/review

{
  "status": "resolved",
  "resolution": "completed",
  "impact": "{\"external_id\":\"pay_abc123\",\"duration_ms\":842}"
}

Status	Meaning
`unreviewed`	Evaluation is waiting for operator review.
`acknowledged`	An operator has accepted ownership.
`resolved`	The review is complete and an outcome was captured.
`dismissed`	The review was closed as not actionable or abandoned.

History recording

Kernel stores every evaluation, decision, outcome, and operator note for investigation and audit.

GET /investigations

Query	Description
`decision`	Filter by `ALLOW`, `REVIEW`, or `BLOCK`.
`review_status`	Filter by review state.
`limit`	Maximum number of results.
`assigned_to_user_id`	Show reviews owned by a specific operator.

GET /trace/{session_id}

Returns the session trail used by the investigation UI: events, decisions, scores, signals, reasons, and runtime versions.

POST /evaluations/{evaluation_id}/notes

Adds operator context to the evaluation review.

Failure modes

Kernel is designed to fail safely. Every failure mode has a configurable behavior.

Timeout

API timeout

Default client timeout is 5 seconds. The SDK returns a timeout error. Your application should handle the error and apply the configured fallback.

Retry

Retry behavior

The SDK retries on 429 and 5xx responses (up to 3 attempts with exponential backoff). Idempotent evaluations can be safely retried.

Fail open

When Kernel is unreachable, the action is allowed through. Use this for non-critical agents where availability matters more than control.

Fail closed

When Kernel is unreachable, the action is blocked. Use this for high-risk actions where policy adherence matters more than availability.

Cached decision

The SDK caches the last-known-good decision for up to 30 seconds. If Kernel is unreachable, the cached decision is returned instead of a timeout.

Observation mode

Observation mode fallback

Deploy in observation mode first. Kernel returns decisions but enforcement is advisory. Allows you to validate behavior before enforcing decisions.

Latency and throughput

Kernel's evaluation path is designed to stay under 100ms p95 in normal operating conditions.

Metric	Target	Notes
p95 latency	< 100 ms	Measured from receipt to response for a single evaluation at 100 RPS sustained load.
Requests per second	1,000+ per instance	Baseline throughput on a standard 8-vCPU instance.
Scaling behavior	Horizontal	Stateless evaluation nodes. Scale out by adding instances behind a load balancer.
Resource profile	~0.4 vCPU / 800 MB per 100 RPS	Measured with in-memory signal state. Database-backed mode adds ~20ms to p95.

Latency and throughput vary by signal configuration, taxonomy size, and deployment topology. Self-hosted deployments typically match hosted performance with equivalent resources.

Availability

Kernel behavior under infrastructure degradation depends on deployment mode and client configuration.

Kernel is down
Client falls back to fail-open or fail-closed behavior based on configuration. Cached decisions serve for up to 30 seconds. No data loss — evaluations are queued and replayed on recovery.

Postgres is down
In-memory signal state remains available. New evaluations return decisions based on current in-memory state. History writes are queued until Postgres recovers.

Hosted infra degraded
Multi-region failover with active-passive replica. DNS-based failover targets < 60 second RTO. RPO is zero — evaluation writes are synchronous to the primary region.

Self-hosted mode
Full data residency. No external dependency beyond your Postgres instance. Kernel operates entirely inside your environment with no egress required.

Hosted vs self-hosted

Kernel supports two deployment modes. Choose based on your data residency, latency, and operational requirements.

Dimension	Hosted	Self-hosted
Data residency	Stored in Kernel-managed infrastructure (US region by default).	Fully customer-managed. Data never leaves your VPC, network, or Postgres instance.
Management overhead	Zero — Kernel manages API, database, signal state, and dashboard upgrades.	Customer responsible for API, Postgres, monitoring, backups, and upgrades.
Latency	~2–10 ms network round-trip from same cloud region. Cross-region adds ~30–80 ms.	Sub-millisecond internal network. No egress overhead. Evaluation overhead is the same.
Throughput	Shared multi-tenant infrastructure. Burst up to 5,000 RPS. Guaranteed minimum via reserved capacity.	Dedicated resources. Throughput scales with provisioned CPU and memory. No multi-tenant contention.
Upgrades	Managed by Kernel. Rolling updates with no downtime. Version pins available for signal and model.	Customer-controlled. Pull new images or update packages. Full control over upgrade schedule.
Compliance scope	Covered by Kernel's SOC 2 Type II audit (in progress) and DPA.	Customer extends their own compliance boundary. Kernel provides audit logs and config exports.
Failover	Multi-region active-passive. DNS failover with < 60s RTO. Zero RPO on evaluation writes.	Customer-defined. Deploy multi-AZ or multi-region Postgres. Kernel nodes are stateless and can run behind any load balancer.
Pricing	Per-evaluation pricing with volume tiers. Free development tier available.	Per-instance license. Unlimited evaluations within licensed capacity.
Getting started	Sign up at `api.runtime-trust.com`. API key in 60 seconds.	Download the Evaluation Kit and run `docker compose up`. No repository required.

Both modes use the same evaluation API, SDK, and signal models. Decisions are identical — the only difference is where the computation runs and who manages the infrastructure.

Versioning

Every evaluation is recorded with the exact versions of every component that produced the decision. This enables precise rollback and audit.

Version	Description	Rollback
Model version	The behavioral model version used to compute trust and risk scores.	Pin to a previous version per agent or globally via config.
Signal version	The signal detection logic version. New signals may be added in minor versions.	Pin to the previous signal version. Supports granular rollback.
Taxonomy version	The failure class taxonomy used to classify detected patterns.	Changes are additive. Existing evaluations are not reclassified.
Threshold version	The decision boundary configuration (REVIEW and BLOCK thresholds per action type).	Every threshold change is versioned. Rollback to any previous version via config API.

Every evaluation response includes runtime_version, signal_version, trust_model_version, taxonomy_version, and config_version for full traceability.

Configuration lifecycle

Thresholds, signal configuration, and taxonomy are managed through the Kernel API and dashboard. Every change is versioned and audited.

Who changes thresholds
Operators with the admin or config_manager role. Changes are made through the dashboard or PUT /config API.

How changes are approved
Two-person approval for production config changes. A second admin must approve the change before it takes effect.

How changes are audited
Every config change is recorded with the user, timestamp, before/after values, and approval. Exportable via GET /audit-log with event_type=config_change.

How exports work
Full config export via GET /config as JSON. Supports import into another environment via PUT /config. Includes thresholds, signal config, taxonomy, and version pins.

Architecture

Every evaluation produces a versioned manifest. This is the full response shape returned by the evaluate endpoint.

{
  "decision": "ALLOW",
  "risk": 0.12,
  "signals": [{"id": "velocity", "details": "Transaction velocity exceeds historical pattern", "failure_class": "Optimization Drift"}, {"id": "near-limit", "details": "Amount within 5% of policy boundary", "failure_class": "Policy Boundary"}],
  "evaluation_id": "evt_9s8K2m",
  "runtime_version": "1.0.0",
  "signal_version": "1",
  "trust_model_version": "1",
  "taxonomy_version": "1",
  "config_version": "a1b2c3d4",
  "evaluated_at": "2026-06-29T14:30:00Z"
}

Every evaluation response includes runtime_version, signal_version, trust_model_version, taxonomy_version, and config_version for full traceability. Manifests are immutable — once written, they cannot be modified or deleted (except by full tenant deletion).

Operator workflow

The operator review loop is the human-in-the-middle for REVIEW decisions. Kernel provides assignment, notifications, SLAs, and bulk actions.

Review ownership

Assignment

Evaluations with REVIEW decision are assigned to operator queues. Assignment is round-robin or by agent type. Manual reassignment supported.

Notifications

Alerting

Slack, PagerDuty, and webhook integrations. Notify on new REVIEW decisions, SLA breaches, and bulk action triggers.

SLAs

Service levels

Configurable review SLAs per action type. Escalate if unreviewed after threshold. SLA breaches trigger notification escalation.

Bulk actions

Batch operations

Select multiple evaluations. Resolve, dismiss, or reassign in bulk. Filter by agent, action type, risk range, or session.

Resolve

Complete review

Mark as resolved with resolution and optional impact notes. The evaluation status moves to resolved.

Dismiss

Close review

Mark as dismissed with a reason code. The evaluation is archived but retained for audit. Dismissed evaluations can be reopened within 30 days.

Performance evidence

Kernel is designed for production use at scale. The following metrics are from hosted production and load-test environments.

Metric	Value	Environment
Evaluation volume	10M+ evaluations processed	Production (hosted)
Uptime	99.97%	Rolling 90-day average (hosted)
p95 latency	74 ms	Production at 500 RPS sustained
CPU	~0.4 vCPU per 100 RPS	8-vCPU instance, in-memory mode
Memory	~800 MB per 100 RPS	Includes in-memory signal state
DB / storage growth	~2 KB per evaluation	Postgres, includes history and signals

Self-hosted performance matches hosted with equivalent resources. Memory and CPU scale linearly with evaluation volume.

Appendix

SDK example

Full client example with error handling:

from kernel_runtime_trust import KernelClient, KernelTimeoutError

client = KernelClient()

try:
    result = client.evaluate(
        agent_id="payment-bot",
        session_id="ses-abc-123",
        action_type="refund",
        amount=150.00,
    )

    if result.decision == "ALLOW":
        execute_refund()
    elif result.decision == "REVIEW":
        queue_for_operator_review(result.evaluation_id)
    else:
        stop_execution(result.reason)

except KernelTimeoutError:
    logger.warning("Kernel timeout, applying fail-open")
    execute_refund()

REST examples

Evaluate an action:

curl -X POST https://api.runtime-trust.com/evaluate \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d {
    "agent_id": "payment-bot",
    "session_id": "ses-abc-123",
    "action_type": "refund",
    "amount": 150.00,
    "metadata": {"customer_tier": "premium"}
  }

Report an outcome:

curl -X PUT https://api.runtime-trust.com/evaluations/a1b2c3d4-e5f6-7890-abcd-ef1234567890/review \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d {
    "status": "resolved",
    "resolution": "completed",
    "impact": "{\"external_id\":\"pay_abc123\",\"duration_ms\":842}"
  }

Health check:

curl https://api.runtime-trust.com/health
# {"status": "ok"}

Deployment example

Self-hosted with Docker Compose (Evaluation Kit — no repo needed):

# Download and start
curl -LO https://kerneva.com/evaluation-kit.zip
unzip evaluation-kit.zip
cd evaluation-kit
cp .env.example .env
docker compose up

# Verify
curl http://localhost:8080/health

Environment variable	Required	Description
`API_KEY`	Yes	API key for evaluation requests (used as `DEMO_API_KEY` internally).
`POSTGRES_PASSWORD`	Yes	PostgreSQL password.
`CORS_ORIGINS`	No	Allowed dashboard or application origins.
`PORT`	No	API server port. Default is `8080`.

FAQ

Does Kernel see my agent's prompts or outputs?
No. Kernel only receives structured action events — agent_id, session_id, action_type, amount, and optional metadata. No prompts, no model output, no conversation text.

Does Kernel execute actions?
No. Kernel returns a decision. Your application enforces it. Kernel never calls refund APIs, payment gateways, or any business system directly.

Can I run Kernel offline?
Yes. Self-hosted mode runs entirely inside your environment with no external dependencies beyond your Postgres instance.

What happens if I stop sending outcomes?
Evaluations remain in unreviewed state. Operator dashboards show unreviewed counts. History still records the evaluation and decision.

Questions? Email [email protected].

KernelDocumentation.