Agent Permission Management

Control which A2A agents can be accessed by specific keys or teams in LiteLLM.

Overview

Agent Permission Management lets you restrict which agents a LiteLLM Virtual Key or Team can access. This is useful for:

• Multi-tenant environments: Give different teams access to different agents
• Security: Prevent keys from invoking agents they shouldn't have access to
• Compliance: Enforce access policies for sensitive agent workflows

When permissions are configured:

• GET /v1/agents only returns agents the key/team can access
• POST /a2a/{agent_id} (Invoking an agent) returns 403 Forbidden if access is denied

Setting Permissions on a Key

This example shows how to create a key with agent permissions and test access.

1. Get Your Agent ID

1. Go to Agents in the sidebar
2. Click into the agent you want
3. Copy the Agent ID

curl "http://localhost:4000/v1/agents" \\
  -H "Authorization: Bearer sk-master-key"

Response:

{
  "agents": [
    {"agent_id": "agent-123", "name": "Support Agent"},
    {"agent_id": "agent-456", "name": "Sales Agent"}
  ]
}

2. Create a Key with Agent Permissions

1. Go to Keys → Create Key
2. Expand Agent Settings
3. Select the agents you want to allow

curl -X POST "http://localhost:4000/key/generate" \\
  -H "Authorization: Bearer sk-master-key" \\
  -H "Content-Type: application/json" \\
  -d '{
    "object_permission": {
      "agents": ["agent-123"]
    }
  }'

3. Test Access

Allowed agent (succeeds):

curl -X POST "http://localhost:4000/a2a/agent-123" \\
  -H "Authorization: Bearer sk-your-new-key" \\
  -H "Content-Type: application/json" \\
  -d '{"message": {"role": "user", "parts": [{"type": "text", "text": "Hello"}]}}'

Blocked agent (fails with 403):

curl -X POST "http://localhost:4000/a2a/agent-456" \\
  -H "Authorization: Bearer sk-your-new-key" \\
  -H "Content-Type: application/json" \\
  -d '{"message": {"role": "user", "parts": [{"type": "text", "text": "Hello"}]}}'

Response:

{
  "error": {
    "message": "Access denied to agent: agent-456",
    "code": 403
  }
}

Setting Permissions on a Team

Restrict all keys belonging to a team to only access specific agents.

1. Create a Team with Agent Permissions

1. Go to Teams → Create Team
2. Expand Agent Settings
3. Select the agents you want to allow for this team

curl -X POST "http://localhost:4000/team/new" \\
  -H "Authorization: Bearer sk-master-key" \\
  -H "Content-Type: application/json" \\
  -d '{
    "team_alias": "support-team",
    "object_permission": {
      "agents": ["agent-123"]
    }
  }'

Response:

{
  "team_id": "team-abc-123",
  "team_alias": "support-team"
}

2. Create a Key for the Team

1. Go to Keys → Create Key
2. Select the Team from the dropdown

curl -X POST "http://localhost:4000/key/generate" \\
  -H "Authorization: Bearer sk-master-key" \\
  -H "Content-Type: application/json" \\
  -d '{
    "team_id": "team-abc-123"
  }'

3. Test Access

The key inherits agent permissions from the team.

Allowed agent (succeeds):

curl -X POST "http://localhost:4000/a2a/agent-123" \\
  -H "Authorization: Bearer sk-team-key" \\
  -H "Content-Type: application/json" \\
  -d '{"message": {"role": "user", "parts": [{"type": "text", "text": "Hello"}]}}'

Blocked agent (fails with 403):

curl -X POST "http://localhost:4000/a2a/agent-456" \\
  -H "Authorization: Bearer sk-team-key" \\
  -H "Content-Type: application/json" \\
  -d '{"message": {"role": "user", "parts": [{"type": "text", "text": "Hello"}]}}'

How It Works

flowchart TD
    A[Request to invoke agent] --> B{LiteLLM Virtual Key has agent restrictions?}
    B -->|Yes| C{LiteLLM Team has agent restrictions?}
    B -->|No| D{LiteLLM Team has agent restrictions?}
    
    C -->|Yes| E[Use intersection of key + team permissions]
    C -->|No| F[Use key permissions only]
    
    D -->|Yes| G[Inherit team permissions]
    D -->|No| H[Allow ALL agents]
    
    E --> I{Agent in allowed list?}
    F --> I
    G --> I
    H --> J[Allow request]
    
    I -->|Yes| J
    I -->|No| K[Return 403 Forbidden]

Viewing Permissions

1. Go to Keys or Teams
2. Click into the key/team you want to view
3. Agent permissions are displayed in the info view

curl "http://localhost:4000/key/info?key=sk-your-key" \\
  -H "Authorization: Bearer sk-master-key"