Agent Execution Verification System — transparent audit SDK for AI agents.

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.

• Python 3.10+
• Framework adapters:
  • aevs[langchain] for LangChain / LangGraph tool interception
  • aevs[mcp] for MCP tool interception (requires mcp>=1.20)

pip install aevs

With framework extras:

pip install aevs[langchain]   # LangChain / LangGraph support
pip install aevs[mcp]         # MCP tool support

import aevs

aevs.configure(api_key="aevs_sk_<key_id>_<hex_secret>")
aevs.enable()

# Every tool call from this point is intercepted.
# No changes to tools, agents, or LLM setup.

aevs.configure(api_key=..., **options)   # Set configuration (required before enable)
aevs.enable()                            # Auto-detect frameworks and start intercepting
aevs.enable(frameworks=["langchain"])    # Or specify explicitly
aevs.disable()                           # Unpatch all frameworks, restore originals
aevs.flush()                             # Force-send buffered receipts to backend
aevs.get_session_id()                    # UUID minted at enable(); stamped on every receipt
aevs.is_healthy()                        # False after sustained buffer write failures

Every intercepted tool call gets a reference_id (UUID v4) embedded in its receipt. The SDK keeps these in a bounded FIFO registry.

response = await agent.ainvoke({"messages": [("user", query)]})
refs = aevs.get_reference_ids(clear=True)
# [{"seq": 1, "tool_name": "search", "reference_id": "abc-...", "run_id": "def-..."}, ...]

Verify any reference_id via the public backend endpoint (no auth required):

GET /v1/receipts/verify/{reference_id}

aevs.get_reference_id(run_id)       # Lookup by framework run_id
aevs.get_reference_ids(clear=True)  # Get all entries, then clear
aevs.clear_reference_ids()          # Drop all entries

Each enable() mints a fresh UUIDv4 session id. The id is stamped on every receipt produced in that session and participates in the hash chain anchor — two SDK processes that share an API key cannot fork the chain by construction.

aevs.enable()
session = aevs.get_session_id()
# "5db7d195-f84c-4f90-ae12-d74d001d3f9d"

aevs.disable()
aevs.get_session_id()
# None

Useful for log correlation: every receipt carries session_id, so filtering receipts by session in the AEVS backend isolates a single SDK run.

AEVS receipts may include tool inputs and outputs, which can contain secrets or PII depending on what your tools return (e.g. prompts, retrieved documents, API responses).

• Receipts are buffered locally in an encrypted SQLite database (default ~/.aevs/buffer.db).
• Receipts are submitted to the AEVS backend over HTTPS by default (base_url).

You are responsible for ensuring your tool layer does not emit sensitive data you cannot store or transmit. If needed, redact at the tool boundary (before data reaches the agent runtime).

• AEVS is tamper-evident, not tamper-proof. It helps detect modification/reordering of receipts after the fact; it does not secure a fully compromised host process.
• The SDK signs requests with a key derived from your API key secret; protect the API key like any other credential.

• Python 3.10+
• Poetry

git clone https://github.com/fetchai/AEVS-sdk.git && cd AEVS-sdk
make install   # poetry install --all-extras

The Makefile wraps the everyday workflow. Run make help to see the full list.

make test        # run the test suite
make test-cov    # tests with coverage (HTML report in ./htmlcov)
make lint        # ruff check
make format      # ruff format + auto-fix
make typecheck   # mypy --strict on src/
make check       # lint + typecheck + tests (the CI gate)
make build       # build sdist + wheel into ./dist

You can still call the underlying tools directly:

poetry run pytest tests/test_integration.py -v
poetry run ruff check src/ tests/
poetry run mypy src/

See CONTRIBUTING.md for the full guide — branch naming, Conventional Commits, the PR checklist, and release flow.

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

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

• Interception: Framework-specific patches capture tool inputs/outputs
• Signing: Each receipt is HMAC-signed (HKDF-derived keys) with a hash chain linking sequential calls
• Buffering: Receipts are encrypted and stored locally in SQLite, flushed in the background
• Resilience: Buffer survives process restarts; flush retries on transient failures

aevs-sdk/
├── src/aevs/
│   ├── __init__.py        Public API (configure, enable, disable, flush)
│   ├── _api.py            Core state management, enable/disable, flush
│   ├── _drainer.py        Background flush of buffered receipts
│   ├── _version.py        Package version
│   ├── config.py          Configuration dataclass + validation
│   ├── exceptions.py      SDK exception types
│   ├── adapters/          Framework-specific interceptors
│   │   ├── base.py        Base adapter interface
│   │   ├── langchain.py   LangChain / LangGraph interceptor
│   │   └── mcp.py         MCP tool interceptor
│   ├── core/
│   │   ├── buffer.py      Encrypted SQLite local buffer
│   │   ├── client.py      HTTP client (sync + async)
│   │   ├── receipt.py     ReceiptBuilder — HMAC, hash chain
│   │   ├── serializer.py  Canonical JSON serialization
│   │   ├── signer.py      Request signing (HKDF + HMAC)
│   │   └── types.py       Typed payload shapes
│   └── crypto/
│       ├── chain.py       Hash chain helpers
│       ├── hkdf.py        HKDF key derivation
│       └── hmac_auth.py   HMAC authentication
├── tests/                 Test suite
├── pyproject.toml         Poetry packaging + tool config
├── poetry.lock
├── LICENSE
└── README.md