Architecture Overview

Overview

AgentTrust follows a validate-at-runtime architecture. The SDK (or HTTP client) sends an execution envelope to the gateway. The gateway runs a deterministic fast-path pipeline (validation → confidence → risk → decision), persists an audit record, and optionally enqueues async LLM judge jobs and human review items.

┌─────────────┐     POST /v1/runtime/validate     ┌──────────────────────┐
│  Agent App  │ ─────────────────────────────────▶│  AgentTrust Gateway  │
│  (SDK/HTTP) │◀───────────────────────────────── │  (FastAPI)           │
└─────────────┘     ValidateResponse              └──────────┬───────────┘
                                                             │
                    ┌────────────────────────────────────────┼────────────┐
                    ▼                    ▼                   ▼            ▼
              PostgreSQL            Redis              Review Queue   LLM Judge
              (audit store)    (jobs, cache)          (human ops)   (async)

Why It Matters

Understanding the architecture helps you choose the right deployment mode, tune latency expectations, and know which features require which infrastructure components.

Prerequisites

Familiarity with How It Works and the repository layout.

Step-by-Step Guide

Validation pipeline (full gateway)

Each POST /v1/runtime/validate request runs:

1. Historical reliability — Redis cache → audit store lookup for agent_id
2. ValidationEngine — 6 deterministic checks (target <20ms, zero LLM calls)
3. ConfidenceEngine — 7-signal weighted confidence score
4. RiskEngine — 4-factor risk scoring → low / medium / high / critical
5. Trust chain — Multi-agent provenance check (Enterprise)
6. DecisionEngine — Maps scores to governance outcome
7. Audit persist — Append-only ledger with hash chain
8. Review queue — escalate / request_evidence routed to operators
9. LLM judge — Async background enrichment (Enterprise)

Validation checks (fast path)

Decision outcomes

approve · retry · request_evidence · escalate · block · pending

Repository layout

agent-trust-sdk/
├── agentrust_sdk/          # Python SDK (pip install agentrust-sdk)
├── sdks/typescript/        # TypeScript/Node SDK
├── agentrust-edge/
│   ├── gateway/            # FastAPI governance runtime
│   ├── dashboard/          # React operator UI
│   ├── docker-compose.yml
│   └── k8s/                # Helm + raw manifests
├── examples/               # Framework integration cookbooks
└── docs/                   # This documentation

Deployment modes

Gateway API surface

Examples

Docker Compose stack (staging):

Env-only promotion — same app code across environments:

# Dev
embed_gateway()  # or AGENTRUST_GATEWAY_URL=http://localhost:8765

# Staging
AGENTRUST_GATEWAY_URL=https://staging.internal:8000

# Production
AGENTRUST_GATEWAY_URL=https://agentrust.internal:8000
AGENTRUST_FAILURE_MODE=open

Best Practices

• Use embedded gateway for dev/CI; full edge for staging and production
• Run gateway with AUTH_ENABLED=true in all non-dev environments
• Mount policy packs as read-only ConfigMaps in Kubernetes
• Export OpenTelemetry traces from both SDK and gateway (see OTEL Cookbook)
• Verify audit chain integrity periodically via GET /v1/audit/chain/verify

Common Mistakes

• Assuming embedded gateway has the same capabilities as full edge
• Deploying dashboard without setting VITE_API_URL to the gateway
• Skipping Redis in production (breaks async judge and rate limiting)

Troubleshooting

Related Resources

• Architecture Metrics (engineering)
• How It Works
• Docker Compose
• Kubernetes
• Embedded Gateway