Autoload

Overview

Autoload enables zero-code AgentTrust bootstrap by starting the embedded gateway and applying auto-instrumentation via environment variables and PYTHONSTARTUP — no changes to your application source code.

Why It Matters

Legacy codebases and third-party tools where you cannot modify imports benefit from governance injection at process startup.

Prerequisites

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

Step-by-Step Guide

1. Set environment variables

export AGENTRUST_AUTOLOAD_EMBED=true
export AGENTRUST_AUTOLOAD_AGENT_ID=my-agent
export AGENTRUST_AUTO_INSTRUMENT=true

2. Configure PYTHONSTARTUP

export PYTHONSTARTUP=$(python -c "import agentrust_sdk; import os; print(os.path.dirname(agentrust_sdk.__file__) + '/autoload.py')")

Or use one of the other activation mechanisms autoload.py supports:

sitecustomize.py (site-wide — survives any entry point):

import agentrust_sdk.autoload  # noqa: F401

PYTHONPATH + sitecustomize (no write access to site-packages):

mkdir -p /tmp/agentrust_site
echo "import agentrust_sdk.autoload" > /tmp/agentrust_site/sitecustomize.py
export PYTHONPATH=/tmp/agentrust_site:$PYTHONPATH

gunicorn / uvicorn workers — PYTHONSTARTUP never runs under gunicorn --preload, and patches applied before the fork do not survive it. The module exposes a post_fork hook that re-applies them in each worker:

gunicorn myapp:app --preload \
  --worker-class uvicorn.workers.UvicornWorker \
  --config agentrust_sdk.autoload

3. Run your application normally

python your_existing_app.py
# Embedded gateway starts; OpenAI/LangChain/LangGraph patched automatically

4. Verify

agentrust status
agentrust audit tail

Examples

Docker entrypoint:

ENV AGENTRUST_AUTOLOAD_EMBED=true
ENV AGENTRUST_AUTOLOAD_AGENT_ID=container-agent
ENV PYTHONSTARTUP=/app/autoload.py

CI test job:

env:
  AGENTRUST_AUTOLOAD_EMBED: "true"
  AGENTRUST_AUTOLOAD_AGENT_ID: "ci-agent"
  AGENTRUST_ENABLED: "true"

Best Practices

• Use autoload for brownfield integrations only
• Prefer explicit @harness or auto_instrument() in new code
• Set AGENTRUST_AUTOLOAD_AGENT_ID to a meaningful production agent name
• Disable with AGENTRUST_ENABLED=false for instant rollback

Common Mistakes

• Autoload without [embedded] extra when AGENTRUST_AUTOLOAD_EMBED=true
• Conflicting with application's own PYTHONSTARTUP (merge scripts)
• Using autoload in production without monitoring embedded SQLite growth

Troubleshooting

Related Resources

• Auto-Instrumentation Overview
• Zero-Code Setup
• Embedded Gateway Overview