AgentTrust Docs

Complete setup guide for the Python SDK — PyPI package agentrust-py, import name agentrust_sdk.

Overview

Complete setup guide for the Python SDK. The PyPI distribution is agentrust-py; the import name is agentrust_sdk. Covers installation, configuration, integration patterns, CLI, and promotion from dev to production.

Why It Matters

Python is the primary SDK with the fullest feature set: embedded gateway, queue mode, framework adapters, and CLI tooling.

Prerequisites

Python ≥ 3.10
Virtual environment recommended

Step-by-Step Guide

1. Install with extras

pip install "agentrust-py[embedded,retry]"

Extra	Installs
`embedded`	In-process gateway (`embed_gateway()`)
`retry`	Exponential backoff via tenacity
`otel`	OpenTelemetry traces and metrics
`langgraph`	LangGraph `AgentTrustNode`
`crewai`	CrewAI `AgentTrustCallback`
`full`	`embedded` + `retry` + `otel` + `llm` — not the framework adapters

2. Initialize configuration

agentrust init          # interactive onboarding
agentrust init --local  # offline key for air-gap

Creates ~/.agentrust/config.yaml with your API key (plus the tier and org_id decoded from it). It does not write a gateway URL — set AGENTRUST_GATEWAY_URL, or add control_plane_url: to the file by hand.

3. Choose an integration pattern

Pattern A — Auto-instrument (zero code change):

from agentrust_sdk import auto_instrument
auto_instrument()  # patches OpenAI, LangChain, LangGraph

Pattern B — @harness decorator:

from agentrust_sdk import harness

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

Pattern C — Direct client:

from agentrust_sdk import AgentTrustClient

with AgentTrustClient() as client:
    result = client.validate(
        agent_id="my-agent",
        user="alice",
        input="user message",
        output={"text": llm_response},
        framework="Custom",
    )

4. Configure via environment

export AGENTRUST_GATEWAY_URL=http://localhost:8000
export AGENTRUST_KEY=at_team_your_key
export AGENTRUST_FAILURE_MODE=open
export AGENTRUST_TIMEOUT_SEC=10
export AGENTRUST_RETRY_ATTEMPTS=3

5. Handle blocked outputs

from agentrust_sdk import harness
from agentrust_sdk.decorator import BlockedError

@harness
def risky_agent(user, input):
    return {"action": "transfer", "amount": 50000}

try:
    # Keyword arguments — @harness reads `user` and `input` by name.
    risky_agent(user="alice", input="Transfer $50k")
except BlockedError as e:
    print(f"Blocked [{e.outcome}]: {e.reason}")

Examples

Async agent:

from agentrust_sdk import harness

@harness
async def async_agent(user: str, input: str) -> dict:
    return {"answer": await call_llm_async(input)}

Embedded dev setup:

from agentrust_sdk import harness, embed_gateway
embed_gateway()
@harness
def dev_agent(user, input): return {"ok": True}

Best Practices

Import agentrust_sdk hooks before framework imports when using auto_instrument()
Use context manager with AgentTrustClient() for connection pooling
Set AGENTRUST_FAILURE_MODE=closed in staging to surface gateway issues
Pin SDK version in requirements.txt for reproducible builds

Common Mistakes

Using from agentrust import ... — correct module is agentrust_sdk
Expecting Team-tier adapters without API key (tier defaults to OSS)
Not installing [retry] extra but setting AGENTRUST_RETRY_ATTEMPTS > 1

Troubleshooting

Issue	Fix
`GatewayUnavailableError`	Check URL; set `AGENTRUST_FAILURE_MODE=open` temporarily
`TierGateError`	Upgrade tier or remove tier-gated adapter
`GatewayVersionError`	Upgrade SDK or gateway to compatible versions

Sync Client
Async Client
Environment Variables
agentrust_sdk/README.md in the repository

Python Quickstart