Troubleshooting - AgentWarden

Overview

This guide helps you diagnose and fix common issues with AgentWarden integration.

Permission Check Issues

Problem: “No permission found for action”

Symptoms:

result = guard.check(agent_id, "stripe.refund", context)
# result.allowed = False
# result.reason = "No permission found for action 'stripe.refund'"

Causes & Solutions:

1. Permission doesn't exist

Check: Go to dashboard → Agents → [Your Agent] → PermissionsSolution: Create the permission

    Action: stripe.refund
    Max Amount: 100.00
    Requires Approval: No

2. Action name mismatch

Check: Verify exact spelling and case

    # Wrong
    guard.check(agent_id, "stripe.Refund", context)  # Capital R
    guard.check(agent_id, "stripe_refund", context)  # Underscore
    
    # Correct
    guard.check(agent_id, "stripe.refund", context)  # Lowercase, dot

3. Wrong agent ID

Check: Print the agent ID you’re using

    print(f"Using agent ID: {agent_id}")

Solution: Copy the correct agent ID from the dashboard

Problem: “Amount exceeds maximum allowed”

Symptoms:

result = guard.check(agent_id, "stripe.refund", {"amount": 150.00})
# result.reason = "Amount 150.00 exceeds maximum allowed 100.00"

Solutions:

Increase Limit
Create Tiered Permissions
Request Approval

Update the permission’s max_amount in the dashboard:

Go to Agents → [Your Agent] → Permissions
Edit the permission
Increase Max Amount to desired value
Save

Create multiple permissions with different limits:

    stripe.refund.small - Max $50
    stripe.refund.medium - Max $200  
    stripe.refund.large - Max $1000 (requires approval)

Then route appropriately in code:

    if amount <= 50:
        action = "stripe.refund.small"
    elif amount <= 200:
        action = "stripe.refund.medium"
    else:
        action = "stripe.refund.large"

Set requires_approval = true for this permission tier

Problem: “Agent is not active”

Symptoms:

result.reason = "Agent is not active (status: inactive)"

Solution:

Go to dashboard → Agents
Find the agent
Check status badge
If inactive, click agent → Change status to “Active”

Authentication Issues

Problem: “Invalid API key”

Symptoms:

AuthenticationError: Invalid API key

Diagnosis:

import os

# Print what key is being used
api_key = os.getenv('AGENTWARDEN_API_KEY')
print(f"Using API key: {api_key[:10]}..." if api_key else "API key not found!")

Common causes:

Check .env file

    # Verify .env exists
    cat .env
    
    # Check for typos
    AGENTWARDEN_API_KEY=ak_1234567890abcdef  # Correct
    AGENT_WARDEN_API_KEY=...  # Wrong - underscore
    AGENTWARDEN_APIKEY=...     # Wrong - no underscore

Verify environment variables load

    from dotenv import load_dotenv
    load_dotenv()  # Must call this!
    
    import os
    print(os.getenv('AGENTWARDEN_API_KEY'))

Copy fresh key from dashboard

Settings → General → Copy API Key

Check for extra spaces

    # Wrong - has trailing space
    AGENTWARDEN_API_KEY=ak_1234567890abcdef 
    
    # Correct
    AGENTWARDEN_API_KEY=ak_1234567890abcdef

Problem: API key works locally but not in production

Check environment variables in production:

# For systemd service
sudo systemctl show agentwarden --property=Environment

# For Docker
docker exec container_name env | grep AGENTWARDEN

# For Heroku
heroku config:get AGENTWARDEN_API_KEY

# For AWS Lambda
aws lambda get-function-configuration --function-name my-function

Solution: Set environment variable in production environment

Rate Limiting

Problem: “Rate limit exceeded”

Symptoms:

RateLimitError: Rate limit exceeded. Please try again in 60 seconds.

Immediate fix:

import time

# Wait and retry
time.sleep(60)
result = guard.check(agent_id, action, context)

Long-term solutions:

Implement Backoff
Cache Results
Upgrade Plan

    from agentwarden import RateLimitError
    import time
    
    def check_with_retry(agent_id, action, context, max_retries=3):
        for attempt in range(max_retries):
            try:
                return guard.check(agent_id, action, context)
            except RateLimitError:
                if attempt < max_retries - 1:
                    wait = (2 ** attempt) * 1  # 1s, 2s, 4s
                    time.sleep(wait)
                else:
                    raise

    from functools import lru_cache
    
    @lru_cache(maxsize=1000)
    def cached_check(agent_id, action, context_str):
        context = json.loads(context_str)
        return guard.check(agent_id, action, context)
    
    # Use with short TTL
    result = cached_check(agent_id, action, json.dumps(context))

Plan	Rate Limit
Free	100/min
Pro	1,000/min
Business	10,000/min

Network Issues

Problem: “Connection timeout” or “Network unreachable”

Diagnosis:

# Test API connectivity
curl -I https://api.agentwarden.io/health

# Check DNS resolution
nslookup api.agentwarden.io

# Test from your server
curl -X POST https://api.agentwarden.io/sdk/check \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "test", "action": "test", "context": {}}'

Solutions:

1. Check Firewall Rules

Ensure outbound HTTPS (port 443) is allowed:

    # Check if port 443 is open
    nc -zv api.agentwarden.io 443

2. Configure Proxy

If behind a corporate proxy:

    import os
    os.environ['HTTPS_PROXY'] = 'http://proxy.company.com:8080'
    
    guard = AgentWarden(api_key=api_key)

3. Increase Timeout

    guard = AgentWarden(
        api_key=api_key,
        timeout=60  # Increase from default 30s
    )

4. Implement Retry

    from agentwarden import NetworkError
    
    for attempt in range(3):
        try:
            result = guard.check(agent_id, action, context)
            break
        except NetworkError:
            if attempt < 2:
                time.sleep(2)
            else:
                # Fail-safe: deny action
                result = {"allowed": False, "reason": "System unavailable"}

Logging Issues

Problem: Logs not appearing in dashboard

Possible causes:

Check log call

    # Verify log is actually being called
    print("About to log...")
    guard.log(agent_id, action, "success", context)
    print("Logged successfully")

Check for errors

    try:
        guard.log(agent_id, action, "success", context)
    except Exception as e:
        print(f"Logging failed: {e}")

Verify agent exists

The agent must exist and belong to your organization

Check plan limits

Free plan: 1,000 logs/monthGo to Settings → Plans & Billing to see usage

Problem: “Monthly log limit reached”

Solution options:

Upgrade plan - Settings → Plans & Billing
Log selectively - Only log important actions:

   # Only log high-value actions
   if action in HIGH_VALUE_ACTIONS:
       guard.log(agent_id, action, status, context)

Wait for reset - Limits reset monthly

Integration Issues

Problem: SDK not found

Symptoms:

ModuleNotFoundError: No module named 'agentwarden'

Solution:

# Install SDK
pip install agentwarden

# Verify installation
pip list | grep agentwarden

# Check Python version (requires 3.8+)
python --version

Problem: Agent ID not found

Get your agent ID:

Via Dashboard:
- Go to Agents
- Click on agent
- Copy the ID from the URL or page
Via API:

   curl https://api.agentwarden.io/api/agents \
     -H "Authorization: Bearer YOUR_JWT_TOKEN"

Print in code:

   # List all agents
   response = requests.get(
       'https://api.agentwarden.io/api/agents',
       headers={'Authorization': f'Bearer {jwt_token}'}
   )
   agents = response.json()
   for agent in agents:
       print(f"{agent['name']}: {agent['id']}")

Approval Workflow Issues

Problem: Approvals not showing in dashboard

Check:

Permission has requires_approval = true
Action is being checked (not just executed directly)
You’re logged in with correct organization

Verify approval was created:

result = guard.check(agent_id, action, context)
print(f"Requires approval: {result.requires_approval}")
print(f"Approval ID: {result.approval_id}")

Problem: Can’t approve/deny requests

Possible causes:

Not an admin - Only admins can approve
- Solution: Have an admin grant you permissions
Approval already decided - Check status
Session expired - Log out and log back in

Performance Issues

Problem: Slow permission checks

Measure latency:

import time

start = time.time()
result = guard.check(agent_id, action, context)
duration = time.time() - start

print(f"Check took {duration:.3f}s")

if duration > 1.0:
    print("⚠️ Slow check detected!")

Solutions:

Reduce Context Size
Implement Caching
Check Network

    # Don't send huge objects
    context = {
        "amount": 50,
        "customer_id": "cus_123"
        # Don't include entire customer object!
    }

    from functools import lru_cache
    
    @lru_cache(maxsize=1000)
    def cached_check(agent_id, action, context_hash):
        return guard.check(agent_id, action, context)

    # Ping API
    ping api.agentwarden.io
    
    # Check latency
    curl -w "@curl-format.txt" -o /dev/null -s \
      https://api.agentwarden.io/health

Testing Issues

Problem: Tests failing in CI/CD

Common causes:

API key not set in CI:

   # .github/workflows/test.yml
   env:
     AGENTWARDEN_API_KEY: ${{ secrets.AGENTWARDEN_API_KEY }}

Network blocked in CI:
- Use test mode or mock the SDK
Mock not configured:

   from unittest.mock import Mock, patch
   
   with patch('agentwarden.AgentWarden') as MockGuard:
       mock_guard = MockGuard.return_value
       mock_guard.check.return_value = Mock(allowed=True)
       # Test code...

Debugging Tips

Enable Debug Logging

import logging

# Enable SDK debug logs
logging.basicConfig(level=logging.DEBUG)
logger = logging.getLogger('agentwarden')
logger.setLevel(logging.DEBUG)

# Now all SDK calls will be logged
guard = AgentWarden(api_key=api_key)
result = guard.check(agent_id, action, context)

Inspect Request/Response

import requests

# Make raw API call to see exact request/response
response = requests.post(
    'https://api.agentwarden.io/sdk/check',
    headers={
        'X-API-Key': api_key,
        'Content-Type': 'application/json'
    },
    json={
        'agent_id': agent_id,
        'action': action,
        'context': context
    }
)

print(f"Status: {response.status_code}")
print(f"Headers: {response.headers}")
print(f"Body: {response.json()}")

Check API Status

# Check if API is up
curl https://status.agentwarden.io

# Or check directly
curl https://api.agentwarden.io/health

Getting Help

If you’re still stuck:

Check Status Page

See if there’s an ongoing incident

Discord Community

Ask the community for help

Email Support

Contact our support team

GitHub Issues

Report bugs or request features

Diagnostic Checklist

When reporting issues, include:

Next Steps

Best Practices

Follow recommended patterns

Error Handling

Handle errors properly

Integration Examples

See working examples

Python SDK

Full SDK reference

Get Started

Core Concepts

SDK

Integration Guides

​Overview

​Permission Check Issues

​Problem: “No permission found for action”

​Problem: “Amount exceeds maximum allowed”

​Problem: “Agent is not active”

​Authentication Issues

​Problem: “Invalid API key”

​Problem: API key works locally but not in production

​Rate Limiting

​Problem: “Rate limit exceeded”

​Network Issues

​Problem: “Connection timeout” or “Network unreachable”

​Logging Issues

​Problem: Logs not appearing in dashboard

​Problem: “Monthly log limit reached”

​Integration Issues

​Problem: SDK not found

​Problem: Agent ID not found

​Approval Workflow Issues

​Problem: Approvals not showing in dashboard

​Problem: Can’t approve/deny requests

​Performance Issues

​Problem: Slow permission checks

​Testing Issues

​Problem: Tests failing in CI/CD

​Debugging Tips

​Enable Debug Logging

​Inspect Request/Response

​Check API Status

​Getting Help

Check Status Page

Discord Community

Email Support

GitHub Issues

​Diagnostic Checklist

​Next Steps

Best Practices

Error Handling

Integration Examples

Python SDK

Overview

Permission Check Issues

Problem: “No permission found for action”

Problem: “Amount exceeds maximum allowed”

Problem: “Agent is not active”

Authentication Issues

Problem: “Invalid API key”

Problem: API key works locally but not in production

Rate Limiting

Problem: “Rate limit exceeded”

Network Issues

Problem: “Connection timeout” or “Network unreachable”

Logging Issues

Problem: Logs not appearing in dashboard

Problem: “Monthly log limit reached”

Integration Issues

Problem: SDK not found

Problem: Agent ID not found

Approval Workflow Issues

Problem: Approvals not showing in dashboard

Problem: Can’t approve/deny requests

Performance Issues

Problem: Slow permission checks

Testing Issues

Problem: Tests failing in CI/CD

Debugging Tips

Enable Debug Logging

Inspect Request/Response

Check API Status

Getting Help

Diagnostic Checklist

Next Steps