diff --git a/docs/my-website/docs/a2a.md b/docs/my-website/docs/a2a.md index 05b147de7c..b4aa4ed03a 100644 --- a/docs/my-website/docs/a2a.md +++ b/docs/my-website/docs/a2a.md @@ -2,7 +2,17 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import Image from '@theme/IdealImage'; -# /a2a - Agent Gateway (A2A Protocol) +# Agent Gateway (A2A Protocol) - Overview + +Add A2A Agents on LiteLLM AI Gateway, Invoke agents in A2A Protocol, track request/response logs in LiteLLM Logs. Manage which Teams, Keys can access which Agents onboarded. + + + +
+
| Feature | Supported | |---------|-----------| diff --git a/docs/my-website/docs/a2a_agent_permissions.md b/docs/my-website/docs/a2a_agent_permissions.md new file mode 100644 index 0000000000..93f367f43e --- /dev/null +++ b/docs/my-website/docs/a2a_agent_permissions.md @@ -0,0 +1,259 @@ +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import Image from '@theme/IdealImage'; + +# 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** + + + + + + +```bash title="List all agents" showLineNumbers +curl "http://localhost:4000/v1/agents" \ + -H "Authorization: Bearer sk-master-key" +``` + +Response: +```json title="Response" showLineNumbers +{ + "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 + + + + + + +```bash title="Create key with agent permissions" showLineNumbers +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):** +```bash title="Invoke allowed agent" showLineNumbers +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):** +```bash title="Invoke blocked agent" showLineNumbers +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: +```json title="403 Forbidden Response" showLineNumbers +{ + "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 + + + + + + +```bash title="Create team with agent permissions" showLineNumbers +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: +```json title="Response" showLineNumbers +{ + "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 + + + + + + +```bash title="Create key for team" showLineNumbers +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):** +```bash title="Invoke allowed agent" showLineNumbers +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):** +```bash title="Invoke blocked agent" showLineNumbers +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 + +```mermaid +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] +``` + +| Key Permissions | Team Permissions | Result | Notes | +|-----------------|------------------|--------|-------| +| None | None | Key can access **all** agents | Open access by default when no restrictions are set | +| `["agent-1", "agent-2"]` | None | Key can access `agent-1` and `agent-2` | Key uses its own permissions | +| None | `["agent-1", "agent-3"]` | Key can access `agent-1` and `agent-3` | Key inherits team's permissions | +| `["agent-1", "agent-2"]` | `["agent-1", "agent-3"]` | Key can access `agent-1` only | Intersection of both lists (most restrictive wins) | + +## 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 + + + + +```bash title="Get key info" showLineNumbers +curl "http://localhost:4000/key/info?key=sk-your-key" \ + -H "Authorization: Bearer sk-master-key" +``` + + + diff --git a/docs/my-website/img/a2a_gateway.png b/docs/my-website/img/a2a_gateway.png new file mode 100644 index 0000000000..c53a9910d5 Binary files /dev/null and b/docs/my-website/img/a2a_gateway.png differ diff --git a/docs/my-website/img/agent_id.png b/docs/my-website/img/agent_id.png new file mode 100644 index 0000000000..d3b11907f2 Binary files /dev/null and b/docs/my-website/img/agent_id.png differ diff --git a/docs/my-website/img/agent_key.png b/docs/my-website/img/agent_key.png new file mode 100644 index 0000000000..7769e0edba Binary files /dev/null and b/docs/my-website/img/agent_key.png differ diff --git a/docs/my-website/img/agent_team.png b/docs/my-website/img/agent_team.png new file mode 100644 index 0000000000..0439e77202 Binary files /dev/null and b/docs/my-website/img/agent_team.png differ diff --git a/docs/my-website/sidebars.js b/docs/my-website/sidebars.js index c36e4141f4..faec93de1d 100644 --- a/docs/my-website/sidebars.js +++ b/docs/my-website/sidebars.js @@ -129,6 +129,16 @@ const sidebars = { }, items: [ "proxy/docker_quick_start", + { + type: "link", + label: "A2A Agent Gateway", + href: "https://docs.litellm.ai/docs/a2a", + }, + { + type: "link", + label: "MCP Gateway", + href: "https://docs.litellm.ai/docs/mcp", + }, { "type": "category", "label": "Config.yaml", @@ -317,7 +327,14 @@ const sidebars = { slug: "/supported_endpoints", }, items: [ - "a2a", + { + type: "category", + label: "/a2a - A2A Agent Gateway", + items: [ + "a2a", + "a2a_agent_permissions", + ], + }, "assistants", { type: "category",