Advanced Scopes

This v2.7.4 source says it verifies token audiences, but verify_audience remains disabled and the issued tokens have no aud claim. To reject tokens created for another AgentOS, set verify_audience=True in AuthorizationConfig and add "aud": "my-agent-os" to the token payload. Until then, another instance using the same HMAC secret can accept these tokens.

Issue HS256 tokens for five privilege tiers and use global, per-agent, and wildcard scopes to filter agents and gate runs.

advanced_scopes.py

"""
Advanced RBAC Example with AgentOS - Simplified Scopes with Audience Verification

This example demonstrates the AgentOS RBAC system with simplified scope format:

Scope Format:
1. Global resource scopes: resource:action
2. Per-resource scopes: resource:<resource-id>:action
3. Wildcard support: resource:*:action

Scope Examples:
- config:read - Read system config
- agents:read - List all agents
- agents:web-agent:read - Read specific agent
- agents:web-agent:run - Run specific agent
- agents:*:run - Run ANY agent (wildcard)
- agent_os:admin - Full access to everything

Prerequisites:
- Set JWT_VERIFICATION_KEY environment variable
- Endpoints automatically filter based on user scopes
"""

import os
from datetime import UTC, datetime, timedelta

import jwt
from agno.agent import Agent
from agno.db.postgres import PostgresDb
from agno.models.openai import OpenAIResponses
from agno.os import AgentOS
from agno.os.config import AuthorizationConfig
from agno.tools.websearch import WebSearchTools

# ---------------------------------------------------------------------------
# Create Example
# ---------------------------------------------------------------------------

# JWT Secret (use environment variable in production)
JWT_SECRET = os.getenv("JWT_VERIFICATION_KEY", "your-secret-key-at-least-256-bits-long")

# Setup database
db = PostgresDb(db_url="postgresql+psycopg://ai:ai@localhost:5532/ai")

# Create agents with different capabilities
web_search_agent = Agent(
    id="web-search-agent",
    name="Web Search Agent",
    model=OpenAIResponses(id="gpt-5.5"),
    db=db,
    tools=[WebSearchTools()],
    add_history_to_context=True,
    markdown=True,
)

analyst_agent = Agent(
    id="analyst-agent",
    name="Data Analyst Agent",
    model=OpenAIResponses(id="gpt-5.5"),
    db=db,
    add_history_to_context=True,
    markdown=True,
)

admin_agent = Agent(
    id="admin-agent",
    name="Admin Agent",
    model=OpenAIResponses(id="gpt-5.5"),
    db=db,
    markdown=True,
)


# Create AgentOS with specific ID for audience verification
agent_os = AgentOS(
    id="my-agent-os",
    name="Production AgentOS",
    description="RBAC Protected AgentOS with Simplified Scopes",
    agents=[web_search_agent, analyst_agent, admin_agent],
    authorization=True,  # Enable RBAC
    authorization_config=AuthorizationConfig(
        verification_keys=[JWT_SECRET],
        algorithm="HS256",
    ),
)

# Get the app
app = agent_os.get_app()


def create_token(user_id: str, scopes: list[str], hours: int = 24) -> str:
    """Helper function to create JWT tokens with scopes and audience."""
    payload = {
        "sub": user_id,
        "scopes": scopes,
        "exp": datetime.now(UTC) + timedelta(hours=hours),
        "iat": datetime.now(UTC),
    }
    return jwt.encode(payload, JWT_SECRET, algorithm="HS256")


# ---------------------------------------------------------------------------
# Run Example
# ---------------------------------------------------------------------------

if __name__ == "__main__":
    """
    Scope Hierarchy and Examples:
    
    1. ADMIN SCOPE (highest privilege):
       - "agent_os:admin" grants full access to all endpoints
    
    2. GLOBAL RESOURCE SCOPES:
       - "config:read" - Read system configuration
       - "agents:read" - List all agents
       - "agents:run" - Run any agent
    
    3. PER-RESOURCE SCOPES (granular permissions):
       - "agents:web-search-agent:read" - Read specific agent
       - "agents:web-search-agent:run" - Run specific agent
       - "agents:*:run" - Run ANY agent (wildcard)
    
    AUDIENCE VERIFICATION:
       - Tokens for other AgentOS instances will be rejected
    """

    # EXAMPLE 1: Admin user - full access
    admin_token = create_token(
        user_id="admin_user",
        scopes=["agent_os:admin"],
    )

    # EXAMPLE 2: Power user - can list and run all agents
    power_user_token = create_token(
        user_id="power_user",
        scopes=[
            "config:read",
            "agents:read",
            "agents:run",
            "sessions:read",
            "sessions:write",
        ],
    )

    # EXAMPLE 3: Limited user - can only run specific agents
    limited_user_token = create_token(
        user_id="limited_user",
        scopes=[
            "agents:web-search-agent:read",
            "agents:web-search-agent:run",
            "agents:analyst-agent:read",
            "agents:analyst-agent:run",
            # Note: This user won't see admin-agent in GET /agents
        ],
    )

    # EXAMPLE 4: Read-only user - can only view agents
    readonly_user_token = create_token(
        user_id="readonly_user",
        scopes=[
            "agents:*:read",  # Can read all agents
            "config:read",  # Can read system info
            # Cannot run any agents
        ],
    )

    # EXAMPLE 5: Wildcard user - can run any agent
    wildcard_user_token = create_token(
        user_id="wildcard_user",
        scopes=[
            "agents:read",  # Read all agents
            "agents:*:run",  # Run any agent (wildcard)
        ],
    )

    print("\n" + "=" * 80)
    print("ADVANCED RBAC TEST TOKENS")
    print("=" * 80)

    print("\n1. ADMIN USER (full access):")
    print("   Scopes: ['agent_os:admin']")
    print("   Token: " + admin_token[:50] + "...")

    print("\n2. POWER USER (global access):")
    print("   Scopes: ['config:read', 'agents:read', 'agents:run', ...]")
    print("   Token: " + power_user_token[:50] + "...")

    print("\n3. LIMITED USER (specific agents only):")
    print(
        "   Scopes: ['agents:web-search-agent:read', 'agents:web-search-agent:run', ...]"
    )
    print("   Token: " + limited_user_token[:50] + "...")

    print("\n4. READ-ONLY USER (view only):")
    print("   Scopes: ['agents:*:read', 'config:read']")
    print("   Token: " + readonly_user_token[:50] + "...")

    print("\n5. WILDCARD USER (run any agent):")
    print("   Scopes: ['agents:read', 'agents:*:run']")
    print("   Token: " + wildcard_user_token[:50] + "...")

    print("\n" + "=" * 80)
    print("TEST COMMANDS")
    print("=" * 80)

    print("\n# Test admin access (should work for all endpoints):")
    print(
        'curl -H "Authorization: Bearer '
        + admin_token
        + '" http://localhost:7777/agents'
    )
    print(
        'curl -H "Authorization: Bearer '
        + admin_token
        + '" http://localhost:7777/config'
    )

    print("\n# Test power user (should see all agents and run any):")
    print(
        'curl -H "Authorization: Bearer '
        + power_user_token
        + '" http://localhost:7777/agents'
    )
    print(
        'curl -X POST -H "Authorization: Bearer ' + power_user_token + '" \\\n'
        '  -F "message=test" http://localhost:7777/agents/web-search-agent/runs'
    )

    print(
        "\n# Test limited user (should only see 2 agents: web-search-agent and analyst-agent):"
    )
    print(
        'curl -H "Authorization: Bearer '
        + limited_user_token
        + '" http://localhost:7777/agents'
    )
    print(
        'curl -X POST -H "Authorization: Bearer ' + limited_user_token + '" \\\n'
        '  -F "message=test" http://localhost:7777/agents/web-search-agent/runs'
    )

    print("\n# Test read-only user (should see all agents but cannot run):")
    print(
        'curl -H "Authorization: Bearer '
        + readonly_user_token
        + '" http://localhost:7777/agents'
    )
    print(
        'curl -X POST -H "Authorization: Bearer ' + readonly_user_token + '" \\\n'
        '  -F "message=test" http://localhost:7777/agents/web-search-agent/runs  # Should fail'
    )

    print("\n# Test wildcard user (should work for any agent):")
    print(
        'curl -H "Authorization: Bearer '
        + wildcard_user_token
        + '" http://localhost:7777/agents'
    )
    print(
        'curl -X POST -H "Authorization: Bearer ' + wildcard_user_token + '" \\\n'
        '  -F "message=test" http://localhost:7777/agents/admin-agent/runs'
    )

    print("\n" + "=" * 80)
    print("SCOPE CHECKING BEHAVIOR")
    print("=" * 80)
    print("""
For GET /agents:
- Filters the agent list based on user's scopes
- 'agents:web-search-agent:read' -> only see web-search-agent
- 'agents:*:read' -> see all agents (wildcard)
- 'agents:read' -> see all agents (global scope)

For POST /agents/{agent_id}/runs:
- Checks for matching scopes with resource ID
- Requires either:
  * 'agents:<agent_id>:run' (specific agent)
  * 'agents:*:run' (any agent - wildcard)
  * 'agents:run' (global scope)
  * 'agent_os:admin' (full access)

AUDIENCE VERIFICATION:
- Invalid audience returns 401 Unauthorized
    """)

    print("\n" + "=" * 80 + "\n")

    # Serve the application
    agent_os.serve(app="advanced_scopes:app", port=7777, reload=True)

Run the Example

The source falls back to a public demonstration secret. Local demos can use it, but before exposing this server set JWT_VERIFICATION_KEY to a private random value of at least 32 bytes and use the same value to sign tokens.

Set up your virtual environment

uv venv --python 3.12
source .venv/bin/activate

uv venv --python 3.12
.venv\Scripts\activate

Install dependencies

uv pip install -U "agno[os]" "psycopg[binary]" ddgs openai

Export your OpenAI API key

export OPENAI_API_KEY="your_openai_api_key_here"

$Env:OPENAI_API_KEY="your_openai_api_key_here"

Run PgVector

docker run -d \
  -e POSTGRES_DB=ai \
  -e POSTGRES_USER=ai \
  -e POSTGRES_PASSWORD=ai \
  -e PGDATA=/var/lib/postgresql \
  -v pgvolume:/var/lib/postgresql \
  -p 5532:5432 \
  --name pgvector \
  agnohq/pgvector:18

docker run -d `
  -e POSTGRES_DB=ai `
  -e POSTGRES_USER=ai `
  -e POSTGRES_PASSWORD=ai `
  -e PGDATA=/var/lib/postgresql `
  -v pgvolume:/var/lib/postgresql `
  -p 5532:5432 `
  --name pgvector `
  agnohq/pgvector:18

Run the example

Save the code above as advanced_scopes.py, then run:

python advanced_scopes.py

Full source: cookbook/05_agent_os/rbac/symmetric/advanced_scopes.py

Examples

Primitives

Context

Models

Tools

More

Advanced Scopes

Run the Example

​Run the Example

Run the Example