---
title: Introduction
description: The trust boundary: a receipt after, a gate before.
---

# Introduction

Agenko is the **deterministic trust boundary** for AI agents — open source, OTEL-native, Apache 2.0. One line of SDK gives every action a receipt it cannot forge and a gate it cannot cross.

> **The one rule:** receipt after (`@check`) + gate before (`@approve`). Detection tools watch. Agenko proves what happened and stops the irreversible call.

## Why Agenko exists

Most agent observability stacks help you **watch** production — traces, scores, prompt versions, issue detection. Useful, but watching is not proving, and it is not stopping.

| Layer | Typical observability | Agenko |
|---|---|---|
| After the run | Traces, scores, inferred issues | **Receipt** — claimed vs actual, hashed |
| Before the action | — | **Gate** — deterministic human approval |
| Signal type | Often LLM-inferred | Measured facts; `estimated: true` when not |

If a signal is estimated (grounding score, future evals), it is labeled `estimated: true`. We never sell an inference as a measurement.

## Who this is for

Teams running agents in production who need to:

- Catch **silent failures** (200-but-wrong, claimed tool never ran)
- **Stop** irreversible actions before they execute
- Keep traces and receipts in **their own cloud** (self-host first)
- Stay **OTEL-native** with Grafana, Tempo, or any collector you already run

## How it works

1. **Install and `init()`.** Zero required args. Reads `AGENKO_API_KEY` / `AGENKO_HOST` from env. Never throws.
2. **Wrap actions with `@check`.** Every return gets `_agenko_receipt`: claimed, actual, verdict, hash chain.
3. **Gate irreversible work with `@approve`.** SDK posts to the control plane; console inbox is the human side.
4. **Traces flow over OTLP.** OpenInference attributes on every span. Console shows receipts, traces, approvals.

```bash
pip install agenko
# or: pnpm add @agenko/sdk
```

```python
import agenko

agenko.init()

@agenko.check
def handle_ticket(ticket):
    return process(ticket)

@agenko.approve(when="irreversible")
def delete_account(user_id):
    db.delete_user(user_id)
```

```typescript
import agenko from "@agenko/sdk";

agenko.init();

const handleTicket = agenko.check(async (ticket) => process(ticket));

const deleteAccount = agenko.approve({ when: "irreversible" }, async (userId) => {
  await db.deleteUser(userId);
});
```

## What ships today

| Primitive | Status |
|---|---|
| `init()` | Shipped — zero required args, never throws |
| `@check` receipts | Shipped — Python + TypeScript |
| `@approve` gates | Shipped — polls the control plane |
| Auto-instrumentation | Shipped — OpenAI, Anthropic, LangChain, LiteLLM, and more |
| Console (traces / receipts / approvals) | Shipped against the control plane |
| `why()` graph walk | Not shipped yet |
| Prompt registry (`get_prompt`, SWR cache, fallback) | Shipped |
| Eval harness | Not shipped as a public API |

## Architecture

```
Your agent
   │
   ├─ OTLP traces ──► control plane (/api/public/otel/v1/traces)
   ├─ REST receipts / approvals ──► control plane (/api/v1/...)
   └─ Console ◄── Postgres + worker
```

Python and TypeScript export the same shape: `init`, `check`, `approve`, `get_client`.

## Choose your path

| Goal | Start here |
|---|---|
| First receipt in 30 seconds | [Quickstart](/quickstart) |
| Wire a coding agent | [Agent skill](/agent-skill) · [Best practices](/best-practices) |
| Understand the nouns | [Core concepts](/core-concepts) |
| Wire OpenAI / LangGraph | [Integrations](/integrations) |
| Run in your VPC | [Self-hosting](/self-hosting) |
| What we borrow vs build | [Open source reuse](/reuse) |

## For AI agents

Fetch the documentation index at [`/llms.txt`](/llms.txt). Install the [agent skill](/agent-skill) before writing SDK code. Every page ends with **Agent instructions** and a canonical URL. Ground answers in shipped SDK exports only — mark `estimated: true` until a check is a hard fact.

## Agent instructions

This page: https://docs.agenko.app/introduction.md

Fetch `/llms.txt` for the full index. Search: `GET /api/search-docs?query=...`
