Overview
This guide will walk you through setting up AgentWarden and protecting your first AI agent action. You’ll learn how to:
- Create an account and get your API key
- Install the SDK
- Create your first agent
- Set permissions
- Check and log actions
Prerequisites: Python 3.8 or higher installed on your system
Step 1: Create Your Account
Verify Email
Check your email and verify your account.
Step 2: Get Your API Key
Navigate to Settings
Click on Settings in the left sidebar.
Copy API Key
In the General tab, you’ll find your API key. Click Copy to copy it to your clipboard.
Keep it Secret
Store your API key securely - never commit it to version control!
Your API key gives full access to your organization. Treat it like a password and never expose it in client-side code.
Step 3: Install the SDK
Install the AgentWarden Python SDK using pip:
Or add it to your requirements.txt:
Step 4: Create Your First Agent
You can create agents either through the dashboard or programmatically.
Option A: Via Dashboard (Recommended for first agent)
Go to Agents Page
Click Agents in the left sidebar.
Create Agent
Click Create Agent button.
Fill Details
- Name:
customer-support-bot
- Description:
Handles customer support requests
Copy Agent ID
After creation, copy the Agent ID - you’ll need it for the SDK.
Your Agent ID
After creating the agent, you’ll see something like:
Agent ID: 550e8400-e29b-41d4-a716-446655440000
Option B: Via API
You can also create agents programmatically (see API Reference).
Step 5: Set Permissions
Define what actions your agent can perform:
Open Agent
Click on your customer-support-bot agent in the dashboard.
Add Permission
Click Add Permission.
Configure
- Action:
stripe.refund
- Max Amount:
100.00
- Requires Approval: Toggle OFF (for amounts ≤ $100)
Save
Click Create to save the permission.
You can create multiple permissions with different limits. For example, auto-approve refunds up to $100, but require human approval for larger amounts.
Step 6: Integrate the SDK
Now let’s protect your AI agent’s actions with AgentWarden:
from agentwarden import AgentWarden
# Initialize the SDK
guard = AgentWarden(api_key="your-api-key-here")
# Your AI agent's ID (copy from dashboard after creating agent)
AGENT_ID = "550e8400-e29b-41d4-a716-446655440000" # Example format
# Before your agent performs an action, check permission
def process_customer_refund(customer_id: str, amount: float):
# Check with AgentWarden first
result = guard.check(
agent_id=AGENT_ID,
action="stripe.refund",
context={
"amount": amount,
"customer_id": customer_id
}
)
if not result.allowed:
# Action is not allowed
if result.requires_approval:
print(f"⏳ Action requires approval: {result.reason}")
# Notify admin for approval
notify_admin_for_approval(customer_id, amount)
else:
print(f"🚫 Action blocked: {result.reason}")
return False
# Permission granted - safe to proceed
try:
# Perform the actual refund
stripe.Refund.create(
charge=customer_id,
amount=int(amount * 100) # Stripe uses cents
)
# Log the successful action
guard.log(
agent_id=AGENT_ID,
action="stripe.refund",
status="success",
context={
"amount": amount,
"customer_id": customer_id
}
)
print(f"✅ Refund processed: ${amount}")
return True
except Exception as e:
# Log the failure
guard.log(
agent_id=AGENT_ID,
action="stripe.refund",
status="failed",
context={
"amount": amount,
"customer_id": customer_id,
"error": str(e)
}
)
print(f"❌ Refund failed: {e}")
return False
# Test it out
process_customer_refund("cus_123456", 50.00)
Step 7: View Logs in Dashboard
Navigate to Logs
Click Logs in the left sidebar.
View Activity
You’ll see all actions your agents have attempted, including:
- ✅ Allowed actions
- 🚫 Blocked actions
- ⏳ Actions requiring approval
Filter & Search
Use filters to find specific agents, actions, or time periods.
What’s Next?
Common Patterns
Pattern 1: Different Limits for Different Actions
# Small refunds - auto-approve
guard.check(
agent_id=AGENT_ID,
action="stripe.refund.small",
context={"amount": 25.00}
)
# Large refunds - require approval
guard.check(
agent_id=AGENT_ID,
action="stripe.refund.large",
context={"amount": 500.00}
)
Pattern 2: Environment-Based Permissions
import os
# Different permissions for staging vs production
env = os.getenv("ENVIRONMENT", "production")
action = f"deploy.{env}"
result = guard.check(
agent_id="devops-agent",
action=action,
context={"version": "v2.1.0"}
)
Pattern 3: Bulk Operations
# Check permission once for bulk operation
result = guard.check(
agent_id=AGENT_ID,
action="email.send_bulk",
context={"recipient_count": 1000}
)
if result.allowed:
send_emails(recipients)
guard.log(AGENT_ID, "email.send_bulk", "success")
Need Help?
