AgentTrust Docs

Overview

Run a full governance gateway inside your Python process using SQLite — no PostgreSQL, Redis, or Docker required. Ideal for local development, CI pipelines, demos, and air-gapped environments.

Why It Matters

Embedded mode removes all infrastructure friction. You get real HTTP validation, local audit storage, and policy checks without provisioning external services.

Prerequisites

pip install "agentrust-py[embedded]"

Step-by-Step Guide

1. Start embedded gateway

from agentrust_sdk import embed_gateway

gw = embed_gateway()
print(gw.url)         # http://127.0.0.1:8765 — the SDK auto-sets AGENTRUST_GATEWAY_URL

2. Use with `@harness`

from agentrust_sdk import harness, embed_gateway

embed_gateway()

@harness
def my_agent(user: str, input: str) -> dict:
    return {"result": "ok"}

3. Configure storage and port

export AGENTRUST_EMBED_PORT=8765
export AGENTRUST_EMBED_DB=~/.agentrust/embedded.db
export AGENTRUST_EMBED_TOKEN=your-bearer-token  # auto-generated if unset

4. Inspect local audit

agentrust audit tail             # reads ~/.agentrust/embedded.db and audit.db
agentrust export ./audit.jsonl   # both databases, as JSONL

Or query the running gateway directly (every route but /v1/health needs the token):

curl -H "Authorization: Bearer $AGENTRUST_EMBED_TOKEN" \
  http://127.0.0.1:8765/v1/audit/executions?limit=10

5. Zero-code autoload (optional)

export AGENTRUST_AUTOLOAD_EMBED=true
export AGENTRUST_AUTOLOAD_AGENT_ID=my-agent
export PYTHONSTARTUP=/path/to/agentrust_sdk/autoload.py

Examples

Context manager pattern:

Prefer `embed_gateway()` unless you need the context manager

Constructing EmbeddedGateway directly wires up nothing: it sets neither AGENTRUST_GATEWAY_URL nor AGENTRUST_KEY. The gateway still enforces its bearer token on every route except /v1/health, so a client that does not know the token gets 401 on every call — and under the default fail-open mode those 401s are logged and swallowed, leaving you with a sample that looks governed but records nothing.

Pass both the URL and the token, or just use embed_gateway(), which exports them.

import os

from agentrust_sdk import EmbeddedGateway, harness

os.environ["AGENTRUST_EMBED_TOKEN"] = "local-dev-token"   # pin BEFORE constructing

with EmbeddedGateway(port=8765) as gw:

    @harness(base_url=gw.url, api_key="local-dev-token")
    def agent(user, input):
        return {"ok": True}

    agent(user="alice", input="test")   # keyword args — see the harness docs

Verify it actually governed something rather than trusting the absence of an error:

agentrust audit tail   # expect two rows: pre_check and post_check

CI pipeline:

# .github/workflows/test.yml
- run: pip install "agentrust-py[embedded]"
- run: python -m pytest tests/  # tests call embed_gateway() in conftest

Best Practices

Use embedded for dev/CI only; promote to full edge for production
Embedded risk is computed deterministically, without the historical-reliability signal — do not use it for production risk calibration
Purge test data between CI runs: agentrust purge --confirm
Set explicit AGENTRUST_EMBED_TOKEN in shared CI environments

Common Mistakes

Expecting the LLM judge, trust chain, or analytics in embedded mode (HITL review and Discord/Slack notifications are supported)
Running multiple embed_gateway() calls on the same port
Using embedded SQLite DB as production audit store

Troubleshooting

Issue	Fix
Port already in use	Change `AGENTRUST_EMBED_PORT`
`uvicorn` not found	Install `[embedded]` extra
Empty audit tail	Confirm validations hit the embedded URL, and that `AGENTRUST_EMBED_DB` is not `:memory:`

Embedded vs Full Gateway

Feature	Embedded	Full Edge
Pre-check / post-check / validate	✅	✅
Schema validation	✅	✅
Policy packs	Base + bundled domain packs	Full, versioned, syncable
Risk engine	Deterministic only	Full scoring + historical reliability
Human review	HITL API only	Full review queue + operator UI
LLM judge	❌	✅ (Enterprise)
Trust chain	❌	✅ (Enterprise)
Multi-tenant	❌	✅
Hash chain audit	❌	✅ (Enterprise)

Embedded Quickstart