AgentGuard Python SDK
The reliability layer for AI agents in production. Trace executions, enforce guardrails, and monitor agent behavior — with zero changes to your agent's core logic.
Installation
pip install agentx-sdk
Quick Start
from agentguard import AgentGuard, GuardConfig
guard = AgentGuard(
api_key="your-api-key",
config=GuardConfig(api_url="https://api.agentguard.dev"),
)
# 1. Decorator — auto-capture input/output/latency
@guard.watch(agent_id="my-agent")
def run_agent(prompt: str) -> str:
return call_llm(prompt)
# 2. Context manager — fine-grained step tracing
with guard.trace(agent_id="my-agent", task="summarize") as ctx:
result = call_llm(prompt)
ctx.step("llm", "summarize", input=prompt, output=result)
ctx.record(result)
Sync Verification
Run inline verification with pass/flag/block decisions. When the verification engine determines an output is unreliable, the SDK raises AgentGuardBlockError so your application can handle it gracefully.
from agentguard import AgentGuard, GuardConfig, AgentGuardBlockError
guard = AgentGuard(
api_key="your-api-key",
config=GuardConfig(
mode="sync",
api_url="https://api.agentguard.dev",
),
)
@guard.watch(agent_id="my-agent")
def run_agent(prompt: str) -> str:
return call_llm(prompt)
try:
result = run_agent("Summarize this document")
# result is a GuardResult with confidence score
print(result.output, result.confidence, result.action)
except AgentGuardBlockError as e:
print(f"Blocked: confidence={e.result.confidence}")
Correction Cascade
Automatically correct unreliable outputs instead of blocking. When enabled, the verification engine attempts to fix issues and returns the corrected output.
guard = AgentGuard(
api_key="your-api-key",
config=GuardConfig(
mode="sync",
correction="cascade", # Enable correction
transparency="transparent", # Include correction details in result
),
)
result = run_agent("Summarize this document")
if result.corrected:
print(f"Output was corrected: {result.output}")
print(f"Original: {result.original_output}")
Session Tracking & Conversation History
Group related executions into sessions with automatic conversation history for multi-turn verification (hallucination, drift, coherence).
session = guard.session(agent_id="chat-bot")
# Turn 1
with session.trace(task="greeting", input_data="Hello") as ctx:
response = call_llm("Hello")
ctx.record(response)
# Turn 2 — conversation history from turn 1 is sent automatically
with session.trace(task="follow-up", input_data="Tell me more") as ctx:
response = call_llm("Tell me more")
ctx.record(response)
The session maintains a sliding window of conversation history (configurable via conversation_window_size), enabling cross-turn verification checks like self-contradiction detection and goal drift analysis.
Configuration
from agentguard import GuardConfig
from agentguard.models import ThresholdConfig
GuardConfig(
mode="async", # "async" (fire-and-forget) or "sync" (inline verification)
correction="none", # "none" or "cascade" (auto-correct unreliable outputs)
transparency="opaque", # "opaque" or "transparent" (include correction details)
api_url="https://api.agentguard.dev",
flush_interval_s=1.0, # Batch flush interval (async mode)
flush_batch_size=50, # Max events per flush batch
timeout_s=2.0, # HTTP timeout for API calls
conversation_window_size=10, # Max conversation turns retained per session
confidence_threshold=ThresholdConfig(
pass_threshold=0.8, # >= 0.8 → pass
flag_threshold=0.5, # >= 0.5 → flag (warning logged)
block_threshold=0.3, # < 0.3 → block (raises AgentGuardBlockError)
),
)
What's New in v0.2.0
- Sync Verification: Inline pass/flag/block decisions via
mode="sync"with configurable confidence thresholds - Correction Cascade: Auto-correct unreliable outputs with
correction="cascade", dual-timeout transport (2s verify / 12s correction), and transparent/opaque modes - Conversation-Aware Verification: Multi-turn coherence, cross-turn hallucination detection, and goal drift analysis via automatic session history
GuardResultModel: Structured verification results withconfidence,action,corrected,original_output, andcorrectionsfieldsAgentGuardBlockError: Exception raised when verification blocks output, with the fullGuardResultattachedConversationTurnModel: First-class conversation turn representation for multi-turn agents
Requirements
- Python 3.9+
- Dependencies:
httpx,pydantic(v2)
Documentation
Full documentation: docs.oppla.ai/agentguard
License
Apache 2.0 — see LICENSE for details.
Metadata
Release files for agentx-sdk 0.2.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| agentx_sdk-0.2.2.tar.gz | 22.5 kB | Without provenance | Details for agentx_sdk-0.2.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| agentx_sdk-0.2.2-py3-none-any.whl | Python 3 | none | any | Details for agentx_sdk-0.2.2-py3-none-any.whl |
Total release size: 44.1 kB
Release files / agentx_sdk-0.2.2.tar.gz
| Download URL | agentx_sdk-0.2.2.tar.gz |
|---|---|
| Size | 22.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
357b4cb22db2c50244d601643b0b6742163cef84b081d1a093b2071c5670c5eb
|
|
BLAKE2b-256 checksum How to use checksums |
9776059fd335deb28b27385f531cfb66933125ae6090a3817f63bf78099493c5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.14
|
Release files / agentx_sdk-0.2.2-py3-none-any.whl
| Download URL | agentx_sdk-0.2.2-py3-none-any.whl |
|---|---|
| Size | 21.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
8049f57e53c0ed507732b2028679c787c6c0ad38fb29de74a6ef0d219d21a1ec
|
|
BLAKE2b-256 checksum How to use checksums |
a9b3442bb74c480daa9deb1178b37a37e75de64bc9d1fe546c98126f8ccfe3bf
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.14
|
Security for agentx-sdk 0.2.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.