Documentation & Help

User Guide (Non-Expert Mode)

Quickstart

Install the SDK and make your first authorization call in under 2 minutes.

pip install agentguard-sdk

from agentguard.client import AgentGuardClient

guard = AgentGuardClient(
    api_url="https://myagentguard.com",
    key_id="YOUR_KEY_ID",
    private_key=open("private.pem").read(),
    agent_id="YOUR_AGENT_ID",
    user_id="FIREBASE_UID",
)

# Authorize a basic action
auth = guard.authorize("execute_task", {"domain": "api.openai.com"})
print(auth)  # { decision: "Approved", transactionId: "..." }

Authentication (JWT)

Every API call is authenticated with a short-lived RS256-signed JWT. The SDKs handle signing automatically. Your Key ID and RSA private key can be found in the Dashboard under Developer Settings.

# JWT payload structure (managed by the SDK)
{
  "iss": "YOUR_KEY_ID",
  "sub": "YOUR_AGENT_ID",
  "aud": "https://myagentguard.com",
  "iat": 1710000000,
  "exp": 1710000300,   # 5 minute TTL
  "action": "request_funds",
  "userId": "FIREBASE_UID"
}

V2 Middleware API

The V2 Middleware API allows you to trigger agent missions programmatically and poll for their status. Use your API Key found in the Developer Settings.

curl -X POST https://myagentguard.com/api/v1/execute \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{ "agentId": "agent_123", "prompt": "Find cheapest jeans" }'

{
  "missionId": "miss_abc123",
  "status": "queued",
  "message": "Mission started"
}

curl https://myagentguard.com/api/v1/mission/miss_abc123 \
  -H "x-api-key: YOUR_API_KEY"

{
  "status": "executing",
  "logs": [...],
  "credits_spent": 1.2
}

Credit Metering

AgentGuard V2 uses a credit-based system for usage-based billing. 1 credit ≈ $0.001.

API: authorize

Use authorize to request permission for your agent to perform any action. The gateway checks your user's policy (domain allowlist, kill switch, request limits) and returns a signed decision.

{
  "userId": "string",      // Firebase UID
  "agentId": "string",
  "action": "string",      // e.g. "browse_web"
  "domain": "string",      // e.g. "amazon.com"
  "estimatedCost": 0.004,  // USD (optional)
  "reasoning": "string"    // chain-of-thought
}

{
  "decision": "Approved",
  "transactionId": "txn_abc123",
  "didSignature": "eyJhbGci..."
}

API: request_funds (JIT Shared Payment Token)

When your agent needs to make a real payment, call request_funds. AgentGuard creates a single-use Stripe Issuing Shared Payment Token restricted to the exact amount and MCC. The card is destroyed after one transaction and the agent can never overspend.

{
  "userId":      "string",
  "agentId":     "string",
  "agentType":   "flight-hotel" | "restaurant" |
                 "smart-shopper" | "govadmin",
  "amountCents": 4599,     // $45.99 in cents
  "currency":    "usd",
  "mcc":         "5999",   // Merchant Category Code
  "reasoning":   "string"
}

{
  "cardId":    "ic_1abc...",
  "last4":     "3782",
  "exp_month": 3,
  "exp_year":  2026,
  "number":    "4000...",  // one-time only
  "cvc":       "123",
  "spendLimitCents": 4599
}

SDK usage

card = guard.request_funds(
    amount=4599,           # cents
    currency="usd",
    mcc="5999",
    reasoning="Purchase lowest-price item from Amazon",
    agent_type="smart-shopper"
)
# Use card.number, card.cvc, card.exp_month, card.exp_year to complete checkout

API: Human-in-the-Loop Approvals

When a transaction exceeds the user's approval threshold (set in the Control Center), your agent must pause and wait for the user to approve via email or dashboard. Use @approval_required in Python, or CreateApprovalRequest + PollApproval in Go/Ruby.

from agentguard.client import AgentGuardClient, approval_required, ApprovalDeniedError

guard = AgentGuardClient()

# Option A: Automatic decorator (pauses if amount > threshold)
@approval_required(guard, threshold_cents=10000, category="shopping")
def buy_item(item, amount_cents):
    card = guard.request_funds(amount=amount_cents, mcc="5999")
    # ... complete checkout

# Option B: Manual flow
approval = guard.create_approval_request(
    amount_cents=31200,
    domain="booking.com",
    reasoning="Book flight SFO-LHR for user"
)
try:
    result = guard.poll_approval(approval["id"], timeout=300)
    if result["status"] == "APPROVED":
        card = guard.request_funds(amount=31200, mcc="4511")
except ApprovalDeniedError:
    print("User denied the transaction")

Global Kill Switch

The Global Kill Switch is your ultimate safety valve. When enabled, AgentGuard instantly blocks all outgoing transactions, Shared Payment Token provisioning, and API authorizations across all agents in your workspace.

Integrating with MCP Servers

The **Model Context Protocol (MCP)** allows you to extend agent capabilities by connecting them to external toolsets. AgentGuard acts as a secure proxy between your agent logic and your MCP server.

Marketplace & Prefab Agents

AgentGuard ships with 4 ready-to-use prefab agent templates in the marketplace/ directory. Each agent is pre-configured with the correct MCCs, approval thresholds, and AgentGuard SDK integration.

Users can hire agents via the Marketplace dashboard. Policies (spend limits, approval thresholds) are managed in the Control Center.

Official SDKs

All SDKs support: authorize, request_funds, create_approval_request, and poll_approval. JWT signing, exponential backoff retry, and typed error classes are all handled automatically.

Error Reference