Google AI Studio Managed Agents on LiteLLM
LiteLLM now supports the Google AI Studio Managed Agents API. Create, manage, and run custom agents through LiteLLM.
Available from LiteLLM v1.87.0-dev.1 or above.
Deploy this version
- Docker
- Pip
docker run \
-e STORE_MODEL_IN_DB=True \
-p 4000:4000 \
ghcr.io/berriai/litellm:v1.87.0-dev.1
pip install litellm==1.87.0.dev1
Overview
There are two distinct steps:
- Create a custom agent: /v1beta/agents defines your agent on the Gemini side (name, base model, instructions).
- Run the agent: Once you have created a named agent, you can interact with it by specifying its resource name in the agent field of the /interactions request.
LiteLLM does not store the agent in its own database. The agent lives entirely on Google's side. LiteLLM is just the auth + routing layer.
Quick start
- Proxy
- SDK
Add your Gemini API key to the environment:
export GEMINI_API_KEY="AIzaSy..."
Minimal proxy_config.yaml:
general_settings:
master_key: "sk-<your-litellm-master-key>"
environment_variables:
GEMINI_API_KEY: "AIzaSy..." # or set in shell env
Start the proxy:
litellm --config proxy_config.yaml
If GEMINI_API_KEY is not set, all managed-agent calls will fail with an auth error from Google.
import os
import litellm
os.environ["GEMINI_API_KEY"] = "AIzaSy..."
You can also pass api_key="AIzaSy..." to each call instead of setting the environment variable.
1. Create an agent
- Proxy
- SDK
curl -X POST "http://localhost:4000/v1beta/agents" \
-H "Authorization: Bearer $LITELLM_API_KEY" \
-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"}
}'
Response:
{
"id": "my-slides-agent",
"base_agent": "antigravity-preview-05-2026",
"system_instruction": "You are a helpful assistant that creates slides."
}
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"
Async variant: litellm.interactions.agents.acreate(...).
Parameters:
| Field | Required | Description |
|---|---|---|
name | Yes | Unique agent identifier, used as the ID in later calls |
base_agent | Yes | Base model to build on. Currently only "antigravity-preview-05-2026" is supported by Google |
instructions | No | System-level instructions for the agent |
base_environment | No | Environment config (e.g. GCS skill sources) |
Calling create twice with the same
namereturns a409 Conflictfrom Google.
2. Run an agent
- Proxy
- SDK
curl -X POST "http://localhost:4000/v1beta/interactions" \
-H "Authorization: Bearer $LITELLM_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"agent": "my-slides-agent",
"input": "Create a slide deck on the Fibonacci sequence",
"environment": "remote" # required for agents
}'
response = litellm.interactions.create(
agent="my-slides-agent",
input="Create a slide deck on the Fibonacci sequence",
environment="remote"
)
print(response)
Async variant: litellm.interactions.acreate(...).
Note: pass agent, not model. The agent name is not a LiteLLM model, do not put it in the model field.
See also: /interactions for the full Interactions API.
Manage agents
List agents
- Proxy
- SDK
curl "http://localhost:4000/v1beta/agents" \
-H "Authorization: Bearer $LITELLM_API_KEY"
Response
{
"agents": [
{
"id": "my-custom-slides-agent"
},
{
"id": "my-custom-slides-agent-1"
}
]
}
agents = litellm.interactions.agents.list()
Get an agent
- Proxy
- SDK
curl "http://localhost:4000/v1beta/agents/my-slides-agent" \
-H "Authorization: Bearer $LITELLM_API_KEY"
Response
{
"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"
}
}
agent = litellm.interactions.agents.get(
name="my-slides-agent"
)
Delete an agent
- Proxy
- SDK
curl -X DELETE "http://localhost:4000/v1beta/agents/my-slides-agent" \
-H "Authorization: Bearer $LITELLM_API_KEY"
litellm.interactions.agents.delete(
name="my-slides-agent",
custom_llm_provider="gemini",
)
List agent versions
- Proxy
- SDK
curl "http://localhost:4000/v1beta/agents/my-slides-agent/versions" \
-H "Authorization: Bearer $LITELLM_API_KEY"
Response
{
"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"
}
]
}
versions = litellm.interactions.agents.list_versions(
name="my-slides-agent",
custom_llm_provider="gemini",
)
Authentication
| Method | How to provide the key |
|---|---|
| Proxy | Set GEMINI_API_KEY (or GOOGLE_API_KEY) in the proxy's environment. Virtual keys (sk-...) authenticate users to the proxy; the proxy uses your Gemini key to talk to Google. |
| SDK | Set GEMINI_API_KEY in the environment, or pass api_key="AIzaSy..." to each call. |
There is no way to use managed agents with any provider other than Google AI Studio. Other providers are not supported by this API.
Limitations
base_agentonly accepts"antigravity-preview-05-2026"(Google's current restriction).- Agents are stored on Google's side only. LiteLLM does not persist them in its database. If you delete an agent via Google's API directly, the proxy will not know.
- When this post was written, the Interactions API
agentparam was only supported by Gemini. It now also works on Vertex AI, see Deep Research on Vertex AI. Use themodelparam to call other providers' models. GEMINI_API_KEY/GOOGLE_API_KEYmust be present in the proxy environment. Passing the key per-request viaapi_keyis supported in the SDK but not currently via the proxy endpoint.


