aevs

AEVS SDK

Agent Execution Verification System — transparent audit SDK for AI agents

Documentation · Explorer · Examples · Get Credentials

---

Intercepts tool calls from supported frameworks, builds tamper-evident receipts (HMAC-signed, hash-chained), and sends them to the AEVS backend. Zero changes to your agent code.

Installation

pip install aevs

With framework extras:

pip install aevs[langchain]   # LangChain / LangGraph
pip install aevs[mcp]         # Model Context Protocol

Quick Start

import aevs
from langchain_core.tools import tool

@tool
def search(query: str) -> str:
    """Search the web."""
    return f"Results for: {query}"

aevs.configure(
    api_key="aevs_sk_<key_id>_<hex_secret>",
    agent_id="<your-agent-uuid>",
)
aevs.enable()

result = search.invoke({"query": "AI news"})

refs = aevs.get_reference_ids(clear=True)
print(refs)
# [{"seq": 1, "tool_name": "search", "reference_id": "abc-123-...", ...}]

aevs.flush()
aevs.disable()

Credentials can also be set via AEVS_API_KEY / AEVS_AGENT_ID environment variables. If missing, the SDK logs a warning and runs in no-op mode — your agent keeps working, receipts just aren't recorded.

How It Works

Agent (LangChain / MCP)
  │
  ▼  tool call intercepted
ReceiptBuilder  ──▶  HMAC sign + hash chain
  │
  ▼
LocalBuffer (SQLite, encrypted at rest)
  │
  ▼  background drainer
AEVSClient  ──▶  POST /v1/receipts  ──▶  AEVS Backend

1. aevs.enable() patches your framework's tool dispatch
2. Every tool call is intercepted and a signed receipt is created
3. Receipts are buffered locally (encrypted, crash-safe)
4. A background thread flushes receipts to the AEVS backend
5. Verify any receipt using its reference_id

API Overview

aevs.configure(api_key=..., **options)   # set configuration
aevs.enable()                            # start intercepting tool calls
aevs.disable()                           # stop and restore originals
aevs.flush()                             # send buffered receipts now
aevs.get_session_id()                    # current session UUID
aevs.get_reference_ids(clear=True)       # all captured reference IDs
aevs.get_reference_id(tool_call_id)      # lookup single reference ID
aevs.is_healthy()                        # buffer write health check

See the full API reference for details.

Receipt Visibility

Control what data is included in each receipt:

aevs.configure(api_key=..., agent_id=..., receipt_visibility="proof_only")

Examples

See examples/README.md for setup instructions.

Documentation

Data & Privacy

• Receipts are buffered locally in an encrypted SQLite database
• Submitted to the AEVS backend over HTTPS
• Use receipt_visibility="proof_only" to prevent inputs/outputs from leaving the host
• AEVS is tamper-evident, not tamper-proof — it detects modification after the fact

Development

git clone https://github.com/fetchai/AEVS-sdk.git && cd AEVS-sdk
make install        # poetry install --all-extras
make check          # lint + typecheck + tests (the CI gate)

make test           # run tests
make test-cov       # tests with coverage
make lint           # ruff check
make format         # ruff format + auto-fix
make typecheck      # mypy --strict
make build          # build sdist + wheel

Contributing

See CONTRIBUTING.md for the full guide.

Security

Please do not open a public issue for security problems. See SECURITY.md for the disclosure process.

License

Apache 2.0