SDK Reference

Installation

pip install agentshield

configure()

Configure the SDK globally. All parameters are optional if set via environment variables.

import agentshield as shield

shield.configure(
    api_key="ags_live_...",   # or AGENTSHIELD_API_KEY env var
    debug=False,               # enable debug logging
    timeout=5.0,               # HTTP timeout in seconds
)

@shield() — Monitor

Decorator that tracks every LLM call made inside the wrapped function.

from agentshield import shield

@shield(
    agent="my-agent",          # required — unique agent identifier
    model=None,                # override model name (auto-detected)
    session_id=None,           # link to a session for replay
    metadata={},               # arbitrary key-value tags
)
def my_agent_function():
    ...

session() — Replay

Context manager that groups events into a named session for visual replay.

from agentshield import session

with session(name="optional-name", session_id="optional-custom-id") as s:
    print(s.session_id)  # UUID auto-generated if not provided
    # All @shield calls inside are linked to this session

Protect — Exceptions

AgentShield raises typed exceptions when guardrails trigger:

from agentshield.exceptions import (
    BudgetExceededError,    # agent exceeded its budget cap
    AgentFrozenError,       # kill switch is active
    GuardrailBlockedError,  # content rule blocked the request
    AuthenticationError,    # invalid API key
)

try:
    result = await my_agent(query)
except BudgetExceededError as e:
    print(f"Budget exceeded: {e.current}/{e.limit}")
except GuardrailBlockedError as e:
    print(f"Blocked by rule: {e.rule_name}")

Error handling

Non-blocking: AgentShield never breaks your agent for tracking errors.

Blocking: Budget, frozen, guardrail, and auth errors are always raised.

Environment variables

AGENTSHIELD_API_KEY=ags_live_...   # required
AGENTSHIELD_API_URL=...             # override API endpoint (default: api.agentshield.one)
AGENTSHIELD_DEBUG=true              # enable debug logging