AgentGuard SDK for Python

Install the package:

pip install actaclad-agentguard

The distribution is named actaclad-agentguard and exposes the onboarding API as import agentguard (the import name is unchanged).

Python version

• Python 3.10+ — full auto-instrumentation. pip install actaclad-agentguard pulls traceloop-sdk, so OpenAI / Anthropic / Gemini calls are traced with no per-call code.
• Python 3.8 / 3.9 — installs and runs in manual mode. traceloop-sdk requires 3.10, so it is skipped automatically (PEP 508 marker) and the SDK falls back to manual export. Auto-instrumentation of providers is not available; use track() and record_generation(). Gemini sync is still traced by the SDK on 3.9; Gemini batch always uses record_generation() (see below). To force the extra explicitly on 3.10+: pip install "actaclad-agentguard[auto]".

You normally leave AGENTGUARD_MODE=auto (the default) — the SDK downgrades to manual only when traceloop is unavailable. context() / track() are optional enrichment on top of either mode, not a switch into manual mode.

Environment

AGENTGUARD_HOST=https://agentgaurd-a0acc6egbhced0dc.centralindia-01.azurewebsites.net
AGENTGUARD_PUBLIC_KEY=pk-lf-...
AGENTGUARD_SECRET_KEY=sk-lf-...
APP_ENV=production
AGENTGUARD_MODE=auto

Span filtering (default: infra dropped)

By default the SDK drops infrastructure spans (DB, HTTP client/server, messaging, RPC) at the exporter and keeps LLM, agent/tool, and custom spans — this removes noise and reduces storage/egress. It is a denylist: any span the SDK doesn't recognize as infra is kept, so nothing is silently lost.

To send full traces including infra spans:

AGENTGUARD_INCLUDE_INFRA_SPANS=true     # default: infra spans are dropped

(The legacy AGENTGUARD_DROP_INFRA_SPANS flag is still honored; INCLUDE takes precedence.)

Compatibility env vars are also accepted:

AGENTGUARD_BASE_URL=https://agentgaurd-a0acc6egbhced0dc.centralindia-01.azurewebsites.net
AGENT_GUARD_BASE_URL=https://agentgaurd-a0acc6egbhced0dc.centralindia-01.azurewebsites.net
AGENT_GUARD_PUBLIC_KEY=pk-lf-...
AGENT_GUARD_SECRET_KEY=sk-lf-...

Use API keys from an existing AgentGuard project. The Python SDK does not create console organizations or projects; create or select the project in the console, then copy its public and secret keys into the environment.

Layer 1 — Base Observability

Initialize once at startup before creating LLM clients:

import agentguard

agentguard.init(service_name="my-service")

Then make LLM calls exactly as before:

from openai import OpenAI

resp = OpenAI().chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello"}],
)

Optional Cohere/Mistral instrumentor warnings during startup are ignored by the SDK. They do not block OpenAI or Gemini tracing when those clients are installed and initialized after agentguard.init().

Layer 2 — Tenant Context

Set business/channel once per request:

with agentguard.context(
    business_id="caratlane",
    channel="instagram_dm",
    session_id=conversation_id,
):
    handle_message(message)

Layer 3 — Feature Attribution

Wrap each feature-level LLM call:

def handle_message(message):
    with agentguard.track("sentiment"):
        sentiment = run_sentiment(message)

    with agentguard.track("reply"):
        reply = run_reply(message)

track() emits groupable tags and filterable metadata:

• business:*
• channel:*
• feature:*
• biz_channel:*
• biz_feat:*
• chan_feat:*
• biz_chan_feat:*

Gemini — sync vs batch

Sync calls (client.models.generate_content(...)) auto-trace on Python 3.9+. Batch calls (client.batches.create(...)) are asynchronous — there are no tokens at submit time, so auto-instrumentation cannot capture them. Record the cost with record_generation() when you fetch the results:

for line in batch_results:                  # each line carries usage_metadata
    um = line.response.usage_metadata
    agentguard.record_generation(
        feature="transcription",
        model="gemini-2.5-flash",
        batch=True,                          # bills at the batch rate (model -> "...-batch")
        input_tokens=um.prompt_token_count,
        output_tokens=um.candidates_token_count,
        reasoning_tokens=um.thoughts_token_count or 0,   # thinking tokens, billed at output rate
    )  # business/channel/session inherit the surrounding context()

batch=True suffixes the model with -batch so the pricing registry applies the provider's batch discount (Gemini batch = 50% of sync). reasoning_tokens (thinking/thoughts_token_count) is recorded separately and priced at the output rate, so cost matches the provider bill without double-counting. The model name must exist in the pricing table or cost shows 0.

record_generation() also covers any call auto-instrumentation can't reach — custom/REST providers or an SDK without an instrumentor. Cost is computed server-side from the model name; standard models work out of the box, new or custom model names are added once in the AgentGuard console.

Manual Smoke Test

Use manual mode to test export without real LLM calls:

AGENTGUARD_MODE=manual python examples/smoke_test_agentguard.py \
  --business-id caratlane \
  --channel instagram_dm \
  --flow-id checkout-flow \
  --feature-id sentiment

PowerShell:

$env:AGENTGUARD_MODE="manual"
python examples/smoke_test_agentguard.py `
  --business-id caratlane `
  --channel instagram_dm `
  --flow-id checkout-flow `
  --feature-id sentiment

Legacy API Compatibility

The older agentguard_sdk module is still included:

from agentguard_sdk import AgentGuard

New onboarding docs should use:

import agentguard