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](https://ai.google.dev/static/api/agents.md.txt) [View the OpenAPI Spec](https://ai.google.dev/static/api/interactions.openapi.json)
> [!NOTE]
> This API is in Beta. Endpoints are under `/v1beta/`.
## CreateAgent
post https://generativelanguage.googleapis.com/v1beta/agents Creates a new Agent (Typed version for SDK).
- [Request body](https://ai.google.dev/api/agents#CreateAgent.request_body)
- [Response](https://ai.google.dev/api/agents#CreateAgent.response)
### Request body
The request body contains data with the following structure:
agent_config AntigravityAgentConfig (optional) Configuration parameters for the agent.
Configuration for the Antigravity agent runtime.
Provides server-side control over the agent's execution environment
and tool configuration.
#### Fields
max_total_tokens string (optional) Max total tokens for the agent run.
model string (optional) The model to use for agent reasoning.
type object (optional) No description provided.
Always set to `"antigravity"`.
base_agent string (optional) The base agent to extend.
base_environment EnvironmentConfig or string (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 or enum (string) (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 array (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 array (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 Cloud Storage, this is the Cloud Storage 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 Cloud Storage bucket.
- `inline`
Inline content.
- `repository`
A generic repository. The protocol prefix in the source URL
identifies the provider (e.g., github://, gcs://).
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 array (AgentTool) (optional) The tools available to the agent.
A tool that the agent can use.
#### Possible Types
CodeExecution A tool that can be used by the model to execute code.
type object (required) No description provided.
Always set to `"code_execution"`.
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"`.
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.
type object (required) No description provided.
Always set to `"google_search"`.
McpServer A MCPServer is a server that can be called by the model to perform actions.
allowed_tools array (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"
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"`.
### Response
If successful, the response body contains data with the following structure:
agent_config AntigravityAgentConfig (optional) Configuration parameters for the agent.
Configuration for the Antigravity agent runtime.
Provides server-side control over the agent's execution environment
and tool configuration.
#### Fields
max_total_tokens string (optional) Max total tokens for the agent run.
model string (optional) The model to use for agent reasoning.
type object (optional) No description provided.
Always set to `"antigravity"`.
base_agent string (optional) The base agent to extend.
base_environment EnvironmentConfig or string (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 or enum (string) (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 array (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 array (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 Cloud Storage, this is the Cloud Storage 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 Cloud Storage bucket.
- `inline`
Inline content.
- `repository`
A generic repository. The protocol prefix in the source URL
identifies the provider (e.g., github://, gcs://).
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 array (AgentTool) (optional) The tools available to the agent.
A tool that the agent can use.
#### Possible Types
CodeExecution A tool that can be used by the model to execute code.
type object (required) No description provided.
Always set to `"code_execution"`.
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"`.
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.
type object (required) No description provided.
Always set to `"google_search"`.
McpServer A MCPServer is a server that can be called by the model to perform actions.
allowed_tools array (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"
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"`.
### Create Agent
#### Example Response
```json
{
"created": "2025-11-26T12:25:15Z",
"display_name": "My Research Agent",
"id": "ag_abc123",
"object": "agent",
"system_instruction": "You are a helpful research assistant.",
"tools": [
{
"type": "google_search"
}
],
"updated": "2025-11-26T12:25:15Z"
}
```
### Agent with Sources
#### Example Response
```json
{
"created": "2025-11-26T12:25:15Z",
"id": "data-analyst-abc123",
"object": "agent",
"system_instruction": "You are a data analyst. Always include visualizations and export results as PDF.",
"updated": "2025-11-26T12:25:15Z"
}
```
### Agent Forked from Environment
#### Example Response
```json
{
"created": "2025-11-26T12:25:15Z",
"id": "my-data-analyst",
"object": "agent",
"system_instruction": "You are a data analyst. Use the template at /workspace/template.py for all reports.",
"updated": "2025-11-26T12:25:15Z"
}
```
## ListAgents
get https://generativelanguage.googleapis.com/v1beta/agents Lists all Agents.
- [Path / Query parameters](https://ai.google.dev/api/agents#ListAgents.PATH_PARAMETERS)
- [Response](https://ai.google.dev/api/agents#ListAgents.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](https://ai.google.dev/api/agents#Resource:Agent)) (optional) No description provided.
next_page_token string (optional) No description provided.
### List Agents
#### Example Response
```json
{
"data": [
{
"created": "2025-11-26T12:25:15Z",
"display_name": "My Research Agent",
"id": "ag_abc123",
"object": "agent",
"system_instruction": "You are a helpful research assistant.",
"updated": "2025-11-26T12:25:15Z"
}
],
"object": "list"
}
```
## GetAgent
get https://generativelanguage.googleapis.com/v1beta/agents/{id} Gets a specific Agent.
- [Path / Query parameters](https://ai.google.dev/api/agents#GetAgent.PATH_PARAMETERS)
- [Response](https://ai.google.dev/api/agents#GetAgent.response)
### Path / Query Parameters
id string (required) No description provided.
### Response
If successful, the response body contains data with the following structure:
agent_config AntigravityAgentConfig (optional) Configuration parameters for the agent.
Configuration for the Antigravity agent runtime.
Provides server-side control over the agent's execution environment
and tool configuration.
#### Fields
max_total_tokens string (optional) Max total tokens for the agent run.
model string (optional) The model to use for agent reasoning.
type object (optional) No description provided.
Always set to `"antigravity"`.
base_agent string (optional) The base agent to extend.
base_environment EnvironmentConfig or string (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 or enum (string) (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 array (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 array (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 Cloud Storage, this is the Cloud Storage 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 Cloud Storage bucket.
- `inline`
Inline content.
- `repository`
A generic repository. The protocol prefix in the source URL
identifies the provider (e.g., github://, gcs://).
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 array (AgentTool) (optional) The tools available to the agent.
A tool that the agent can use.
#### Possible Types
CodeExecution A tool that can be used by the model to execute code.
type object (required) No description provided.
Always set to `"code_execution"`.
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"`.
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.
type object (required) No description provided.
Always set to `"google_search"`.
McpServer A MCPServer is a server that can be called by the model to perform actions.
allowed_tools array (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"
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"`.
### Get Agent
#### Example Response
```json
{
"created": "2025-11-26T12:25:15Z",
"display_name": "My Research Agent",
"id": "ag_abc123",
"object": "agent",
"system_instruction": "You are a helpful research assistant.",
"tools": [
{
"type": "google_search"
}
],
"updated": "2025-11-26T12:25:15Z"
}
```
## DeleteAgent
delete https://generativelanguage.googleapis.com/v1beta/agents/{id} Deletes an Agent.
- [Path / Query parameters](https://ai.google.dev/api/agents#DeleteAgent.PATH_PARAMETERS)
- [Response](https://ai.google.dev/api/agents#DeleteAgent.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
agent_config AntigravityAgentConfig (optional) Configuration parameters for the agent.
Configuration for the Antigravity agent runtime.
Provides server-side control over the agent's execution environment
and tool configuration.
#### Fields
max_total_tokens string (optional) Max total tokens for the agent run.
model string (optional) The model to use for agent reasoning.
type object (optional) No description provided.
Always set to `"antigravity"`.
base_agent string (optional) The base agent to extend.
base_environment EnvironmentConfig or string (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 or enum (string) (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 array (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 array (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 Cloud Storage, this is the Cloud Storage 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 Cloud Storage bucket.
- `inline`
Inline content.
- `repository`
A generic repository. The protocol prefix in the source URL
identifies the provider (e.g., github://, gcs://).
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 array (AgentTool) (optional) The tools available to the agent.
A tool that the agent can use.
#### Possible Types
CodeExecution A tool that can be used by the model to execute code.
type object (required) No description provided.
Always set to `"code_execution"`.
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"`.
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.
type object (required) No description provided.
Always set to `"google_search"`.
McpServer A MCPServer is a server that can be called by the model to perform actions.
allowed_tools array (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"
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"`.