agentguard-py 0.1.1
Monitor and protect yourself with AI agent budget controls, approval workflows, and anomaly detection.
License: MIT
Requires Python: >=3.8
Keywords: agentguard, ai, agents, monitoring, logging, llm, openai, anthropic, budget, approval, safety

# AgentGuard Python SDK

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

[![PyPI version](https://img.shields.io/pypi/v/agentguard.svg)](https://pypi.org/project/agentguard/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

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

```bash
pip install agentguard
```

## Quick Start

```python
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

```python
@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

```python
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

```python
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

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

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

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

## Budget Management

```python
# 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

```python
# 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

```python
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

```python
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](https://app.agent-guard.io)**

## Links

- [Website](https://agent-guard.io)
- [Dashboard](https://app.agent-guard.io)
- [GitHub](https://github.com/alexhrsu/agentguard)
- [JS/TypeScript SDK](https://www.npmjs.com/package/agentguard-js)

## License

MIT