Quickstart

Install the SDK

The PyPI distribution is agentrust-py. The Python module you import is agentrust_sdk — the names differ, and that is expected.

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

Confirm the install and see which tier you are on:

agentrust whoami

  Not authenticated (OSS mode — schema validation only)

  Get a free key: https://app.agent-trust.tech/signup

That is the expected output here — with no API key you are on the OSS tier, which is all this quickstart needs. The full capability matrix only prints once a key is configured.

Write a governed agent

Create agent.py. The @harness decorator is the entire integration — one line above the function you want governed.

from agentrust_sdk import harness, embed_gateway

# Starts an in-process governance gateway on http://127.0.0.1:8765 and points
# every AgentTrust client created afterwards at it. Idempotent.
embed_gateway()


@harness
def my_agent(user: str, input: str) -> dict:
    """Your agent. Return a dict so the schema check has something to validate."""
    return {"answer": "Hello from a governed agent"}


if __name__ == "__main__":
    result = my_agent(user="alice", input="What is AI governance?")
    print(result)

Run it

python agent.py

{'answer': 'Hello from a governed agent'}

Your agent returns exactly what it always did — @harness never changes the return value. What changed is invisible from the outside, and it is the whole point:

1. Pre-check — POST /v1/runtime/pre-check ran before the function body. Had the decision been block, BlockedError would have been raised and the body would never have executed — no payment sent, no row written, no email delivered.
2. Your function ran.
3. Post-check — POST /v1/runtime/post-check scored the actual output and decided whether you were allowed to see it.

Both phases were persisted to an append-only SQLite ledger.

Read the audit trail

Every governed call leaves two rows — one per phase.

agentrust audit tail

  ENVELOPE     AGENT                DECISION     RISK         CONF  TIMESTAMP
  ───────────────────────────────────────────────────────────────────────────
  4988f888     my_agent             approve      low          91.5  2026-08-15 09:14:02
  3000a5b2     my_agent             approve      low          89.5  2026-08-15 09:14:02

You can also query the gateway over HTTP — but only while your process is still alive. The embedded gateway runs in a daemon thread, so it dies the moment agent.py exits; python agent.py & followed by curl just gives you connection refused.

Keep it up long enough to inspect by parking the script:

import os
os.environ["AGENTRUST_EMBED_TOKEN"] = "local-dev-token"   # pin it BEFORE starting

from agentrust_sdk import harness, embed_gateway

embed_gateway()

@harness
def my_agent(user: str, input: str) -> dict:
    return {"answer": "Hello from a governed agent"}

my_agent(user="alice", input="What is AI governance?")

input("gateway running on :8765 — press Enter to stop")   # keeps the thread alive

Then, from another shell:

curl -s http://127.0.0.1:8765/v1/health

curl -s -H "Authorization: Bearer local-dev-token" \
  "http://127.0.0.1:8765/v1/audit/executions?limit=5" | python -m json.tool

/v1/health is the only unauthenticated route; everything else answers 401 without the bearer token. Set AGENTRUST_EMBED_TOKEN before embed_gateway() runs — otherwise a fresh token is generated inside the Python process and your shell never sees it.

Watch it block something

Governance you have never seen refuse anything is governance you cannot trust. Set the kill switch and re-run — every agent is hard-blocked, ahead of any scoring:

AGENTRUST_KILL_SWITCH=1 python agent.py

from agentrust_sdk import BlockedError

try:
    my_agent(user="alice", input="What is AI governance?")
except BlockedError as e:
    print(e.outcome)      # "block"
    print(e.reason)       # "Kill switch: Environment kill switch (AGENTRUST_KILL_SWITCH=1)"
    print(e.envelope_id)  # the audit row to quote in an incident review

The block lands at the pre-check, so the function body never runs — confirm it by putting a print() inside my_agent and watching it stay silent. The blocked attempt is still written to the ledger, with decision=block and risk_tier=critical.

Promote to production

Application code does not change between environments. Only the environment does:

export AGENTRUST_GATEWAY_URL=https://agentrust.internal:8000
export AGENTRUST_KEY=at_team_your_key_here
export AGENTRUST_FAILURE_MODE=closed

Delete the embed_gateway() call and the same @harness now runs against the full Edge gateway — PostgreSQL-backed audit, the review queue, analytics, and the LLM judge.

And when you need governance gone right now, with no redeploy and no code change:

export AGENTRUST_ENABLED=false

@harness becomes an identity wrapper. Your agents run exactly as they did before you installed anything.