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-sdk[embedded]"

Step-by-Step Guide

1. Start embedded gateway

from agentrust_sdk import embed_gateway

gw = embed_gateway()  # default: http://localhost:8765
print(gw.url)         # 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
agentrust export ./audit.jsonl

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:

from agentrust_sdk import EmbeddedGateway, harness

with EmbeddedGateway(port=8765) as gw:
    @harness
    def agent(user, input): return {"ok": True}
    agent("alice", "test")

CI pipeline:

# .github/workflows/test.yml
- run: pip install "agentrust-sdk[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 always low — do not use 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 review queue, LLM judge, or webhooks in embedded mode
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 embedded URL

Embedded vs Full Gateway

Feature	Embedded	Full Edge
Schema validation	✅	✅
Policy packs	Basic	Full
Risk engine	Always LOW	Full scoring
Review queue	❌	✅
LLM judge	❌	✅ (Enterprise)
Multi-tenant	❌	✅
Hash chain audit	❌	✅ (Enterprise)

Embedded Quickstart