Gemini Agents API  |  Gemini API  |  Google AI for Developers
Skip to main content
/
English
Deutsch
Español – América Latina
Français
Indonesia
Italiano
Polski
Português – Brasil
Shqip
Tiếng Việt
Türkçe
Русский
עברית
العربيّة
فارسی
हिंदी
বাংলা
ภาษาไทย
中文 – 简体
中文 – 繁體
日本語
한국어
Get API key
Cookbook
Community
Sign in
Docs
API reference
Gemini API
Docs
API reference
Get API key
Cookbook
Community
Overview
API versions
Core APIs
Interactions API
GenerateContent
Real time APIs
Live API
Live Music API
Platform APIs
Model API
Agents
Webhooks
Triggers
Batch API
Files API
Tokens
Caching
Embeddings
File Search API
File search stores
Documents
All methods
SDK references
Python
Go
TypeScript
Java
C#
The Interactions API is now generally available. We recommend using this API for access to all the latest features and models.
Home
Gemini API
API reference
Send feedback
Gemini Agents API
Beta: This API is in Beta. Endpoints are under /v1beta/.
Agents are systems that leverage Gemini models, a set of tools, and reasoning capabilities to perform complex, multi-step tasks and achieve specific goals. Unlike a single model call, an agent can plan, execute a series of actions, interact with external systems, and synthesize information to fulfill a user's request.
View as markdown
View the OpenAPI Spec
CreateAgent
post
https://generativelanguage.googleapis.com/v1beta/agents
Creates a new Agent (Typed version for SDK).
Request body
Response
Request body
The request body contains data with the following structure:
base_agent
string
 (optional)
The base agent to extend.
base_environment
EnvironmentConfig
 (optional)
The environment configuration for the agent.
Configuration for a custom environment.
Fields
environment_id
string
 (optional)
Optional. The environment ID for the interaction. If specified, the request will
update the existing environment instead of creating a new one.
network
EnvironmentNetworkEgressAllowlist
 (optional)
Network configuration for the environment.
Outbound networking configuration for the sandbox. Accepts an object with an 'allowlist' array to restrict traffic, or the string 'disabled' to turn off all network access. Omit entirely to allow all outbound traffic with no header injection.
Possible Types
object
Outbound networking configuration for the sandbox. When specified, restricts which external domains the sandbox can reach. Omit entirely to allow all outbound traffic with no header injection.
allowlist
AllowlistEntry
 (optional)
List of allowed outbound domains. Only requests to listed domains are permitted. Use [{'domain': '*'}] to allow all domains while still injecting headers on specific ones.
A single domain allowlist rule with optional header injection.
Fields
domain
string
 (optional)
Domain to allow outbound requests to. Supports wildcards (e.g. '*.googleapis.com'). Use '*' to allow all domains.
transform
array (object) or object
 (optional)
Headers to inject on all outbound requests matching this domain. Accepts a single dict or a list of dicts. The egress proxy injects these automatically.
string
Turns all network off.
Possible values
disabled
Turns all network off.
sources
Source
 (optional)
No description provided.
A source to be mounted into the environment.
Fields
content
string
 (optional)
The inline content if `type` is `INLINE`.
encoding
string
 (optional)
Optional encoding for inline content (e.g. `base64`).
source
string
 (optional)
The source of the environment.
For GCS, this is the GCS path.
For GitHub, this is the GitHub path.
target
string
 (optional)
Where the source should appear in the environment.
type
enum (string)
 (optional)
No description provided.
Possible
values:
gcs
A GCS bucket.
inline
Inline content.
repository
A generic repository. The protocol prefix in the source URL
identifies the provider (e.g., github://, gcs://).
skill_registry
A skill resource from the Skill Registry Service.
Skill: projects/{project}/locations/{location}/skills/{skill}
SkillRevision:
projects/{project}/locations/{location}/skills/{skill}/revisions/{revision}
Support mounting all skills under a project:
projects/{project}/locations/{location}/skills.
type
object
 (optional)
No description provided.
Always set to "remote".
description
string
 (optional)
Agent description for developers to quickly read and understand.
id
string
 (optional)
The unique identifier for the agent.
system_instruction
string
 (optional)
System instruction for the agent.
tools
AgentTool
 (optional)
The tools available to the agent.
A tool that the agent can use.
Possible Types
Polymorphic discriminator: type
CodeExecution
A tool that can be used by the model to execute code.
type
object
 (required)
No description provided.
Always set to "code_execution".
GoogleSearch
A tool that can be used by the model to search Google.
search_types
array (enum (string))
 (optional)
The types of search grounding to enable.
Possible
values:
web_search
Setting this field enables web search. Only text results are returned.
image_search
Setting this field enables image search. Image bytes are returned.
enterprise_web_search
Setting this field enables enterprise web search.
type
object
 (required)
No description provided.
Always set to "google_search".
UrlContext
A tool that can be used by the model to fetch URL context.
type
object
 (required)
No description provided.
Always set to "url_context".
McpServer
A MCPServer is a server that can be called by the model to perform actions.
allowed_tools
AllowedTools
 (optional)
The allowed tools.
The configuration for allowed tools.
Fields
mode
enum (string)
 (optional)
The mode of the tool choice.
Possible
values:
auto
Auto tool choice.
any
Any tool choice.
none
No tool choice.
validated
Validated tool choice.
tools
array (string)
 (optional)
The names of the allowed tools.
headers
object
 (optional)
Optional: Fields for authentication headers, timeouts, etc., if needed.
name
string
 (optional)
The name of the MCPServer.
type
object
 (required)
No description provided.
Always set to "mcp_server".
url
string
 (optional)
The full URL for the MCPServer endpoint.
Example: "https://api.example.com/mcp"
Function
A tool that can be used by the model.
description
string
 (optional)
A description of the function.
name
string
 (optional)
The name of the function.
parameters
object
 (optional)
The JSON Schema for the function's parameters.
type
object
 (required)
No description provided.
Always set to "function".
Response
If successful, the response body contains data with the following structure:
base_agent
string
 (optional)
The base agent to extend.
base_environment
EnvironmentConfig
 (optional)
The environment configuration for the agent.
Configuration for a custom environment.
Fields
environment_id
string
 (optional)
Optional. The environment ID for the interaction. If specified, the request will
update the existing environment instead of creating a new one.
network
EnvironmentNetworkEgressAllowlist
 (optional)
Network configuration for the environment.
Outbound networking configuration for the sandbox. Accepts an object with an 'allowlist' array to restrict traffic, or the string 'disabled' to turn off all network access. Omit entirely to allow all outbound traffic with no header injection.
Possible Types
object
Outbound networking configuration for the sandbox. When specified, restricts which external domains the sandbox can reach. Omit entirely to allow all outbound traffic with no header injection.
allowlist
AllowlistEntry
 (optional)
List of allowed outbound domains. Only requests to listed domains are permitted. Use [{'domain': '*'}] to allow all domains while still injecting headers on specific ones.
A single domain allowlist rule with optional header injection.
Fields
domain
string
 (optional)
Domain to allow outbound requests to. Supports wildcards (e.g. '*.googleapis.com'). Use '*' to allow all domains.
transform
array (object) or object
 (optional)
Headers to inject on all outbound requests matching this domain. Accepts a single dict or a list of dicts. The egress proxy injects these automatically.
string
Turns all network off.
Possible values
disabled
Turns all network off.
sources
Source
 (optional)
No description provided.
A source to be mounted into the environment.
Fields
content
string
 (optional)
The inline content if `type` is `INLINE`.
encoding
string
 (optional)
Optional encoding for inline content (e.g. `base64`).
source
string
 (optional)
The source of the environment.
For GCS, this is the GCS path.
For GitHub, this is the GitHub path.
target
string
 (optional)
Where the source should appear in the environment.
type
enum (string)
 (optional)
No description provided.
Possible
values:
gcs
A GCS bucket.
inline
Inline content.
repository
A generic repository. The protocol prefix in the source URL
identifies the provider (e.g., github://, gcs://).
skill_registry
A skill resource from the Skill Registry Service.
Skill: projects/{project}/locations/{location}/skills/{skill}
SkillRevision:
projects/{project}/locations/{location}/skills/{skill}/revisions/{revision}
Support mounting all skills under a project:
projects/{project}/locations/{location}/skills.
type
object
 (optional)
No description provided.
Always set to "remote".
description
string
 (optional)
Agent description for developers to quickly read and understand.
id
string
 (optional)
The unique identifier for the agent.
system_instruction
string
 (optional)
System instruction for the agent.
tools
AgentTool
 (optional)
The tools available to the agent.
A tool that the agent can use.
Possible Types
Polymorphic discriminator: type
CodeExecution
A tool that can be used by the model to execute code.
type
object
 (required)
No description provided.
Always set to "code_execution".
GoogleSearch
A tool that can be used by the model to search Google.
search_types
array (enum (string))
 (optional)
The types of search grounding to enable.
Possible
values:
web_search
Setting this field enables web search. Only text results are returned.
image_search
Setting this field enables image search. Image bytes are returned.
enterprise_web_search
Setting this field enables enterprise web search.
type
object
 (required)
No description provided.
Always set to "google_search".
UrlContext
A tool that can be used by the model to fetch URL context.
type
object
 (required)
No description provided.
Always set to "url_context".
McpServer
A MCPServer is a server that can be called by the model to perform actions.
allowed_tools
AllowedTools
 (optional)
The allowed tools.
The configuration for allowed tools.
Fields
mode
enum (string)
 (optional)
The mode of the tool choice.
Possible
values:
auto
Auto tool choice.
any
Any tool choice.
none
No tool choice.
validated
Validated tool choice.
tools
array (string)
 (optional)
The names of the allowed tools.
headers
object
 (optional)
Optional: Fields for authentication headers, timeouts, etc., if needed.
name
string
 (optional)
The name of the MCPServer.
type
object
 (required)
No description provided.
Always set to "mcp_server".
url
string
 (optional)
The full URL for the MCPServer endpoint.
Example: "https://api.example.com/mcp"
Function
A tool that can be used by the model.
description
string
 (optional)
A description of the function.
name
string
 (optional)
The name of the function.
parameters
object
 (optional)
The JSON Schema for the function's parameters.
type
object
 (required)
No description provided.
Always set to "function".
Create Agent
Example Response
{
"id": "ag_abc123",
"display_name": "My Research Agent",
"system_instruction": "You are a helpful research assistant.",
"tools": [
{
"type": "google_search"
}
],
"object": "agent",
"created": "2025-11-26T12:25:15Z",
"updated": "2025-11-26T12:25:15Z"
}
Agent with Sources
Example Response
{
"id": "data-analyst-abc123",
"system_instruction": "You are a data analyst. Always include visualizations and export results as PDF.",
"object": "agent",
"created": "2025-11-26T12:25:15Z",
"updated": "2025-11-26T12:25:15Z"
}
Agent Forked from Environment
Example Response
{
"id": "my-data-analyst",
"system_instruction": "You are a data analyst. Use the template at /workspace/template.py for all reports.",
"object": "agent",
"created": "2025-11-26T12:25:15Z",
"updated": "2025-11-26T12:25:15Z"
}
ListAgents
get
https://generativelanguage.googleapis.com/v1beta/agents
Lists all Agents.
Path / Query parameters
Response
Path / Query Parameters
page_size
integer
 (optional)
No description provided.
page_token
string
 (optional)
No description provided.
parent
string
 (optional)
No description provided.
Response
If successful, the response body contains data with the following structure:
agents
array (Agent)
 (optional)
No description provided.
next_page_token
string
 (optional)
No description provided.
List Agents
Example Response
{
"object": "list",
"data": [
{
"id": "ag_abc123",
"display_name": "My Research Agent",
"system_instruction": "You are a helpful research assistant.",
"object": "agent",
"created": "2025-11-26T12:25:15Z",
"updated": "2025-11-26T12:25:15Z"
}
]
}
GetAgent
get
https://generativelanguage.googleapis.com/v1beta/agents/{id}
Gets a specific Agent.
Path / Query parameters
Response
Path / Query Parameters
id
string
 (required)
No description provided.
Response
If successful, the response body contains data with the following structure:
base_agent
string
 (optional)
The base agent to extend.
base_environment
EnvironmentConfig
 (optional)
The environment configuration for the agent.
Configuration for a custom environment.
Fields
environment_id
string
 (optional)
Optional. The environment ID for the interaction. If specified, the request will
update the existing environment instead of creating a new one.
network
EnvironmentNetworkEgressAllowlist
 (optional)
Network configuration for the environment.
Outbound networking configuration for the sandbox. Accepts an object with an 'allowlist' array to restrict traffic, or the string 'disabled' to turn off all network access. Omit entirely to allow all outbound traffic with no header injection.
Possible Types
object
Outbound networking configuration for the sandbox. When specified, restricts which external domains the sandbox can reach. Omit entirely to allow all outbound traffic with no header injection.
allowlist
AllowlistEntry
 (optional)
List of allowed outbound domains. Only requests to listed domains are permitted. Use [{'domain': '*'}] to allow all domains while still injecting headers on specific ones.
A single domain allowlist rule with optional header injection.
Fields
domain
string
 (optional)
Domain to allow outbound requests to. Supports wildcards (e.g. '*.googleapis.com'). Use '*' to allow all domains.
transform
array (object) or object
 (optional)
Headers to inject on all outbound requests matching this domain. Accepts a single dict or a list of dicts. The egress proxy injects these automatically.
string
Turns all network off.
Possible values
disabled
Turns all network off.
sources
Source
 (optional)
No description provided.
A source to be mounted into the environment.
Fields
content
string
 (optional)
The inline content if `type` is `INLINE`.
encoding
string
 (optional)
Optional encoding for inline content (e.g. `base64`).
source
string
 (optional)
The source of the environment.
For GCS, this is the GCS path.
For GitHub, this is the GitHub path.
target
string
 (optional)
Where the source should appear in the environment.
type
enum (string)
 (optional)
No description provided.
Possible
values:
gcs
A GCS bucket.
inline
Inline content.
repository
A generic repository. The protocol prefix in the source URL
identifies the provider (e.g., github://, gcs://).
skill_registry
A skill resource from the Skill Registry Service.
Skill: projects/{project}/locations/{location}/skills/{skill}
SkillRevision:
projects/{project}/locations/{location}/skills/{skill}/revisions/{revision}
Support mounting all skills under a project:
projects/{project}/locations/{location}/skills.
type
object
 (optional)
No description provided.
Always set to "remote".
description
string
 (optional)
Agent description for developers to quickly read and understand.
id
string
 (optional)
The unique identifier for the agent.
system_instruction
string
 (optional)
System instruction for the agent.
tools
AgentTool
 (optional)
The tools available to the agent.
A tool that the agent can use.
Possible Types
Polymorphic discriminator: type
CodeExecution
A tool that can be used by the model to execute code.
type
object
 (required)
No description provided.
Always set to "code_execution".
GoogleSearch
A tool that can be used by the model to search Google.
search_types
array (enum (string))
 (optional)
The types of search grounding to enable.
Possible
values:
web_search
Setting this field enables web search. Only text results are returned.
image_search
Setting this field enables image search. Image bytes are returned.
enterprise_web_search
Setting this field enables enterprise web search.
type
object
 (required)
No description provided.
Always set to "google_search".
UrlContext
A tool that can be used by the model to fetch URL context.
type
object
 (required)
No description provided.
Always set to "url_context".
McpServer
A MCPServer is a server that can be called by the model to perform actions.
allowed_tools
AllowedTools
 (optional)
The allowed tools.
The configuration for allowed tools.
Fields
mode
enum (string)
 (optional)
The mode of the tool choice.
Possible
values:
auto
Auto tool choice.
any
Any tool choice.
none
No tool choice.
validated
Validated tool choice.
tools
array (string)
 (optional)
The names of the allowed tools.
headers
object
 (optional)
Optional: Fields for authentication headers, timeouts, etc., if needed.
name
string
 (optional)
The name of the MCPServer.
type
object
 (required)
No description provided.
Always set to "mcp_server".
url
string
 (optional)
The full URL for the MCPServer endpoint.
Example: "https://api.example.com/mcp"
Function
A tool that can be used by the model.
description
string
 (optional)
A description of the function.
name
string
 (optional)
The name of the function.
parameters
object
 (optional)
The JSON Schema for the function's parameters.
type
object
 (required)
No description provided.
Always set to "function".
Get Agent
Example Response
{
"id": "ag_abc123",
"display_name": "My Research Agent",
"system_instruction": "You are a helpful research assistant.",
"tools": [
{
"type": "google_search"
}
],
"object": "agent",
"created": "2025-11-26T12:25:15Z",
"updated": "2025-11-26T12:25:15Z"
}
DeleteAgent
delete
https://generativelanguage.googleapis.com/v1beta/agents/{id}
Deletes an Agent.
Path / Query parameters
Response
Path / Query Parameters
id
string
 (required)
No description provided.
Response
If successful, the response is empty.
Delete Agent
Resources
Agent
An agent definition for the CreateAgent API.
This message is the target for annotation-parser-based JSON parsing.
New format:
{
"id": "customer-sentinel",
"base_agent": "",
"system_instruction": "...",
"base_environment": { "type": "remote", "sources": [...] },
"tools": [ {"type": "code_execution"} ]
}
Fields
base_agent
string
 (optional)
The base agent to extend.
base_environment
EnvironmentConfig
 (optional)
The environment configuration for the agent.
Configuration for a custom environment.
Fields
environment_id
string
 (optional)
Optional. The environment ID for the interaction. If specified, the request will
update the existing environment instead of creating a new one.
network
EnvironmentNetworkEgressAllowlist
 (optional)
Network configuration for the environment.
Outbound networking configuration for the sandbox. Accepts an object with an 'allowlist' array to restrict traffic, or the string 'disabled' to turn off all network access. Omit entirely to allow all outbound traffic with no header injection.
Possible Types
object
Outbound networking configuration for the sandbox. When specified, restricts which external domains the sandbox can reach. Omit entirely to allow all outbound traffic with no header injection.
allowlist
AllowlistEntry
 (optional)
List of allowed outbound domains. Only requests to listed domains are permitted. Use [{'domain': '*'}] to allow all domains while still injecting headers on specific ones.
A single domain allowlist rule with optional header injection.
Fields
domain
string
 (optional)
Domain to allow outbound requests to. Supports wildcards (e.g. '*.googleapis.com'). Use '*' to allow all domains.
transform
array (object) or object
 (optional)
Headers to inject on all outbound requests matching this domain. Accepts a single dict or a list of dicts. The egress proxy injects these automatically.
string
Turns all network off.
Possible values
disabled
Turns all network off.
sources
Source
 (optional)
No description provided.
A source to be mounted into the environment.
Fields
content
string
 (optional)
The inline content if `type` is `INLINE`.
encoding
string
 (optional)
Optional encoding for inline content (e.g. `base64`).
source
string
 (optional)
The source of the environment.
For GCS, this is the GCS path.
For GitHub, this is the GitHub path.
target
string
 (optional)
Where the source should appear in the environment.
type
enum (string)
 (optional)
No description provided.
Possible
values:
gcs
A GCS bucket.
inline
Inline content.
repository
A generic repository. The protocol prefix in the source URL
identifies the provider (e.g., github://, gcs://).
skill_registry
A skill resource from the Skill Registry Service.
Skill: projects/{project}/locations/{location}/skills/{skill}
SkillRevision:
projects/{project}/locations/{location}/skills/{skill}/revisions/{revision}
Support mounting all skills under a project:
projects/{project}/locations/{location}/skills.
type
object
 (optional)
No description provided.
Always set to "remote".
description
string
 (optional)
Agent description for developers to quickly read and understand.
id
string
 (optional)
The unique identifier for the agent.
system_instruction
string
 (optional)
System instruction for the agent.
tools
AgentTool
 (optional)
The tools available to the agent.
A tool that the agent can use.
Possible Types
Polymorphic discriminator: type
CodeExecution
A tool that can be used by the model to execute code.
type
object
 (required)
No description provided.
Always set to "code_execution".
GoogleSearch
A tool that can be used by the model to search Google.
search_types
array (enum (string))
 (optional)
The types of search grounding to enable.
Possible
values:
web_search
Setting this field enables web search. Only text results are returned.
image_search
Setting this field enables image search. Image bytes are returned.
enterprise_web_search
Setting this field enables enterprise web search.
type
object
 (required)
No description provided.
Always set to "google_search".
UrlContext
A tool that can be used by the model to fetch URL context.
type
object
 (required)
No description provided.
Always set to "url_context".
McpServer
A MCPServer is a server that can be called by the model to perform actions.
allowed_tools
AllowedTools
 (optional)
The allowed tools.
The configuration for allowed tools.
Fields
mode
enum (string)
 (optional)
The mode of the tool choice.
Possible
values:
auto
Auto tool choice.
any
Any tool choice.
none
No tool choice.
validated
Validated tool choice.
tools
array (string)
 (optional)
The names of the allowed tools.
headers
object
 (optional)
Optional: Fields for authentication headers, timeouts, etc., if needed.
name
string
 (optional)
The name of the MCPServer.
type
object
 (required)
No description provided.
Always set to "mcp_server".
url
string
 (optional)
The full URL for the MCPServer endpoint.
Example: "https://api.example.com/mcp"
Function
A tool that can be used by the model.
description
string
 (optional)
A description of the function.
name
string
 (optional)
The name of the function.
parameters
object
 (optional)
The JSON Schema for the function's parameters.
type
object
 (required)
No description provided.
Always set to "function".
Send feedback
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2026-07-15 UTC.
Need to tell us more?
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2026-07-15 UTC."],[],[]]
Terms
Privacy
Manage cookies
English
Deutsch
Español – América Latina
Français
Indonesia
Italiano
Polski
Português – Brasil
Shqip
Tiếng Việt
Türkçe
Русский
עברית
العربيّة
فارسی
हिंदी
বাংলা
ภาษาไทย
中文 – 简体
中文 – 繁體
日本語
한국어