agents

Creates, updates, deletes, gets or lists an agents resource.

Overview

Name	agents
Type	Resource
Id	google.aiplatform.agents

Fields

The following fields are returned by SELECT queries:

get

Name	Datatype	Description
id	string	Immutable. The user-specified ID for the agent. This ID becomes the final component of the agent resource name. If not provided, Vertex AI 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])?.
name	string	Identifier. The resource name of the agent. Format: projects/{project}/locations/{location}/agents/{agent}.
base_agent	string	Required. The base agent for the agent. Supported values: * antigravity-preview-05-2026
base_environment	any	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.
created	string (google-datetime)	Output only. The time the agent was created.
description	string	Optional. The description of the agent.
metadata	object	Optional. The metadata for the agent.
object	string	Output only. The object type of the resource. For agents, the value is agent.
system_instruction	string	Optional. The instructions for the agent to follow. These instructions are passed to the LLM as a system instruction.
tools	array	Optional. The tools available to the agent.
updated	string (google-datetime)	Output only. The time the agent was last updated.

list

Name	Datatype	Description
id	string	Immutable. The user-specified ID for the agent. This ID becomes the final component of the agent resource name. If not provided, Vertex AI 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])?.
name	string	Identifier. The resource name of the agent. Format: projects/{project}/locations/{location}/agents/{agent}.
base_agent	string	Required. The base agent for the agent. Supported values: * antigravity-preview-05-2026
base_environment	any	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.
created	string (google-datetime)	Output only. The time the agent was created.
description	string	Optional. The description of the agent.
metadata	object	Optional. The metadata for the agent.
object	string	Output only. The object type of the resource. For agents, the value is agent.
system_instruction	string	Optional. The instructions for the agent to follow. These instructions are passed to the LLM as a system instruction.
tools	array	Optional. The tools available to the agent.
updated	string (google-datetime)	Output only. The time the agent was last updated.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get	select	projectsId, locationsId, agentsId		Retrieves an agent.
list	select	projectsId, locationsId	orderBy, pageSize, pageToken	Lists the agents in a location that belong to the caller. An agent belongs to the end user recorded as its owner when it was created, so the response holds that caller's agents and no others. It is empty for a caller that is not an end user, and an agent with no recorded owner is listed for nobody.
create	insert	projectsId, locationsId		Creates an agent.
patch	update	projectsId, locationsId, agentsId	updateMask	Updates an agent.
delete	delete	projectsId, locationsId, agentsId		Deletes an agent.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
agentsId	string
locationsId	string
projectsId	string
orderBy	string
pageSize	integer (int32)
pageToken	string
updateMask	string (google-fieldmask)

SELECT examples

get

Retrieves an agent.

SELECT
id,
name,
base_agent,
base_environment,
created,
description,
metadata,
object,
system_instruction,
tools,
updated
FROM google.aiplatform.agents
WHERE projectsId = '{{ projectsId }}' -- required
AND locationsId = '{{ locationsId }}' -- required
AND agentsId = '{{ agentsId }}' -- required
;

list

Lists the agents in a location that belong to the caller. An agent belongs to the end user recorded as its owner when it was created, so the response holds that caller's agents and no others. It is empty for a caller that is not an end user, and an agent with no recorded owner is listed for nobody.

SELECT
id,
name,
base_agent,
base_environment,
created,
description,
metadata,
object,
system_instruction,
tools,
updated
FROM google.aiplatform.agents
WHERE projectsId = '{{ projectsId }}' -- required
AND locationsId = '{{ locationsId }}' -- required
AND orderBy = '{{ orderBy }}'
AND pageSize = '{{ pageSize }}'
AND pageToken = '{{ pageToken }}'
;

INSERT examples

create

Creates an agent.

INSERT INTO google.aiplatform.agents (
data__base_agent,
data__base_environment,
data__description,
data__id,
data__metadata,
data__name,
data__system_instruction,
data__tools,
projectsId,
locationsId
)
SELECT 
'{{ base_agent }}',
'{{ base_environment }}',
'{{ description }}',
'{{ id }}',
'{{ metadata }}',
'{{ name }}',
'{{ system_instruction }}',
'{{ tools }}',
'{{ projectsId }}',
'{{ locationsId }}'
RETURNING
name,
done,
error,
metadata,
response
;

Manifest

# Description fields are for documentation purposes
- name: agents
props:
  - name: projectsId
    value: "{{ projectsId }}"
    description: Required parameter for the agents resource.
  - name: locationsId
    value: "{{ locationsId }}"
    description: Required parameter for the agents resource.
  - name: base_agent
    value: "{{ base_agent }}"
    description: |
      Required. The base agent for the agent. Supported values: * `antigravity-preview-05-2026`
  - name: base_environment
    value: "{{ base_environment }}"
    description: |
      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`.
  - name: description
    value: "{{ description }}"
    description: |
      Optional. The description of the agent.
  - name: id
    value: "{{ id }}"
    description: |
      Immutable. The user-specified ID for the agent. This ID becomes the final component of the agent resource name. If not provided, Vertex AI 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])?`.
  - name: metadata
    value: "{{ metadata }}"
    description: |
      Optional. The metadata for the agent.
  - name: name
    value: "{{ name }}"
    description: |
      Identifier. The resource name of the agent. Format: `projects/{project}/locations/{location}/agents/{agent}`.
  - name: system_instruction
    value: "{{ system_instruction }}"
    description: |
      Optional. The instructions for the agent to follow. These instructions are passed to the LLM as a system instruction.
  - name: tools
    description: |
      Optional. The tools available to the agent.
    value:
      - headers: "{{ headers }}"
        name: "{{ name }}"
        type: "{{ type }}"
        url: "{{ url }}"

UPDATE examples

patch

Updates an agent.

UPDATE google.aiplatform.agents
SET 
data__base_agent = '{{ base_agent }}',
data__base_environment = '{{ base_environment }}',
data__description = '{{ description }}',
data__id = '{{ id }}',
data__metadata = '{{ metadata }}',
data__name = '{{ name }}',
data__system_instruction = '{{ system_instruction }}',
data__tools = '{{ tools }}'
WHERE 
projectsId = '{{ projectsId }}' --required
AND locationsId = '{{ locationsId }}' --required
AND agentsId = '{{ agentsId }}' --required
AND updateMask = '{{ updateMask}}'
RETURNING
id,
name,
base_agent,
base_environment,
created,
description,
metadata,
object,
system_instruction,
tools,
updated;

DELETE examples

delete

Deletes an agent.

DELETE FROM google.aiplatform.agents
WHERE projectsId = '{{ projectsId }}' --required
AND locationsId = '{{ locationsId }}' --required
AND agentsId = '{{ agentsId }}' --required
;