Agents

Learn how to create and manage AI agents with AgentSudo.

An Agent represents an AI entity with specific permissions. Think of it like a user account, but for your AI.

Creating an Agent

from agentsudo import Agent

support_bot = Agent(
    name="SupportBot",
    scopes=["read:customers", "write:tickets"],
    role="support",
    session_ttl=3600  # 1 hour
)

Parameters

Parameter	Type	Required	Description
`name`	`str`	Yes	Unique identifier for the agent
`scopes`	`list[str]`	Yes	List of permission scopes
`role`	`str`	No	Role label (e.g., "support", "admin")
`session_ttl`	`int`	No	Session timeout in seconds (default: 3600)
`api_key`	`str`	No	API key for dashboard telemetry

Agent Sessions

Agents operate within sessions. A session:

Has a start time and expiration
Tracks all permission checks
Can be ended early

Starting a Session

# Context manager (recommended)
with support_bot.start_session() as session:
    # Agent operations here
    pass

# Manual management
session = support_bot.start_session()
try:
    # Agent operations here
    pass
finally:
    session.end()

Session Properties

with support_bot.start_session() as session:
    print(session.agent_name)    # "SupportBot"
    print(session.started_at)    # datetime
    print(session.expires_at)    # datetime
    print(session.is_expired)    # bool
    print(session.scopes)        # ["read:customers", "write:tickets"]

Multiple Agents

You can create multiple agents with different permissions:

# Read-only agent
reader = Agent(
    name="ReaderBot",
    scopes=["read:*"],
    role="reader"
)

# Support agent
support = Agent(
    name="SupportBot",
    scopes=["read:customers", "write:tickets", "write:refunds:small"],
    role="support"
)

# Admin agent
admin = Agent(
    name="AdminBot",
    scopes=["*"],  # Full access
    role="admin"
)

Checking Permissions

You can check if an agent has a scope without calling a function:

with support_bot.start_session() as session:
    if session.has_scope("write:refunds"):
        print("Can process refunds")
    else:
        print("Cannot process refunds")
    
    # Check multiple scopes
    if session.has_all_scopes(["read:customers", "write:tickets"]):
        print("Has all required scopes")

Agent with Dashboard

To send events to the dashboard, add your API key:

support_bot = Agent(
    name="SupportBot",
    scopes=["read:customers", "write:tickets"],
    api_key="as_your_api_key_here"
)

💡

Get your API key from the Dashboard → Overview → API Configuration

Best Practices

1. Use Descriptive Names

# ✅ Good - clear purpose
customer_support_bot = Agent(name="CustomerSupportBot", ...)
order_processor = Agent(name="OrderProcessor", ...)

# ❌ Bad - unclear
bot1 = Agent(name="Bot1", ...)
agent = Agent(name="Agent", ...)

2. Principle of Least Privilege

# ✅ Good - minimal permissions
support_bot = Agent(
    name="SupportBot",
    scopes=["read:orders", "write:tickets"]  # Only what's needed
)

# ❌ Bad - too permissive
support_bot = Agent(
    name="SupportBot",
    scopes=["*"]  # Full access when not needed
)

3. Use Hierarchical Scopes

# ✅ Good - specific permissions
support_bot = Agent(
    name="SupportBot",
    scopes=[
        "write:refunds:small",   # Only small refunds
        "write:refunds:medium"   # Up to medium
    ]
)

# Instead of
support_bot = Agent(
    name="SupportBot",
    scopes=["write:refunds"]  # All refunds
)

4. Set Appropriate TTLs

# Short-lived task
quick_task = Agent(
    name="QuickTask",
    scopes=["read:data"],
    session_ttl=300  # 5 minutes
)

# Long-running process
batch_processor = Agent(
    name="BatchProcessor",
    scopes=["read:data", "write:results"],
    session_ttl=86400  # 24 hours
)