API Reference

Complete listing of all public classes, functions, errors, and CLI commands.

Core

guard

Main decorator. Can be used with or without arguments.

from agentguard import guard

@guard                                    # No-arg form
@guard(validate_input=True)               # With options
@guard(config=GuardConfig(...))           # With config object

GuardConfig

Reusable configuration dataclass. See GuardConfig Reference for all fields.

HallucinationDetector

Standalone hallucination detection. See Hallucination Detection.

SharedState

Cross-agent state coordination. See Shared State.

Config Classes

CircuitBreakerConfig

CircuitBreakerConfig(
    failure_threshold: int = 5,
    success_threshold: int = 2,
    timeout: float = 60.0,
    half_open_max_calls: int = 3,
    excluded_exceptions: tuple = (),
)

RateLimitConfig

RateLimitConfig(
    calls_per_second: float = None,
    calls_per_minute: float = None,
    calls_per_hour: float = None,
    burst: int = 10,
    block: bool = True,
)

BudgetConfig

BudgetConfig(
    max_cost_per_call: float = None,
    max_cost_per_session: float = None,
    max_calls_per_session: int = None,
    alert_threshold: float = 0.8,
    on_exceed: GuardAction = GuardAction.BLOCK,
    cost_per_call: float = None,
    use_dynamic_llm_costs: bool = True,
    model_pricing_overrides: dict | None = None,
    record_llm_spend: bool = True,
)

For real model-call spend tracking, use guard_openai_client, guard_openai_compatible_client, or guard_anthropic_client together with a TokenBudget.

RetryConfig

RetryConfig(
    max_retries: int = 3,
    initial_delay: float = 0.5,
    backoff_factor: float = 2.0,
    max_delay: float = 30.0,
    jitter: bool = True,
    retry_on: tuple = (Exception,),
)

Error Classes

All errors include useful attributes:

from agentguard.errors import CircuitOpenError, RateLimitExceeded

try:
    result = my_tool("hello")
except CircuitOpenError as e:
    print(e.retry_after)     # Seconds until circuit half-opens
    print(e.failure_count)   # Number of failures that triggered open
except RateLimitExceeded as e:
    print(e.retry_after)     # Seconds until a token is available
    print(e.limit)           # The rate limit that was exceeded

CLI Commands

# Examples
agentguard generate ./traces --output ./tests/test_generated.py
agentguard traces list ./traces
agentguard traces report ./traces --output report.json
agentguard benchmark --model gpt-4o-mini
agentguard policy validate agentguard.toml
agentguard policy apply agentguard.toml

Verification Engine Types

VerificationEngine

Bayesian multi-signal verification engine. Main methods:

VerificationResult

Returned by engine.verify(). Fields: verdict ("accept"/"flag"/"block"), confidence, signals, tier_reached, explanation, prior, posterior, is_hallucinated, reason.

SignalResult

Per-signal detail. Fields: fired (bool), score (0–1), detail (str), likelihood_ratio (float).

VerificationTier

Enum: TIER_0 (zero-cost pre-checks only), TIER_1 (post-execution checks added), TIER_2 (reserved).

Baseline & SPC Types

ToolBaseline

Maintains running statistics per tool. Methods: record(), check_anomaly(), to_dict(). Tracks latency, response size, field frequency, and numeric value ranges.

RunningStats

Online mean/variance via Welford’s algorithm. Properties: count, mean, variance, std, recent_values. Method: update(value).

SPCResult

Result of SPC check. Fields: is_anomalous (bool), anomalies (list of SPCAnomaly), score (0–1).

SPCAnomaly

Single SPC rule violation. Fields: rule, field, value, sigma_distance, description.

Adaptive Threshold Types

AdaptiveThresholdManager

Learns per-tool thresholds from feedback using EMA. Methods: get_threshold(), record_feedback(), get_prior(), update_likelihood_ratio(), reset().

ThresholdStats

Per-tool stats. Fields: tool_name, threshold, total_feedback, hallucination_count, correct_count, ema_hallucination_rate.

Consistency Types

ConsistencyTracker

Tracks tool outputs across calls. Methods: record(), check_session_consistency(), check_historical_consistency(), clear_session().

ConsistencyResult / ConsistencyViolation

Result of consistency checks. ConsistencyViolation fields: kind, field, current_value, prior_value, severity, description.

Middleware Types

MiddlewareChain

Ordered list of middleware. Methods: use(mw), build(terminal), run(ctx, terminal), copy(), prepend(mw).

MiddlewareContext

Context passed through the chain. Fields: tool_name, args, kwargs, config, metadata, timestamps, call_id. Methods: mark(label), elapsed_ms(since).

Multi-Agent Shared Types

SharedBudget

Thread-safe shared budget pool. Properties: .config, .session_spend, .session_calls. Methods: stats(), reset(), check_pre_call().

SharedCircuitBreaker

Thread-safe shared circuit breaker. Properties: .config, .circuit_state. Methods: check(), record_success(), record_failure(), reset(), stats().

Integration Types

GuardedCrewAITool

Wraps CrewAI tools with agentguard. Methods: run(), arun(), to_crewai_tool(). Attributes: name, description, guarded_fn.

GuardedAutoGenTool

Wraps AutoGen functions. Methods: __call__(), acall(), as_function(), register(llm, exec). Attributes: name, description, guarded_fn.

Benchmark Types

BenchmarkRunner

Orchestrates benchmark execution. Methods: add_scenario(), add_scenarios(), run(model, base_url, api_key), compare(results_list).

BenchmarkResults

Aggregate results. Properties: tool_call_accuracy, parameter_accuracy, hallucination_rate, avg_latency_ms. Methods: summary(), by_category(), to_report().

BenchmarkScenario

Single test case. Fields: name, description, category, tools, messages, expected_tool_calls, validate_fn, tags.

BuiltinScenarios

Static methods returning scenario lists: BASIC_TOOL_CALLING, MULTI_TOOL_SELECTION, HALLUCINATION_RESISTANCE, PARAMETER_EXTRACTION, TOOL_SELECTION, ERROR_HANDLING, ALL.

Telemetry Types

instrument_agentguard(tool_names=None)

Enable OpenTelemetry instrumentation for guarded tools.

StructuredLogger

Zero-dependency JSON-lines logger. Methods: after_call_hook(), get_records(), clear(), log_event(), log_hallucination().

guard_span(name, tool_name, **attributes)

Context manager for custom OTel spans.

Provider Types

Provider enum

Supported providers: OPENAI, ANTHROPIC, OPENROUTER, GROQ, TOGETHER, FIREWORKS, CUSTOM.

Providers registry

Static methods for provider detection and configuration.