Google AI Studio - Managed Agents

LiteLLM이 이제 Google AI Studio Managed Agents API를 지원해요. LiteLLM을 통해 사용자 지정 에이전트를 생성·관리·실행할 수 있죠.

출처: 문서

본문

개요 (Overview)

두 가지 구분되는 단계가 있어요:

사용자 지정 에이전트 생성: /v1beta/agents로 Gemini 측에 에이전트를 정의해요(이름, 기본 모델, 지시사항).
에이전트 실행: 이름 있는 에이전트를 만들고 나면, /interactions 요청의 agent 필드에 리소스 이름을 지정해 상호작용할 수 있어요.

LiteLLM은 에이전트를 자체 데이터베이스에 저장하지 않아요. 에이전트는 전적으로 Google 측에 존재해요. LiteLLM은 인증 + 라우팅 레이어일 뿐이에요.

빠른 시작 (Quick start)

Proxy:

환경에 Gemini API 키를 추가해 주세요:

export GEMINI_API_KEY="AIzaSy..."

최소 proxy_config.yaml:

general_settings:
  master_key: "sk-<your-litellm-master-key>"

environment_variables:
  GEMINI_API_KEY: "AIzaSy..."   # or set in shell env

프록시 시작:

litellm --config proxy_config.yaml

GEMINI_API_KEY가 설정되어 있지 않으면 모든 관리형 에이전트 호출이 Google의 인증 오류로 실패해요.

SDK:

import os
import litellm

os.environ["GEMINI_API_KEY"] = "AIzaSy..."

환경 변수 대신 각 호출에 api_key="AIzaSy..."를 전달할 수도 있어요.

1. 에이전트 생성 (Create an agent)

Proxy:

curl -X POST "http://localhost:4000/v1beta/agents" \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-custom-slides-agent",
    "base_agent": "antigravity-preview-05-2026",
    "instructions": "You are a helpful assistant that creates slides.",
    "base_environment": {"env_id": "YOUR_ENVIRONMENT_ID"}
}'

응답:

{
  "id": "my-slides-agent",
  "base_agent": "antigravity-preview-05-2026",
  "system_instruction": "You are a helpful assistant that creates slides."
}

SDK:

response = litellm.interactions.agents.create(
    name="my-slides-agent",
    base_agent="antigravity-preview-05-2026",
    instructions="You are a helpful assistant that creates slides.",
    custom_llm_provider="gemini",
    base_environment={"env_id": "YOUR_ENVIRONMENT_ID"}
)
print(response.id)  # "my-slides-agent"

비동기 변형: litellm.interactions.agents.acreate(...).

파라미터 (Parameters):

필드	필수	설명
`name`	예	고유한 에이전트 식별자. 이후 호출에서 ID로 사용
`base_agent`	예	기반이 되는 기본 모델. 현재 Google이 `"antigravity-preview-05-2026"`만 지원
`instructions`	아니오	에이전트를 위한 시스템 레벨 지시사항
`base_environment`	아니오	환경 구성(예: GCS 스킬 소스)

같은 name으로 create를 두 번 호출하면 Google이 409 Conflict를 반환해요.

2. 에이전트 실행 (Run an agent)

Proxy:

curl -X POST "http://localhost:4000/v1beta/interactions" \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "my-slides-agent",
    "input": "Create a slide deck on the Fibonacci sequence",
    "environment": "remote" # required for agents
  }'

SDK:

response = litellm.interactions.create(
    agent="my-slides-agent",
    input="Create a slide deck on the Fibonacci sequence",
    environment="remote"
)
print(response)

비동기 변형: litellm.interactions.acreate(...).

참고: model이 아니라 agent를 전달하세요. 에이전트 이름은 LiteLLM 모델이 아니므로 model 필드에 넣으면 안 돼요.

전체 Interactions API는 /interactions를 참고해 주세요.

에이전트 관리 (Manage agents)

에이전트 목록 (List agents)

Proxy:

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

응답:

{
    "agents": [
        {
            "id": "my-custom-slides-agent"
        },
        {
            "id": "my-custom-slides-agent-1"
        }
    ]
}

SDK:

agents = litellm.interactions.agents.list()

에이전트 가져오기 (Get an agent)

Proxy:

curl "http://localhost:4000/v1beta/agents/my-slides-agent" \
  -H "Authorization: Bearer ***"

응답:

{
    "id": "my-custom-slides-agent",
    "base_agent": "antigravity-preview-05-2026",
    "system_instruction": "You are a helpful assistant that creates slides.",
    "base_environment": {
        "sources": [
            {
                "type": "gcs",
                "source": "gs://eap-templates/slides-skill",
                "target": "/.agents/skills/slides-skill"
            }
        ],
        "type": "remote"
    }
}

SDK:

agent = litellm.interactions.agents.get(
    name="my-slides-agent"
)

에이전트 삭제 (Delete an agent)

Proxy:

curl -X DELETE "http://localhost:4000/v1beta/agents/my-slides-agent" \
  -H "Authorization: Bearer ***"

SDK:

litellm.interactions.agents.delete(
    name="my-slides-agent",
    custom_llm_provider="gemini",
)

에이전트 버전 목록 (List agent versions)

Proxy:

curl "http://localhost:4000/v1beta/agents/my-slides-agent/versions" \
  -H "Authorization: Bearer ***"

응답:

{
    "agentVersions": [
        {
            "agent": "antigravity-preview-05-2026",
            "base_environment": {
                "env_id": "sdsdd"
            },
            "instructions": "You are a helpful assistant that creates slides",
            "name": "agents/my-custom-slides-agent-1/versions/a7616fd3-4e3e-48e7-aea7-9ac76b4f37ab"
        }
    ]
}

SDK:

versions = litellm.interactions.agents.list_versions(
    name="my-slides-agent",
    custom_llm_provider="gemini",
)

인증 (Authentication)

방법	키 제공 방법
Proxy	프록시 환경에 `GEMINI_API_KEY`(또는 `GOOGLE_API_KEY`) 설정. 가상 키(`sk-...`)는 사용자를 프록시에 인증하고, 프록시가 Gemini 키로 Google에 접속해요.
SDK	환경에 `GEMINI_API_KEY`를 설정하거나 각 호출에 `api_key="AIzaSy..."`를 전달.

Google AI Studio 외 다른 프로바이더로 관리형 에이전트를 사용할 방법은 없어요. 이 API는 다른 프로바이더를 지원하지 않아요.

제한 사항 (Limitations)

base_agent는 "antigravity-preview-05-2026"만 받아요(Google의 현재 제한).
에이전트는 Google 측에만 저장돼요. LiteLLM은 자체 데이터베이스에 저장하지 않아요. Google API로 에이전트를 직접 삭제하면 프록시가 알지 못해요.
agent 파라미터로 Interactions API를 사용하는 것은 현재 Gemini만 지원해요. 다른 프로바이더 모델을 호출하려면 model 파라미터를 사용하세요.
GEMINI_API_KEY / GOOGLE_API_KEY가 프록시 환경에 있어야 해요. api_key로 요청별 키를 전달하는 것은 SDK에서 지원하지만 현재 프록시 엔드포인트에서는 지원되지 않아요.

태그 (Tags)

gemini managed-agents interactions google-ai-studio agents litellm-proxy

더 알아보기 (Learn more)

Interactions API — 전체 Interactions 엔드포인트
Google AI Studio Managed Agents — 관리형 에이전트 문서