agentguard-py

AgentGuard Python SDK

Monitor and protect yourself with AI agent budget controls, approval workflows, and anomaly detection.

AgentGuard sits between your AI agent and its actions. Every action is validated before it runs, checking budgets, rate limits, and approval thresholds in real-time.

Install

pip install agentguard

Quick Start

from agentguard import AgentGuard

guard = AgentGuard(api_key="ag_your_api_key")  # Get this from app.agent-guard.io

# Wrap any function for automatic protection
chat = guard.wrap(
    my_chat_function,
    action="openai_chat",
    provider="openai",
    model="gpt-4",
    estimated_cost=0.05,
    get_cost=lambda r: r.usage.total_cost,
)

# This automatically:
# ✓ Checks if agent is active
# ✓ Checks budget limits
# ✓ Checks approval thresholds
# ✓ Runs your function (only if allowed)
# ✓ Logs the result
result = chat("Hello!")

Decorator Style

@guard.protect(action="openai_chat", estimated_cost=0.05)
def chat(prompt):
    return openai.chat(prompt=prompt)

result = chat("Hello!")

Core Methods

guard.check(action, estimated_cost) — Pre-action validation

result = guard.check("openai_chat", estimated_cost=0.05)

if result.allowed:
    response = openai.chat(prompt="Hello")
else:
    print(f"Blocked: {result.message}")

guard.log(action, ...) — Log an action

guard.log(
    "api_call",
    provider="openai",
    model="gpt-4",
    cost=0.05,
    status="SUCCESS",
    input_tokens=10,
    output_tokens=25,
)

guard.track(action) — Track duration

done = guard.track("openai_chat", provider="openai")

result = openai.chat(prompt="Hello")

done(cost=0.05, response=result)
# Duration is calculated automatically

Budget Management

# Get current budget status
budget = guard.get_budget()
print(f"Spent: ${budget.budget_spent} / ${budget.budget_limit}")

# Check if a specific cost is within budget
check = guard.check_budget(0.50)
if not check.allowed:
    print("Would exceed budget")

# Raise if over budget
guard.ensure_budget(0.50)  # raises BudgetExceededError if over

Approval Workflows

# Request approval for a high-cost action
approval = guard.request_approval(
    "send_bulk_email",
    description="Send marketing email to 10,000 users",
    estimated_cost=45.00,
)

# Wait for human decision (polls every 5 seconds)
try:
    decided = guard.wait_for_approval(approval.id, timeout=3600)
    print("Approved! Proceeding...")
except AgentGuardError:
    print("Rejected or expired")

Error Handling

from agentguard import (
    AgentGuardError,       # Base error
    AgentPausedError,      # Agent is paused
    AgentBlockedError,     # Agent is blocked (kill switch)
    BudgetExceededError,   # Budget limit hit
    ApprovalRequiredError, # Needs human approval
)

try:
    result = chat("Hello!")
except AgentPausedError:
    print("Agent paused — stopping gracefully")
except BudgetExceededError:
    print("Budget exceeded — waiting for reset")
except ApprovalRequiredError as e:
    print(f"Approval needed: {e.approval_id}")

Configuration

guard = AgentGuard(
    api_key="ag_your_api_key",                # Required
    base_url="https://api.agent-guard.io",    # Optional
    timeout=10,                                # Optional: seconds (default: 10)
    debug=False,                               # Optional: debug logging (default: False)
)

Dashboard

Manage your agents, view logs, approve actions, and monitor budgets at app.agent-guard.io

Links

• Website
• Dashboard
• GitHub
• JS/TypeScript SDK

License

MIT