Getting Started

This guide will help you install AgentSudo and protect your first function in under 5 minutes.

Installation

Install AgentSudo using pip:

pip install agentsudo

Step 1: Create an Agent

An agent represents an AI entity with specific permissions:

from agentsudo import Agent

# Create a support bot with limited permissions
support_bot = Agent(
    name="SupportBot",
    scopes=["read:orders", "write:tickets"]
)

Step 2: Protect Your Functions

Use the @sudo decorator to require specific permissions:

from agentsudo import sudo

@sudo(scope="read:orders")
def get_order(order_id: str):
    return {"id": order_id, "status": "shipped"}

@sudo(scope="write:tickets")
def create_ticket(subject: str, body: str):
    return {"ticket_id": "TKT-001", "subject": subject}

Step 3: Use Sessions

Wrap agent operations in a session:

with support_bot.start_session():
    # These calls are now permission-checked
    order = get_order("ORD-123")      # ✅ Allowed
    ticket = create_ticket(           # ✅ Allowed
        "Order inquiry",
        "Where is my order?"
    )

Step 4: Handle Denials

When an agent lacks permission, a PermissionDeniedError is raised:

from agentsudo import Agent, sudo, PermissionDeniedError

analytics_bot = Agent(
    name="AnalyticsBot",
    scopes=["read:orders"]  # Read-only!
)

@sudo(scope="write:orders")
def update_order(order_id: str, status: str):
    pass

with analytics_bot.start_session():
    try:
        update_order("ORD-123", "cancelled")
    except PermissionDeniedError as e:
        print(f"Denied: {e}")
        # Denied: Agent 'AnalyticsBot' lacks scope 'write:orders'

Complete Example

Here's a complete working example:

from agentsudo import Agent, sudo, PermissionDeniedError

# Define agents with different permission levels
support_bot = Agent(
    name="SupportBot",
    scopes=["read:orders", "write:refunds:small"]
)

admin_bot = Agent(
    name="AdminBot",
    scopes=["*"]  # Full access
)

# Protected functions
@sudo(scope="read:orders")
def get_order(order_id: str):
    return {"id": order_id, "total": 99.99}

@sudo(scope="write:refunds:small")
def small_refund(order_id: str, amount: float):
    if amount > 50:
        raise ValueError("Amount too large for small refund")
    print(f"Refunding ${amount} for {order_id}")

@sudo(scope="write:refunds:large")
def large_refund(order_id: str, amount: float):
    print(f"Refunding ${amount} for {order_id}")

# Support bot can do small refunds
with support_bot.start_session():
    order = get_order("ORD-123")
    small_refund("ORD-123", 25.00)  # ✅ Works
    
    try:
        large_refund("ORD-123", 500.00)  # ❌ Denied
    except PermissionDeniedError:
        print("Support bot cannot do large refunds")

# Admin bot can do everything
with admin_bot.start_session():
    large_refund("ORD-123", 500.00)  # ✅ Works

Local Logging (Default)

AgentSudo works completely offline by default. All permission checks are logged locally in JSON format:

# No configuration needed - logs appear in your console
with support_bot.start_session():
    get_order("ORD-123")
    # Logs: {"timestamp": "...", "agent_name": "SupportBot", "scope": "read:orders", "allowed": true}

Cloud Dashboard

Connect to the hosted dashboard for visual monitoring and team visibility:

import agentsudo

# Connect to dashboard
agentsudo.configure_cloud(api_key="as_your_api_key")

Open Dashboard to get your API key and start monitoring.

Next Steps

• Agents - Deep dive into agent configuration
• Scopes - Learn about permission patterns
• Guardrails - Topic filtering and prompt injection protection
• Framework Integrations - Use with LangChain, LlamaIndex, FastAPI