Gemini Agents API

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

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

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

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

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".