aguard

agentguard

Official Python SDK for AgentGuard — the AI action firewall that keeps your agents safe.

Install

pip install agentguard

Requirements: Python 3.8 or later.

Quick Start

from agentguard import AgentGuard

guard = AgentGuard(api_key="ag_live_YOUR_KEY_HERE")

Then, before your agent executes any action:

result = guard.check(
    action="send_email",
    payload={"to": "user@example.com", "body": "Hello!"},
)

if result.decision == "block":
    raise Exception(f"Action blocked: {result.reason}")

# proceed with the action

Constructor Options

AgentGuard(
    api_key: str,          # required — from your AgentGuard dashboard
    base_url: str = None,  # default: https://agentguard.dev/api
                           # also read from AGENTGUARD_BASE_URL env var
    timeout: float = 5.0,  # request timeout in seconds
)

The base_url is resolved in this order:

1. base_url argument passed to the constructor
2. AGENTGUARD_BASE_URL environment variable
3. https://agentguard.dev/api (production default)

guard.check() Reference

result = guard.check(
    action: str,                        # required — name of the action
    payload: dict,                      # required — data the agent is acting on
    agent_id: str | None = None,        # which agent is acting (improves logging)
    app_user_id: str | None = None,     # end user ID (enables cross-user detection)
    app_name: str | None = None,        # identifies your app in the dashboard
    risk_context: dict | None = None,   # extra metadata for risk scoring
)

Return value — CheckResult

@dataclass
class CheckResult:
    decision: Literal["allow", "block", "review"]
    risk_level: Literal["low", "medium", "high", "critical"]
    reason: str
    log_id: int | None
    prompt_injection_detected: bool

Handling Each Decision

result = guard.check(action=action, payload=payload)

if result.decision == "allow":
    # Safe to proceed. Execute the action.
    execute_action(action, payload)

elif result.decision == "review":
    # High-risk but not definitively malicious.
    # Queue for human review or notify your security team.
    queue_for_review(action, payload, result.reason)

elif result.decision == "block":
    # Policy violation or detected threat. Do NOT proceed.
    raise Exception(f"Blocked ({result.risk_level}): {result.reason}")

Error Handling

from agentguard import (
    AgentGuard,
    AgentGuardAuthError,
    AgentGuardNetworkError,
    AgentGuardServerError,
)

try:
    result = guard.check(action=action, payload=payload)
except AgentGuardAuthError as e:
    # Invalid or expired API key — check your dashboard
    print(f"Auth error: {e}")
except AgentGuardNetworkError as e:
    # Connectivity issue — the SDK already retried once
    # Fall back gracefully (allow or queue for later)
    print(f"Network error: {e}")
except AgentGuardServerError as e:
    # Unexpected server error (5xx)
    print(f"Server error {e.status_code}: {e}")

The SDK automatically retries once on network errors. Auth errors and server errors are never retried.

Example — Flask Route

from flask import Flask, request, jsonify
from agentguard import AgentGuard
import os

guard = AgentGuard(api_key=os.environ["AGENTGUARD_KEY"])
app = Flask(__name__)

@app.post("/agent/send-email")
def send_email():
    data = request.get_json()
    result = guard.check(
        action="send_email",
        payload={"to": data["to"], "body": data["body"]},
        app_user_id=data.get("userId"),
        agent_id=data.get("agentId"),
    )

    if result.decision == "block":
        return jsonify({"error": result.reason}), 403

    # send the email...
    return jsonify({"ok": True})

Publishing to PyPI

When you're ready to publish:

cd sdks/python
pip install build twine
python -m build
twine upload dist/*

Make sure your pyproject.toml has the correct name, version, and license fields before publishing.

Links

• Dashboard — manage API keys and view logs
• API Reference — raw HTTP API docs
• GitHub — source code and issues