Skip to content

Sessions

Sessions provide bounded operational contexts for AI agents, limiting what they can do within a defined scope.

What is a Session?

A session is a time-limited, resource-limited context for agent operations. Think of it as a "budget" for what an agent can do.

Limit Purpose
max_actions Maximum number of operations
max_value_usd Maximum total monetary value
expires_at Time limit

Why Use Sessions?

Sessions provide guardrails for autonomous agents:

  • Limit Blast Radius: If an agent goes rogue, damage is contained
  • Budget Control: Prevent runaway costs
  • Time Boxing: Operations must complete within a window
  • Audit Grouping: All actions within a session are linked

Creating Sessions

from certusrodo import CertusOrdoClient

client = CertusOrdoClient(api_key="aa_your_api_key")

# Create a session for an agent
session = client.sessions.create(
    agent_id="your-agent-id",
    max_actions=100,           # Max 100 operations
    max_value_usd=1000.00,     # Max $1000 total value
    expires_in_seconds=3600    # 1 hour time limit
)

print(f"Session ID: {session.id}")
print(f"Expires at: {session.expires_at}")

Session Limits

Action Limits

Control how many operations an agent can perform:

# Agent can only perform 50 actions
session = client.sessions.create(
    agent_id=agent.id,
    max_actions=50
)

# Check remaining actions
session = client.sessions.get(session.id)
remaining = session.max_actions - session.action_count
print(f"Actions remaining: {remaining}")

Value Limits

Control the total monetary value of operations:

# Agent can only process up to $5000
session = client.sessions.create(
    agent_id=agent.id,
    max_value_usd=5000.00
)

# Check remaining budget
session = client.sessions.get(session.id)
remaining = session.max_value_usd - session.value_used_usd
print(f"Budget remaining: ${remaining}")

Time Limits

Control how long a session remains valid:

# Session expires in 30 minutes
session = client.sessions.create(
    agent_id=agent.id,
    expires_in_seconds=1800
)

# Check time remaining
from datetime import datetime
remaining = session.expires_at - datetime.now()
print(f"Time remaining: {remaining}")

Session Lifecycle

┌──────────┐     ┌──────────┐     ┌───────────┐
│  CREATE  │────>│  ACTIVE  │────>│ COMPLETED │
└──────────┘     └────┬─────┘     └───────────┘
                      │
        ┌─────────────┼─────────────┐
        ▼             ▼             ▼
   ┌─────────┐  ┌──────────┐  ┌───────────┐
   │ EXPIRED │  │TERMINATED│  │ EXHAUSTED │
   └─────────┘  └──────────┘  └───────────┘
Status Meaning
active Session is valid and accepting operations
completed Session ended normally
expired Time limit reached
terminated Manually ended early
exhausted Action or value limit reached

Using Sessions with Transactions

Sessions group related transactions:

# Create session
session = client.sessions.create(
    agent_id=agent.id,
    max_actions=10,
    max_value_usd=500.00
)

# Transactions within the session
txn1 = client.transactions.begin(
    session_id=session.id,
    pre_state={"balance": 1000},
    action_type="transfer"
)

txn2 = client.transactions.begin(
    session_id=session.id,
    pre_state={"balance": 900},
    action_type="transfer"
)

# All transactions are linked to this session

Managing Sessions

List Sessions

# All sessions
sessions = client.sessions.list()

# Filter by status
active = client.sessions.list(status="active")

Get Session Details

session = client.sessions.get(session.id)

print(f"Status: {session.status}")
print(f"Actions: {session.action_count}/{session.max_actions}")
print(f"Value: ${session.value_used_usd}/${session.max_value_usd}")

End a Session

# End session normally
client.sessions.end(session.id)

# Session status changes to "completed"

Session Patterns

Pattern 1: Daily Budget

# Create a daily session for a trading agent
daily_session = client.sessions.create(
    agent_id=trading_agent.id,
    max_value_usd=10000.00,      # $10k daily limit
    max_actions=1000,             # Max 1000 trades
    expires_in_seconds=86400      # 24 hours
)

Pattern 2: Task-Based Session

# Session for a specific task
def process_invoices(agent_id, invoice_count):
    session = client.sessions.create(
        agent_id=agent_id,
        max_actions=invoice_count * 3,  # 3 ops per invoice
        expires_in_seconds=7200          # 2 hours max
    )

    try:
        for invoice in invoices:
            process_single_invoice(invoice, session.id)
    finally:
        client.sessions.end(session.id)

Pattern 3: Supervised Session

# Human-supervised session with tight limits
supervised_session = client.sessions.create(
    agent_id=agent.id,
    max_actions=5,           # Only 5 actions
    max_value_usd=100.00,    # Max $100
    expires_in_seconds=300   # 5 minutes
)

# Human reviews after session ends

Error Handling

from certusrodo import SessionError

try:
    # Attempt operation in exhausted session
    txn = client.transactions.begin(
        session_id=exhausted_session.id,
        pre_state={"data": "value"},
        action_type="update"
    )
except SessionError as e:
    print(f"Session error: {e}")
    # Session limit reached or expired

Best Practices

1. Set Appropriate Limits

# ✅ Good - limits based on expected workload
session = client.sessions.create(
    agent_id=agent.id,
    max_actions=expected_operations * 1.2,  # 20% buffer
    max_value_usd=expected_value * 1.5      # 50% buffer
)

# ❌ Bad - arbitrary large limits
session = client.sessions.create(
    agent_id=agent.id,
    max_actions=999999,
    max_value_usd=999999.00
)

2. Always End Sessions

session = client.sessions.create(agent_id=agent.id, max_actions=100)

try:
    # Do work
    perform_operations(session.id)
finally:
    # Always end the session
    client.sessions.end(session.id)

3. Monitor Active Sessions

# Regular check for stuck sessions
active_sessions = client.sessions.list(status="active")

for session in active_sessions:
    age = datetime.now() - session.created_at
    if age.hours > 4:
        print(f"Long-running session: {session.id}")

Next Steps