에이전트 권한 관리

LiteLLM에서 특정 키나 팀이 접근할 수 있는 A2A 에이전트를 제어해요.

개요

에이전트 권한 관리는 LiteLLM Virtual Key 또는 팀이 접근할 수 있는 에이전트를 제한할 수 있게 해줍니다. 다음과 같은 경우에 유용해요:

멀티 테넌트 환경: 서로 다른 팀에게 서로 다른 에이전트에 대한 접근 권한 부여
보안: 키가 접근하면 안 되는 에이전트를 호출하지 못하게 방지
컴플라이언스: 민감한 에이전트 워크플로에 대한 접근 정책 강제

권한이 설정되면:

GET /v1/agents는 키/팀이 접근할 수 있는 에이전트만 반환
POST /a2a/{agent_id} (에이전트 호출)는 접근이 거부되면 403 Forbidden 반환

출처: 문서

본문

키에 권한 설정하기

이 예시는 에이전트 권한이 있는 키를 만들고 접근을 테스트하는 방법을 보여줘요.

1. 에이전트 ID 가져오기

사이드바에서 Agents 로 이동
원하는 에이전트를 클릭
Agent ID 를 복사

curl "http://localhost:4000/v1/agents" \
  -H "Authorization: Bearer ***"

응답:

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

2. 에이전트 권한이 있는 키 생성

Keys → Create Key 로 이동
Agent Settings 를 확장
허용할 에이전트를 선택

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

3. 접근 테스트

허용된 에이전트 (성공):

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

차단된 에이전트 (403으로 실패):

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

응답:

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

팀에 권한 설정하기

팀에 속한 모든 키가 특정 에이전트에만 접근하도록 제한해요.

1. 에이전트 권한이 있는 팀 만들기

Teams → Create Team 으로 이동
Agent Settings 를 확장
이 팀에 허용할 에이전트를 선택

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

응답:

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

2. 팀용 키 생성

Keys → Create Key 로 이동
드롭다운에서 팀을 선택

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

3. 접근 테스트

키는 팀으로부터 에이전트 권한을 상속받아요.

허용된 에이전트 (성공):

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

차단된 에이전트 (403으로 실패):

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

에이전트 접근 그룹

에이전트 카탈로그가 커질수록 개별 에이전트를 매 키/팀에 부여하는 것은 번거로워져요. 에이전트 접근 그룹을 사용하면 대시보드에서 에이전트에 논리적 레이블을 태그하고, 해당 그룹을 키나 팀에 부여할 수 있어요. 그룹에 새 에이전트를 추가하면 해당 그룹을 가진 모든 키/팀이 자동으로 사용할 수 있게 됩니다.

1. 에이전트에 하나 이상의 그룹 태그

LiteLLM 대시보드에서:

Agents 로 이동합니다.
에이전트를 만들거나 편집합니다.
Access Groups 아래에 그룹 이름(예: clinical-tools)을 입력하고 Enter를 누릅니다.

에이전트에 접근 그룹을 태그하는 것은 현재 대시보드 전용 작업이에요. POST /v1/agents body 스키마는 agent_access_groups를 top-level 필드로 노출하지 않습니다. 그룹 태그는 기본 DB 컬럼을 통해 유지되고, 권한 해석 중에 사용됩니다.

2. 키 또는 팀에 그룹 부여

curl -X POST "http://localhost:4000/key/generate" \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{
    "object_permission": {
      "agent_access_groups": ["clinical-tools", "research-tools"]
    }
  }'

이제 키는 두 그룹 중 하나로 태그된 모든 에이전트에 접근할 수 있으며, 에이전트별 나열이 필요 없어요. 같은 agent_access_groups 필드는 팀의 object_permission에서도 유효합니다.

키가 직접 agents 목록과 agent_access_groups를 모두 가지면 합집합이 계산되고(어느 경로로든 도달 가능한 에이전트는 허용), 그다음 아래 설명처럼 팀 수준 교집합이 적용돼요.

동작 방식

A2A 권한 해석은 Key와 Team 두 수준에서 이뤄집니다. (MCP의 권한 계층은 End-user / Agent / Org로도 확장되지만, 에이전트 권한은 현재 더 좁은 모델이에요.)

키 권한	팀 권한	결과	참고
없음	없음	키는 모든 에이전트 접근 가능	제한이 없으면 기본적으로 개방 접근
`["agent-1", "agent-2"]`	없음	키는 agent-1, agent-2 접근 가능	키는 자체 권한 사용
없음	`["agent-1", "agent-3"]`	키는 agent-1, agent-3 접근 가능	키는 팀의 권한 상속
`["agent-1", "agent-2"]`	`["agent-1", "agent-3"]`	키는 agent-1만 접근 가능	양쪽 목록의 교집합 (더 제한적인 쪽이 우선)
`agent_access_groups: ["clinical"]`	없음	키는 `clinical`로 태그된 모든 에이전트 접근 가능	접근 그룹이 구체적 에이전트 ID로 해석됨
`agent_access_groups: ["clinical"]`	`agents: ["agent-1"]`	(`clinical`로 태그된 모든 에이전트)와 `["agent-1"]`의 교집합	직접 + 그룹 부여 혼합 지원

권한 보기

Keys 또는 Teams 로 이동
확인하려는 키/팀을 클릭
에이전트 권한이 정보 뷰에 표시됩니다

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

에이전트 권한 관리