> ## Documentation Index
> Fetch the complete documentation index at: https://attesta.kyberon.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Introduction
> Human-in-the-loop approval framework for AI agent actions
**Early Release (v0.1.x)** — Attesta is under active development. The core API is functional and tested, but interfaces may change between minor versions. Pin your dependency to a specific version in production. Report issues through this repository's issue tracker.
**Attesta** = *Attestation* + *Gate*. Every AI agent action passes through a trust gate before it touches the real world.
## The Problem: Approval Fatigue
Every AI agent framework has a human-in-the-loop mechanism. LangChain has `HumanApprovalCallbackHandler`. CrewAI has `human_input=True`. OpenAI Agents SDK has handoffs. They all do the same thing: pause execution and ask a human to click **Yes** or **No**.
**A human who sees 200 approval prompts a day stops reading them.** Approval fatigue turns your safety layer into a rubber stamp.
| Capability | Baseline HITL | **Attesta** ✓ |
| ----------------------------- | -------------------------------------------- | ------------------------------------------------------------------------- |
| **Risk awareness** | None — all actions get the same Y/N | 5-factor scoring auto-detects risk from function signature |
| **Challenge depth** | Binary confirm for everything | Scales by risk: auto-approve → confirm → quiz → teach-back → multi-party |
| **Approval fatigue** | High — every action prompts | Low — only risky actions surface; safe actions pass silently |
| **Audit integrity** | Basic logs (if any) | SHA-256 hash-chained JSONL; tamper-evident |
| **Multi-party support** | No | CRITICAL actions require 2+ independent approvers |
| **Trust adaptation** | No | Bayesian trust engine; incidents instantly revoke trust |
| **`drop_database()` outcome** | "Confirm? \[Y/N]" → instant click → executed | Score 0.95 CRITICAL → multi-party review, 30s+ minimum, teach-back + quiz |
Illustrative comparison; baseline behavior varies by framework.
## The Attesta Pipeline
AI agents can write code, execute shell commands, manage infrastructure, and access sensitive data. **Attesta ensures no high-risk action happens without informed human approval** — while letting low-risk actions fly through silently.
## Core Pillars
A 5-factor scoring engine analyzes the function name, arguments, docstring, caller hints, and call novelty. `get_user()` scores 0.1. `drop_database()` scores 0.95. The challenge scales accordingly — no manual risk tagging required.
Low-risk actions pass through silently. High-risk actions require the approver to answer auto-generated comprehension questions. Critical actions require multiple independent approvers, each completing a different challenge type. You can't just click through.
Every decision is recorded in a SHA-256 hash-chained log. Modify any entry and every subsequent hash breaks. `attesta audit verify` checks the entire chain. `attesta audit rubber-stamps` flags suspiciously fast approvals.
A Bayesian trust engine tracks each agent's approval history with exponential decay. Trusted agents see reduced friction over time. A single security incident instantly penalizes trust. Critical actions are immune to trust discounts — always fully gated.
## What Makes Attesta Different
1. **Risk is computed, not assumed** — The scorer auto-detects risk from the function signature. No manual tagging.
2. **Challenges test comprehension** — Quiz and teach-back challenges force the approver to prove they understand the action.
3. **Minimum review times** — A wall-clock minimum prevents instant approvals. 3s for medium, 10s for high, 30s+ for critical.
4. **Trust is earned** — Agents build trust through consistent safe behavior. Incidents instantly revoke it.
## Quick Example
```python Python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
from attesta import gate
@gate
def deploy(service: str, version: str) -> str:
"""Deploy a service to production."""
return f"Deployed {service} v{version}"
# Attesta intercepts, scores risk, and prompts for approval
deploy("api-gateway", "2.1.0")
```
```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
import { gate } from "@kyberon/attesta";
const deploy = gate(async (service: string, version: string) => {
return `Deployed ${service} v${version}`;
});
// Attesta intercepts, scores risk, and prompts for approval
await deploy("api-gateway", "2.1.0");
```
## Risk Levels at a Glance
| Score | Level | Default Challenge | Example |
| --------- | ------------ | -------------------- | -------------------- |
| 0.0 - 0.3 | **LOW** | Auto-approve | `get_user_profile()` |
| 0.3 - 0.6 | **MEDIUM** | Confirm (Y/N) | `send_email()` |
| 0.6 - 0.8 | **HIGH** | Quiz (comprehension) | `deploy_service()` |
| 0.8 - 1.0 | **CRITICAL** | Multi-party approval | `drop_database()` |
## Works With
LangChain, OpenAI Agents SDK, Anthropic Claude, CrewAI, MCP, Vercel AI SDK
n8n, Flowise, Langflow, Dify
Custom domain profiles via `register_preset()` — define industry-specific risk patterns, escalation rules, and compliance references
Python (full SDK + CLI + domain profiles) and TypeScript (core SDK + LangChain + Vercel AI)
## Next Steps
Get up and running in 5 minutes
See the public feature boundary
Understand the 4-stage approval pipeline
Connect Attesta to your AI framework
Customize policies, risk scoring, and trust