> ## AI Agent Context
> Get the complete documentation index at: https://aistudio.google.com/llms.txt
> Use this file to discover all available pages.
> For the full documentation in a single file, fetch: https://aistudio.google.com/llms-full.txt

# Gemini Agents API

{% callout type="note" %}
  This API is in Beta. Endpoints are under `/v1beta/`.

{% /callout %}

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.

## Methods  {% id="methods" %}

{% table %}
  * Method
  * HTTP request

  ---

  * [Creating an agent](/api-reference/agents/create-agent)
  *     {% mark class="http-post" %}{% icon name="north_east" /%}`POST`{% /mark %} `/v1beta/agents`

    Creates a new Agent (Typed version for SDK).


  ---

  * [Listing agents](/api-reference/agents/list-agents)
  *     {% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `/v1beta/agents`

    Lists all Agents.


  ---

  * [Getting an agent](/api-reference/agents/get-agent)
  *     {% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `/v1beta/agents/{agentsId}`

    Gets a specific Agent.


  ---

  * [Deleting an agent](/api-reference/agents/delete-agent)
  *     {% mark class="http-delete" %}{% icon name="close" /%}`DELETE`{% /mark %} `/v1beta/agents/{agentsId}`

    Deletes an Agent.

{% /table %}

## Resources  {% id="resources" %}

### Agent  {% id="Resource:Agent" %}

An agent definition for the CreateAgent API.
This message is the target for annotation-parser-based JSON parsing.
New format:

```json
{
  "id": "customer-sentinel",
  "base_agent": "",
  "system_instruction": "...",
  "base_environment": { "type": "remote", "sources": [...] },
  "tools": [ {"type": "code_execution"} ]
}
```

**Properties:**

{% section class="api-ref-property-list" %}
  **id**: `string`

  The unique identifier for the agent.

  {% hr /%}

  **base_agent**: `string`

  The base agent to extend.

  {% hr /%}

  **system_instruction**: `string`

  System instruction for the agent.

  {% hr /%}

  **description**: `string`

  Agent description for developers to quickly read and understand.

  {% hr /%}

  {% details %}
  {% summary %}
  **agent_config**: `AntigravityAgentConfig`

  Configuration parameters for the agent.

  {% /summary %}

  **type**: {% mark %}required{% /mark %} `object`

  Value: `antigravity`

  **model**: `string`

  The model to use for agent reasoning.

  **max_total_tokens**: `string`

  Max total tokens for the agent run.

  {% /details %}

  {% hr /%}

  {% details %}
  {% summary %}
  **base_environment**: `EnvironmentConfig` or `string`

  The environment configuration for the agent.

  {% /summary %}

  **Possible Types:** {% class="api-ref-label" %}

  {% details %}
  {% summary %}
  **EnvironmentConfig**

  {% /summary %}

  Configuration for a custom environment.

  **type**: {% mark %}required{% /mark %} `object`

  Value: `remote`

  {% details %}
  {% summary %}
  **sources**: `Source array`

  {% /summary %}

  {% details %}
  {% summary %}
  **type**: `string enum`

  {% /summary %}

  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://).

  {% /details %}

  **source**: `string`

  The source of the environment. For Cloud Storage, this is the Cloud Storage path. For GitHub, this is the GitHub path.

  **target**: `string`

  Where the source should appear in the environment.

  **content**: `string`

  The inline content if `type` is `INLINE`.

  **encoding**: `string`

  Optional encoding for inline content (e.g. `base64`).

  {% /details %}

  {% details %}
  {% summary %}
  **network**: `EnvironmentNetworkEgressAllowlist` or `string enum`

  Network configuration for the environment.

  {% /summary %}

  **Possible Types:** {% class="api-ref-label" %}

  {% details %}
  {% summary %}
  **EnvironmentNetworkEgressAllowlist**

  {% /summary %}

  Network egress configuration for the environment.

  {% details %}
  {% summary %}
  **allowlist**: `EgressRule array` or `string enum`

  List of allowed domains and their configurations. Set to `"disabled"` to block all network egress.

  {% /summary %}

  **Possible Types:** {% class="api-ref-label" %}

  {% details %}
  {% summary %}
  **EgressRule array**

  {% /summary %}

  A single domain allowlist rule with optional header injection.

  **domain**: {% mark %}required{% /mark %} `string`

  Domain to allow outbound requests to. Supports wildcards (e.g. '*.googleapis.com'). Use '*' to allow all domains.

  **transform**: `object`

  Headers to inject into requests matching this rule. Key: header name (e.g., "Authorization"). Value: header value (e.g., "Bearer your-token").

  **credential**: `string`

  Optional. Reference to a server-managed Credential resource by ID.

  {% /details %}

  {% details %}
  {% summary %}
  **string enum**

  {% /summary %}

  Possible values:

  - `disabled`: All network egress is blocked.

  {% /details %}

  {% /details %}

  {% /details %}

  {% details %}
  {% summary %}
  **string enum**

  {% /summary %}

  Possible values:

  - `disabled`: All network egress is blocked.

  {% /details %}

  {% /details %}

  **environment_id**: `string`

  Optional. The environment ID for the interaction. If specified, the request will update the existing environment instead of creating a new one.

  {% details %}
  {% summary %}
  **env**: `object` or `string`

  Environment variables to set in the sandbox environment.

  {% /summary %}

  **Possible Types:** {% class="api-ref-label" %}

  {% details %}
  {% summary %}
  **string**

  {% /summary %}

  A direct string value.

  {% /details %}

  {% /details %}

  {% details %}
  {% summary %}
  **mode**: `string enum`

  The compute lifecycle mode for this environment.

  {% /summary %}

  Possible values:

  - `on_demand`: The compute lifecycle mode for this environment.
  - `self_hosted`: The compute lifecycle mode for this environment.

  {% /details %}

  **custom_config**: `object`

  Optional. Arbitrary customer-defined JSON configuration passed through to the self-hosted environment poller. Only supported when `mode` is `SELF_HOSTED`.

  {% /details %}

  {% details %}
  {% summary %}
  **string**

  {% /summary %}

  A direct string value.

  {% /details %}

  {% /details %}

  {% hr /%}

  {% details %}
  {% summary %}
  **tools**: `AgentTool array`

  The tools available to the agent.

  {% /summary %}

  **Possible Types:** {% class="api-ref-label" %}

  {% details %}
  {% summary %}
  **CodeExecution**

  {% /summary %}

  A tool that can be used by the model to execute code.

  **type**: {% mark %}required{% /mark %} `object`

  Value: `code_execution`

  {% /details %}

  {% details %}
  {% summary %}
  **Function**

  {% /summary %}

  A tool that can be used by the model.

  **type**: {% mark %}required{% /mark %} `object`

  Value: `function`

  **name**: `string`

  The name of the function.

  **description**: `string`

  A description of the function.

  **parameters**: `object`

  The JSON Schema for the function's parameters. Supports a subset of JSON Schema. `minLength`, `maxLength`, `minProperties`, `maxProperties`, `uniqueItems`, `contains`, `minContains`, and `maxContains` are ignored and not enforced.

  {% /details %}

  {% details %}
  {% summary %}
  **GoogleSearch**

  {% /summary %}

  A tool that can be used by the model to search Google.

  **type**: {% mark %}required{% /mark %} `object`

  Value: `google_search`

  {% details %}
  {% summary %}
  **search_types**: `string enum array`

  The types of search grounding to enable.

  {% /summary %}

  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.

  {% /details %}

  {% /details %}

  {% details %}
  {% summary %}
  **McpServer**

  {% /summary %}

  A MCPServer is a server that can be called by the model to perform actions.

  **type**: {% mark %}required{% /mark %} `object`

  Value: `mcp_server`

  **name**: `string`

  The name of the MCPServer.

  **url**: `string`

  The full URL for the MCPServer endpoint. Example: "https://api.example.com/mcp"

  **headers**: `object`

  Optional: Fields for authentication headers, timeouts, etc., if needed.

  {% details %}
  {% summary %}
  **allowed_tools**: `AllowedTools array`

  The allowed tools.

  {% /summary %}

  {% details %}
  {% summary %}
  **mode**: `string enum`

  The mode of the tool choice.

  {% /summary %}

  Possible values:

  - `auto`: Auto tool choice.
  - `any`: Any tool choice.
  - `none`: No tool choice.
  - `validated`: Validated tool choice.

  {% /details %}

  **tools**: `string array`

  The names of the allowed tools.

  {% /details %}

  {% /details %}

  {% details %}
  {% summary %}
  **UrlContext**

  {% /summary %}

  A tool that can be used by the model to fetch URL context.

  **type**: {% mark %}required{% /mark %} `object`

  Value: `url_context`

  {% /details %}

  {% /details %}

{% /section %}