AgentSudo Documentation

v1.0.4 Public Alpha

AgentSudo is a security middleware that implements Zero Trust architecture for AI agents. It acts as a gatekeeper between AI agents and external tools/APIs, ensuring that:

1. No agent overspends (Denial of Wallet Prevention)
2. No dangerous actions execute (Context-Aware Security)
3. No unauthorized access occurs (Just-In-Time Permissions)

The Problem

AI agents are increasingly autonomous, making API calls and executing actions without human oversight. This creates two critical risks:

Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                         AgentSudo Architecture                       │
└─────────────────────────────────────────────────────────────────────┘

┌──────────────┐      ┌──────────────────┐      ┌──────────────────┐
│              │      │                  │      │                  │
│   AI Agent   │─────▶│  AgentSudo SDK   │─────▶│  AgentSudo       │
│              │      │  (agent_sudo.py) │      │  Server          │
│              │      │                  │      │  (server.py)     │
└──────────────┘      └──────────────────┘      └────────┬─────────┘
                                                         │
                                                         ▼
                                                ┌──────────────────┐
                                                │  policies.yaml   │
                                                │  (The Brain)     │
                                                └──────────────────┘

The Flow:

1. Agent requests tool access via SDK.
2. SDK sends request with intent description.
3. Server validates: Auth → Permission → Context → Budget.
4. If approved: Returns JIT token.
5. If denied: Returns specific error (401/403/429).

Installation

Prerequisites: Python 3.10+, pip

pip install fastapi uvicorn pyyaml httpx pydantic

Project Structure

agentsudo/
├── policies.yaml      # Agent policies and rules
├── server.py          # FastAPI backend server
├── agent_sudo.py      # Python SDK
├── demo_context.py    # Validation/demo script
└── README.md          # This documentation

Quick Start

Step 1: Start the Server

uvicorn server:app --reload --port 8000

You should see: INFO: AgentSudo Server Started - Zero Trust Mode Active

Step 2: Run the Demo

python demo_context.py

Step 3: Verify Output

>> Testing SAFE intent...
[+] Safe read access granted!

>> Testing DANGEROUS intent (DELETE)...
[+] Dangerous action was BLOCKED correctly!
Reason: Context Alert: Dangerous intent detected.

Configuration

The brain of the system is policies.yaml.

agents:
  # Senior agent with higher privileges
  research_bot_01:
    secret: "secret_123"
    max_hourly_budget_usd: 5.00
    allowed_tools:
      - name: "openai_api"
        cost_per_call_usd: 0.03
        permission: "invoke"
        blocked_keywords: []
        
      - name: "database_api"
        cost_per_call_usd: 0.00
        permission: "read_only"
        blocked_keywords: ["delete", "drop", "truncate"]

API Reference

POST /request-access

Request Just-In-Time access to a tool.

# Request Body
{
  "agent_id": "research_bot_01",
  "agent_secret": "secret_123",
  "tool_name": "openai_api",
  "intent_description": "Summarize the research paper"
}

GET /spend/{agent_id}

Get current spend status for an agent.

SDK Reference

The core usage pattern for Python agents.

from agent_sudo import AgentSudo, BudgetExceededError

# Initialize client
sudo = AgentSudo(
    agent_id="research_bot_01",
    secret="secret_123"
)

# Request tool access (the core Zero Trust method)
try:
    token = sudo.get_session(
        tool_name="openai_api",
        reason="Generate summary of user's document"
    )
    print(token.token) # The JIT access token

except BudgetExceededError:
    print("Budget limit reached!")

Security Controls

1. Context-Aware Security

Before granting access, the server analyzes the intent_description for dangerous keywords.

intent = "I want to DELETE all users"
# ❌ BLOCKED - Contains "delete"

intent = "I want to read the latest users"
# ✅ ALLOWED - No dangerous keywords

2. Budget Enforcement

The server tracks spending and blocks requests that would exceed the max_hourly_budget_usd.

Production Deployment

• Real JWT Tokens: Replace mock tokens with signed JWTs.
• Persistent Storage: Replace in-memory SPEND_TRACKER with Redis.
• Audit Logging: Send logs to SIEM for compliance.

# Docker Deployment
FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY policies.yaml server.py agent_sudo.py ./
EXPOSE 8000
CMD ["uvicorn", "server:app", "--host", "0.0.0.0", "--port", "8000"]