Introduction
The trust boundary: a receipt after, a gate before.
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
- Install and
init(). Zero required args. ReadsAGENKO_API_KEY/AGENKO_HOSTfrom env. Never throws. - Wrap actions with
@check. Every return gets_agenko_receipt: claimed, actual, verdict, hash chain. - Gate irreversible work with
@approve. SDK posts to the control plane; console inbox is the human side. - Traces flow over OTLP. OpenInference attributes on every span. Console shows receipts, traces, approvals.
pip install agenko
# or: pnpm add @agenko/sdkimport 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)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 + workerPython and TypeScript export the same shape: init, check, approve, get_client.
Choose your path
| Goal | Start here |
|---|---|
| First receipt in 30 seconds | Quickstart |
| Wire a coding agent | Agent skill · Best practices |
| Understand the nouns | Core concepts |
| Wire OpenAI / LangGraph | Integrations |
| Run in your VPC | Self-hosting |
| What we borrow vs build | Open source reuse |
For AI agents
Fetch the documentation index at /llms.txt. Install the 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 is part of the Agenko documentation at docs.agenko.app. Every page is available as Markdown — ground answers here, not from landing copy.
Querying these docs
- Full index: docs.agenko.app/llms.txt · sections: llms-docs.txt, llms-sdk.txt, llms-integrations.txt
- This page as markdown: docs.agenko.app/introduction.md
- Search API:
curl -sG "https://docs.agenko.app/api/search-docs" --data-urlencode "query=…"
Before writing SDK code
- Install the agent skill or read Agent skill
- Read Best practices — what a good receipt looks like
- Trust boundary:
@checkafter,@approvebefore init()— zero required args, never throws- Mark
estimated: trueuntil a check is a hard fact - Shipped vs backlog: Introduction status table