AgentTrust Docs

Overview

The embedded gateway runs a FastAPI governance server inside your Python process, backed by SQLite. It serves the same three runtime endpoints as the Edge gateway — /v1/runtime/pre-check, /v1/runtime/post-check, and /v1/runtime/validate — so @harness works end to end, with reduced capabilities behind them.

Why It Matters

Embedded mode eliminates infrastructure dependencies for development, CI, demos, and air-gapped environments while providing real HTTP validation and local audit storage.

Prerequisites

pip install "agentrust-py[embedded]"

Step-by-Step Guide

1. Start programmatically

import os
from pathlib import Path

from agentrust_sdk import embed_gateway, EmbeddedGateway

# Simple — idempotent, returns the same instance on repeat calls
gw = embed_gateway()
print(gw.url)          # http://127.0.0.1:8765

# Explicit — db_path must be a real path; `~` is NOT expanded for you
with EmbeddedGateway(
    port=8765,
    db_path=str(Path.home() / ".agentrust" / "embedded.db"),
) as gw:
    print(gw.url)

embed_gateway() binds to 127.0.0.1 by default, so gw.url is http://127.0.0.1:8765 rather than http://localhost:8765. Pass host="0.0.0.0" for Docker or remote access — clients are still pointed at 127.0.0.1.

2. SDK auto-configuration

embed_gateway() sets AGENTRUST_GATEWAY_URL to the embedded URL. All SDK paths (@harness, client, auto-instrument) route to it automatically.

3. Configuration

Variable	Default	Notes
`AGENTRUST_EMBED_PORT`	`8765`
`AGENTRUST_EMBED_HOST`	`127.0.0.1`	Set `0.0.0.0` for Docker
`AGENTRUST_EMBED_DB`	`~/.agentrust/embedded.db`	`:memory:` for ephemeral runs (nothing is persisted)
`AGENTRUST_EMBED_TOKEN`	auto-generated	An unsigned JWT carrying a `team` tier claim, regenerated on every start unless you pin it
`AGENTRUST_KILL_SWITCH`	unset	Set `1` to hard-block every agent
`AGENTRUST_MODE`	`alert`	`alert` \| `hitl` \| `block`
`AGENTRUST_DISCORD_WEBHOOK_URL`	unset	Registers the Discord notifier
`AGENTRUST_SLACK_WEBHOOK_URL`	unset	Registers the Slack notifier
`AGENTRUST_LLM_ENABLED`	`false`	Enable the embedded MAD LLM classifier (off by default so it costs nothing)
`AGENTRUST_LLM_KEY`	unset	OpenAI-compatible API key for that classifier
`AGENTRUST_LLM_MODEL`	`gpt-4o-mini`	Model the classifier calls

embed_gateway(set_env=True) — the default — exports AGENTRUST_GATEWAY_URL and AGENTRUST_KEY so every client created afterwards routes to the embedded instance automatically. Clients constructed before the call keep their old base URL.

4. Audit inspection

agentrust audit tail
agentrust export ./embedded-audit.jsonl

Embedded capabilities

Feature	Embedded	Full Edge
`POST /v1/runtime/validate`	✅	✅
`POST /v1/runtime/pre-check` / `/post-check`	✅	✅
Schema, tool-trust, policy, consistency, grounding checks	✅	✅
Confidence engine	✅	✅
Risk engine	✅ (deterministic)	✅ (+ historical reliability)
Policy packs	Base + bundled domain packs	Full, versioned, syncable
Kill switch (global + per-agent)	✅	✅
Human-in-the-loop queue	✅ (`/v1/governance/hitl/*`)	✅ (`/v1/review/*`, full operator UI)
Discord / Slack notifications	✅	✅
Audit store	SQLite, append-only	PostgreSQL + hash chain
LLM judge	❌	✅ (Enterprise)
Trust chain	❌	✅ (Enterprise)
Historical reliability	❌	✅
Analytics, certification, SSO	❌	✅
Multi-tenant	❌	✅

Endpoints served

Method	Path
GET	`/v1/health` (the only unauthenticated route)
POST	`/v1/runtime/pre-check`, `/v1/runtime/post-check`, `/v1/runtime/validate`
GET	`/v1/audit/executions`, `/v1/audit/tail`
GET/POST	`/v1/governance/kill_switch/status`, `/activate`, `/deactivate`
GET/POST	`/v1/governance/hitl/queue`, `/v1/governance/hitl/{review_id}/resolve`
GET/POST	`/v1/governance/profiles`

Every route except /v1/health requires Authorization: Bearer <AGENTRUST_EMBED_TOKEN>. Request bodies are capped at 1 MB, and ?limit= on /v1/audit/executions is capped at 200.

Examples

See Embedded Quickstart and Examples: Embedded Only.

Best Practices

Use embedded for dev/CI only
Call embed_gateway() once at process startup (before agent calls)
Purge test data: agentrust purge --confirm
Promote to full edge for production risk calibration

Common Mistakes

Running multiple embedded gateways on same port
Using embedded risk scores for production policy tuning — there is no historical-reliability signal
Setting AGENTRUST_EMBED_DB=:memory: and then wondering why the audit list is empty
Expecting Team/Enterprise features in embedded mode

Troubleshooting

Issue	Fix
Port in use	`AGENTRUST_EMBED_PORT=8766`
Missing uvicorn	Install `[embedded]` extra
401 from the embedded gateway	Pin `AGENTRUST_EMBED_TOKEN`; the auto-generated token changes on every restart
Empty audit list	Check you are not on `AGENTRUST_EMBED_DB=:memory:`

Embedded Gateway Overview