Python

Aeonic Python SDK

Aeonic Python SDK enables runtime monitoring, drift detection, and governance for AI agents running inside Python applications. It works by observing agent-powered routes at runtime, capturing request/response samples, and securely sending them to the Aeonic platform for analysis.

The SDK is framework-aware, declarative, non-intrusive, and production-safe. Only routes explicitly marked as agent routes are tracked; all other routes are completely ignored.

Supported frameworks

FastAPI
Django

Step 1. Installation

Install the base SDK (core only — requests is included):

pip install aeonic-agentguard-sdk-python

Install with your framework (recommended):

# FastAPI
pip install aeonic-agentguard-sdk-python[fastapi]

# Django
pip install aeonic-agentguard-sdk-python[django]

PyPI package name is aeonic-agentguard-sdk-python; import as aeonic.

Check the installed version

import aeonic
print(aeonic.__version__)

Requirements

Python >= 3.9
Core dependency: requests>=2.25.0 (installed automatically)
FastAPI (optional): fastapi>=0.68.0 — install via [fastapi] extra
Django (optional): django>=3.2.0 — install via [django] extra

Environment variables (optional)

AEONIC_ENDPOINT — Aeonic platform endpoint URL
AEONIC_DEBUG — set to any value to enable debug logging
ORIGIN / BASE_URL — your application's public URL, sent with sample payloads
PORT / HOST — used to auto-detect origin when ORIGIN is not set

Step 2. SDK initialization (required)

Initialize the SDK once at application startup.

from aeonic import init

init({
    "api_key": str,                    # REQUIRED
    "app": Any | None,                 # Optional: FastAPI/Django app for route introspection
    "service_name": str | None,        # Optional (recommended)
    "introspection_delay_ms": int,     # Optional: Delay before route scan (default: 2000ms)
    "capture_payloads": {
        "max_samples": int             # Default: 10
    }
})

What this does

Authenticates your service with Aeonic
Automatically resolves tenant identity via api_key
Sets payload sampling limits per agent route
Discovers and registers all agent routes at startup (if app is provided)
Emits complete agent inventory to the Aeonic platform before serving traffic

Example (with route introspection)

from aeonic import init
from fastapi import FastAPI

app = FastAPI()

init({
    "api_key": "ag_test_123",
    "app": app,
    "service_name": "payments-api",
    "introspection_delay_ms": 2000,
    "capture_payloads": {
        "max_samples": 10
    }
})

Step 3. FastAPI integration

Aeonic uses two components in FastAPI: a global middleware registered once, and a route-level dependency to mark agent routes.

Quick start

from fastapi import Depends, FastAPI
from aeonic import init
from aeonic.adapters.fastapi import agent_middleware, with_agent

app = FastAPI()
app.add_middleware(agent_middleware)

init({
    "api_key": "your_api_key",
    "app": app,
    "service_name": "my-service",
})

@app.post(
    "/agent/chat",
    dependencies=[Depends(with_agent({"name": "ChatAgent", "type": "support", "model": ["gpt-4o"]}))],
)
async def chat_agent(payload: dict):
    return {"reply": "Hello!"}

Run with: uvicorn main:app --reload

1. Register global middleware

from fastapi import FastAPI
from aeonic.adapters.fastapi import agent_middleware

app = FastAPI()
app.add_middleware(agent_middleware)

2. Mark agent routes

from fastapi import Depends
from aeonic.adapters.fastapi import with_agent

@app.post(
    "/agent/finance",
    dependencies=[
        Depends(
            with_agent({
                "name": "RefundRiskAgent",
                "type": "finance",
                "model": ["gpt-4o"]
            })
        )
    ]
)
async def finance_agent(payload: dict):
    return {
        "approved": True,
        "amount": payload["amount"]
    }

How it works (FastAPI)

FastAPI integration uses a global middleware (agent_middleware) and a route-level dependency (with_agent) to mark specific endpoints as agents.
init() authenticates your service, sets payload sampling limits, and (when you pass app) can automatically discover and register agent routes at startup.
agent_middleware hooks into the response lifecycle but is a no-op unless the route was marked with with_agent.

What happens internally (per agent route)

Request and response payloads are captured for agent routes.
Samples are buffered per agent route up to max_samples (default 10).
When the buffer is full, data is sent to the Aeonic platform and agent health status is evaluated.

FastAPI summary

Only marked routes tracked
Async safe
Middleware-based
No contextvars hacks
Production ready

Step 4. Django integration

Django uses a global middleware and a route decorator to mark agent routes. Call init() once at startup (for example in settings.py or wsgi.py).

settings.py

MIDDLEWARE = [
    ...
    "aeonic.adapters.django.agent_middleware",
]

from aeonic import init

init({
    "api_key": "YOUR_API_KEY",
    "service_name": "django-test-app",
    "capture_payloads": {
        "max_samples": 10
    }
})

views.py

from django.http import JsonResponse
from aeonic.adapters.django import with_agent

@with_agent({
    "name": "RefundRiskAgent",
    "type": "finance",
    "model": ["gpt-4o"]
})
def finance_agent(request):
    return JsonResponse({
        "approved": True,
        "amount": 500
    })

How it works (Django)

Django uses global middleware (aeonic.adapters.django.agent_middleware) and a route decorator (with_agent).
The middleware observes responses but ignores any request whose view is not decorated with with_agent.
The decorator registers the agent at import time and tags request.aeonic with agent metadata and payload at request time.

What happens internally (per agent view)

For decorated views, request and response payloads are captured (including JSON bodies and query params where applicable).
Samples are buffered per agent up to max_samples and then flushed asynchronously to Aeonic.
Non-agent views and assessment traffic (X-Aeonic-Assessment header) are skipped.

Django summary

Declarative agent marking
Middleware-based capture
Sync-safe
No framework coupling
Production ready

Step 5. Configuration & agent metadata

Key init() options

api_key (required): your Aeonic API key.
app: FastAPI or Django app instance for route introspection.
service_name: logical service identifier.
introspection_delay_ms (optional): delay before route scan (default 2000).
capture_payloads.max_samples (optional): max samples per agent route (default 10).
agentguard_enabled (optional): when True (default), registers as AgentGuard instance in a background thread.

Agent metadata for with_agent()

name: logical agent name.
type: business domain (finance, healthcare, etc.).
model: AI models used (e.g. ["gpt-4o"]).

Agent concepts

Aeonic correlates HTTP route + method + agent metadata for drift detection, behavior consistency checks, and health classification per route.

Security & privacy

Payloads are sampled, not streamed
Only up to max_samples are collected per flush
SDK never blocks or alters application behavior
Non-agent routes are never inspected

Agent status lifecycle

The Aeonic platform classifies agents as Healthy, Warning, Drifting, or Failed. Status updates are visible in the Aeonic dashboard.

Important rules

Do not wrap business logic in SDK functions
Do not rely on thread-local or contextvar hacks
Always mark agent routes explicitly
Initialize SDK before app starts

Minimal setup summary

Install aeonic-agentguard-sdk-python with the matching framework extra.
Import init, agent_middleware, and with_agent.
Call init() at application startup with your API key.
Register the Aeonic middleware once.
Mark each agent route with appropriate agent metadata.

Under the hood, init() stores a normalized config, kicks off background route introspection after introspection_delay_ms, optionally registers this process as an AgentGuard instance, and emits a complete agent inventory to the platform before serving traffic.

Step 6. Troubleshooting

RuntimeError: Aeonic SDK not initialized

Call init() once at application startup before any SDK features are used.

Samples are not being captured

Ensure the route is marked with with_agent() (FastAPI dependency or Django decorator).
Ensure global middleware is registered (agent_middleware).
Confirm the agent is not blocked or quarantined (check Aeonic dashboard).
Set AEONIC_DEBUG=1 to see SDK debug output.

ModuleNotFoundError: No module named 'fastapi' or 'django'

pip install aeonic-agentguard-sdk-python[fastapi]
# or
pip install aeonic-agentguard-sdk-python[django]

Agent inventory not emitted at startup

For FastAPI, pass "app": app to init().
For Django, ensure init() runs during startup and routes are registered before introspection completes.
Increase introspection_delay_ms if routes are registered late (e.g. 3000 or 5000).

Platform connection issues

export AEONIC_ENDPOINT=https://your-aeonic-endpoint

# Windows PowerShell:
$env:AEONIC_ENDPOINT="https://your-aeonic-endpoint"

Step 7. SDK function reference

Public SDK functions and middleware for integrating Aeonic into your application.

aeonic.init(config: dict)

Initializes the SDK once at startup, validates configuration, kicks off background route introspection, and optionally registers the process as an AgentGuard instance.

api_key (required)
app (optional) — enables automatic route discovery at startup
service_name, capture_payloads.max_samples, introspection_delay_ms, agentguard_enabled

Never blocks the main thread; introspection and registration run in background daemon threads.

from aeonic.core import get_config

cfg = get_config()  # raises RuntimeError if init() was not called

aeonic.adapters.fastapi.agent_middleware

FastAPI middleware that captures samples only for routes marked with with_agent. Skips assessment traffic (x-aeonic-assessment: true) and blocked/quarantined agents.

aeonic.adapters.fastapi.with_agent(agent)

FastAPI dependency factory that marks an endpoint as an agent route and attaches metadata to request.state.aeonic for the middleware.

aeonic.adapters.django.agent_middleware

Django middleware class with the same sampling behavior as the FastAPI adapter. Skips assessment traffic (X-Aeonic-Assessment: true) and blocked/quarantined agents.

aeonic.adapters.django.with_agent(agent)

Decorator that marks a Django view as an agent route and sets request.aeonic with agent metadata and request payload.

Summary of public entry points

aeonic.init — one-time SDK setup
aeonic.adapters.fastapi.agent_middleware / aeonic.adapters.fastapi.with_agent
aeonic.adapters.django.agent_middleware / aeonic.adapters.django.with_agent
Advanced: aeonic.core.get_config(), get_agent_metadata(func) (introspection helpers)