> ## AI Agent Context
> - Full documentation index: https://aistudio.google.com/llms.txt
> - Gemini Docs MCP server (consistent live info): https://gemini-api-docs-mcp.dev
> - Coding agent skills & setup guide: https://aistudio.google.com/docs/coding-agents.md

# Getting an agent

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

{% /callout %}

{% mark class="http-get" %}{% icon name="south_west" /%}`GET`{% /mark %} `https://generativelanguage.googleapis.com/v1beta/agents/{agentsId}`

Gets a specific Agent.

{% two-column-layout %}
  {% left-column %}
## Parameters  {% class="hide-from-toc" id="parameters" %}

  {% section class="api-ref-property-list" %}
  **agentsId**: {% mark %}required{% /mark %} `string`

  The name of the agent to retrieve.

  {% /section %}

  {% /left-column %}

  {% right-column class="sticky" %}
  **Example request** {% class="example-heading" %}

  {% tabs %}
  {% tab label="REST" %}
  ```sh
  curl -X GET https://generativelanguage.googleapis.com/v1beta/agents/ag_abc123 \
    -H "x-goog-api-key: $GEMINI_API_KEY"
  ```

  {% /tab %}

  {% tab label="Python" %}
  ```python
  import uuid
  from google import genai
  
  client = genai.Client(http_options={"api_version": "v1beta"})
  
  
  agent = client.agents.get(agent_id)
  print(agent.id)
  ```

  {% /tab %}

  {% tab label="JavaScript" %}
  ```javascript
  import {GoogleGenAI} from '@google/genai';
  
  const ai = new GoogleGenAI({apiVersion: 'v1beta'});
  
  
  const agent = await ai.agents.get(agentId);
  if (!agent.id) {
    throw new Error('Agent retrieval failed: ID is undefined');
  }
  console.log(agent.id);
  ```

  {% /tab %}

  {% tab label="Java" %}
  ```java
  import com.google.genai.Client;
  import com.google.genai.gaos.models.agents.Agent;
  import com.google.genai.gaos.models.operations.GetAgentResponse;
  import com.google.genai.types.HttpOptions;
  
  Client client =
      Client.builder().httpOptions(HttpOptions.builder().apiVersion("v1beta").build()).build();
  
  
  GetAgentResponse response = client.agents.get(agentId);
  Agent agent = response.agent().orElseThrow(() -> new RuntimeException("No agent returned"));
  System.out.println(agent.id().orElse(""));
  ```

  {% /tab %}

  {% tab label="Go" %}
  ```go
  package main
  
  import (
      "context"
      "fmt"
      "log"
      "google.golang.org/genai"
      "google.golang.org/genai/interactions/models/operations"
  )
  
  func main() {
      ctx := context.Background()
      client, err := genai.NewClient(ctx, &genai.ClientConfig{
          HTTPOptions: genai.HTTPOptions{APIVersion: "v1beta"},
      })
      if err != nil {
          log.Fatal(err)
      }
  
  
      res, err := client.Agents.Get(ctx, operations.GetAgentRequest{ID: agentID})
      if err != nil {
          log.Fatal(err)
      }
  
      if res.Agent != nil && res.Agent.ID != nil {
          fmt.Println(*res.Agent.ID)
      }
  }
  ```

  {% /tab %}

  {% /tabs %}

  {% /right-column %}

{% /two-column-layout %}

{% two-column-layout %}
  {% left-column %}
## Response  {% class="hide-from-toc" id="response" %}

  {% 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 %}

  {% /left-column %}

  {% right-column class="sticky" %}
  **Example response** {% class="example-heading" %}

  ```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"
  }
  ```

  {% /right-column %}

{% /two-column-layout %}

