REST Resource: projects.locations.agents

Resource: Agent

A Vertex agent contains instructions and configurations for the LLM to execute a certain task.

Fields
name string

Identifier. The resource name of the agent. Format: projects/{project}/locations/{location}/agents/{agent}.

id string

Immutable. The user-specified id for the agent. This id becomes the final component of the agent resource name. If not provided, Agent Platform will generate a value for this id. The id can be up to 63 characters and must match the regular expression [a-z]([a-z0-9-]{0,61}[a-z0-9])?.

created string (Timestamp format)

Output only. The time the agent was created.

Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".

updated string (Timestamp format)

Output only. The time the agent was last updated.

Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".

object string

Output only. The object type of the resource. For agents, the value is agent.

base_agent string

Required. Immutable. The base agent for the agent. Supported values: * antigravity-preview-05-2026

Immutable: agents.patch rejects a change, including clearing it. The kind of agent this is gets derived from this field when the agent is created and is recorded then; nothing recomputes it afterwards, so a later change would leave the agent described as one kind and behaving as another. Create a new agent instead.

metadata map (key: string, value: string)

Optional. The metadata for the agent.

description string

Optional. The description of the agent.

system_instruction string

Optional. The instructions for the agent to follow. These instructions are passed to the LLM as a system instruction.

tools[] object (AgentTool)

Optional. The tools available to the agent.

environment Union type
The environment configuration for the agent. The following is a list of mutually exclusive fields. At most one of the fields will be set in a response:
base_environment value (Value format)

Optional. The base environment configuration for the agent. Valid types:

  • A string value for the environment id, or remote for the default.
  • A struct value for the environment_config.
End of mutually exclusive fields.
JSON representation 
{
  "name": string,
  "id": string,
  "created": string,
  "updated": string,
  "object": string,
  "base_agent": string,
  "metadata": {
    string: string,
    ...
  },
  "description": string,
  "system_instruction": string,
  "tools": [
    {
      object (AgentTool)
    }
  ],

  // environment
  "base_environment": value
  // Union type
}

AgentTool

A tool provides a list of actions available to the Agent during the process of executing a task.

Fields
type string

Required. The type of the tool. Supported types:

  • code_execution
  • endpoint
  • filesystem
  • google_search
  • mcp_server
  • url_context
name string

Optional. The tool's Google Cloud resource name, used to resolve the tool. Applicable when type is mcp_server or endpoint (a tool registered in Agent Registry), for example projects/{project}/locations/{location}/.../mcpServers/{id} or projects/{project}/locations/{location}/.../endpoints/{id}.

url string

Optional. Temporary: the tool's runtime reference, consumed by agents.create to create the downstream AI App. Applicable when type is mcp_server or endpoint. It is duplicated here (the resource name is already in name) only because the Agent service is not yet connected to Agent Registry to derive it from name; the Task service instead resolves it from Agent Registry (GetMcpServer / GetEndpoint) at task creation.

headers map (key: string, value: string)

Optional. The headers for the MCP server, such as for authentication. Only applicable when type is mcp_server.

JSON representation 
{
  "type": string,
  "name": string,
  "url": string,
  "headers": {
    string: string,
    ...
  }
}

Methods

create

 Creates an agent.

delete

 Deletes an agent.

get

 Retrieves an agent.

list

 Lists the agents in a location that belong to the caller.

patch

 Updates an agent.