REST Resource: projects.locations.collections.engines.agents

Resource: Agent

Performs a predefined, specific task.

JSON representation 
{
  "name": string,
  "displayName": string,
  "description": string,
  "icon": {
    object (Image)
  },
  "createTime": string,
  "updateTime": string,
  "authorizations": [
    string
  ],
  "dataStoreSpecs": {
    object (DataStoreSpecs)
  },
  "state": enum (State),
  "toolSettings": {
    object (AgentToolSettings)
  },
  "languageCode": string,
  "starterPrompts": [
    {
      object (StarterPrompt)
    }
  ],

  // Union field definition can be only one of the following:
  "adkAgentDefinition": {
    object (AdkAgentDefinition)
  },
  "managedAgentDefinition": {
    object (ManagedAgentDefinition)
  },
  "a2aAgentDefinition": {
    object (A2AAgentDefinition)
  }
  // End of list of possible types for union field definition.

  // Union field agent_state_reason can be only one of the following:
  "suspensionReason": string,
  "rejectionReason": string,
  "deploymentFailureReason": string
  // End of list of possible types for union field agent_state_reason.
}
Fields
name

string

Identifier. Resource name of the agent. Format: projects/{project}/locations/{location}/collections/{collection}/engines/{engine}/assistants/{assistant}/agents/{agent} or projects/{project}/locations/{location}/collections/{collection}/engines/{engine}/agents/{agent}
displayName

string

Required. Display name of the agent. This might be used by an LLM to automatically select an agent to respond to a user query.
description

string

Required. Human-readable description of the agent. This might be used by an LLM to automatically select an agent to respond to a user query.
icon

object (Image)

Optional. The icon that represents the agent on the UI.
createTime

string (Timestamp format)

Output only. timestamp when this Agent was created.

Uses RFC 3339, where generated output will always be Z-normalized and uses 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".
updateTime

string (Timestamp format)

Output only. timestamp when this Agent was most recently updated.

Uses RFC 3339, where generated output will always be Z-normalized and uses 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".
authorizations[]

string

Optional. List of required authorizations for this agent.
dataStoreSpecs

object (DataStoreSpecs)

Optional. DataStoreSpecs associated with the agent. Not setting this field will result in using all data stores in the engine.
state

enum (State)

Output only. The lifecycle state of the agent.
toolSettings
(deprecated)

object (AgentToolSettings)

Optional. DEPRECATED: Planned migration to AgentCard definition.
languageCode

string

Optional. The code of the language of the text in the description, displayName and starterPrompts fields.
starterPrompts[]

object (StarterPrompt)

Optional. The starter prompt suggestions to show the user on the landing page of the agent.
Union field definition. The definition of the agent. definition can be only one of the following:
adkAgentDefinition

object (AdkAgentDefinition)

Optional. The behavior of the agent is defined as an ADK agent.
managedAgentDefinition

object (ManagedAgentDefinition)

Optional. The behavior of the Google managed agent.
a2aAgentDefinition

object (A2AAgentDefinition)

Optional. The behavior of the agent is defined as an A2A agent.
Union field agent_state_reason. The reason why the agent is in its current state. agent_state_reason can be only one of the following:
suspensionReason

string

Output only. The reason why the agent was suspended. Only set if the state is SUSPENDED.
rejectionReason

string

Output only. The reason why the agent was rejected. Only set if the state is PRIVATE, and got there via rejection.
deploymentFailureReason

string

Output only. The reason why the agent deployment failed. Only set if the state is DEPLOYMENT_FAILED.

AdkAgentDefinition

Stores the definition of an agent that uses ADK and is deployed to Agent Engine (formerly known as Reasoning Engine).

JSON representation 
{
  "toolSettings": {
    object (AgentToolSettings)
  },
  "provisionedReasoningEngine": {
    object (ProvisionedReasoningEngine)
  },
  "authorizations": [
    string
  ]
}
Fields
toolSettings

object (AgentToolSettings)

Optional. The parameters that define how the agent is presented to the planner LLM.
provisionedReasoningEngine

object (ProvisionedReasoningEngine)

Optional. The reasoning engine that the agent is connected to.
authorizations[]
(deprecated)

string

Optional. DEPRECATED: Use Agent.authorizations instead. Resource names of the required authorizations. If the user is not authorized, the service will return a number of authorization URIs that the user must open in a browser and authorize. Once all authorizations are granted, the user can retry the query, and the authorizations will be forwarded to the agent.

Format: projects/{project}/locations/{location}/authorizations/{authorization}

AgentToolSettings

Settings for the tool that represents the agent to the Agentspace planner LLM.

JSON representation 
{
  "toolDescription": string,
  "inputParameterName": string,
  "inputParameterDescription": string
}
Fields
toolDescription

string

Required. This might be used by an LLM to describe when the agent should be used.
inputParameterName

string

Optional. Parameter name for the function call. This parameter name will hint the LLM what type of content the parameter is expected to contain, e.g. a "question", a "command", a "searchQuery", etc.
inputParameterDescription

string

Optional. Parameter description for the function call. This description will give the LLM more information about the parameter, e.g. what kind of content is expected to be passed in and what actions should be performed on it.

ProvisionedReasoningEngine

Keeps track of the reasoning engine that the agent is connected to. This message is not intended to keep track of agent's lifecycle. Instead it is only used to define parameters to connect to the agent that is already deployed to a reasoning engine.

JSON representation 
{
  "reasoningEngine": string
}
Fields
reasoningEngine

string

Required. The reasoning engine that the agent is connected to. Format: projects/{project}/locations/{location}/reasoningEngines/{reasoningEngine}

ManagedAgentDefinition

Stores the definition of a Google managed agent.

JSON representation 
{
  "toolSettings": {
    object (AgentToolSettings)
  },
  "authorizations": [
    string
  ],
  "deploymentInfo": {
    object (DeploymentInfo)
  },

  // Union field agent_config can be only one of the following:
  "dataScienceAgentConfig": {
    object (DataScienceAgentConfig)
  }
  // End of list of possible types for union field agent_config.
}
Fields
toolSettings

object (AgentToolSettings)

Optional. The parameters that define how the agent is presented to the planner LLM.
authorizations[]
(deprecated)

string

Optional. DEPRECATED: Use Agent.authorizations instead. Resource names of the required authorizations. If the user is not authorized, the service will return a number of authorization URIs that the user must open in a browser and authorize. Once all authorizations are granted, the user can retry the query, and the authorizations will be forwarded to the agent.

Format: projects/{project}/locations/{location}/authorizations/{authorization}
deploymentInfo

object (DeploymentInfo)

Output only. Automatic deployment information for the agent.
Union field agent_config. Agent type specific configuration. agent_config can be only one of the following:
dataScienceAgentConfig

object (DataScienceAgentConfig)

Optional. Configuration specific to Google premade data science agents. This data structure is intended to store deployment and request time configuration for the agent.

DataScienceAgentConfig

Configuration specific to Google premade data science agents. This data structure is intended to store deployment and request time configuration for the agent.

JSON representation 
{
  "bqProjectId": string,
  "bqDatasetId": string,
  "blocklistTables": [
    string
  ],
  "allowlistTables": [
    string
  ],
  "nlQueryConfig": {
    object (NlQueryConfig)
  }
}
Fields
bqProjectId

string

Required. The BigQuery project id where the dataset is located.
bqDatasetId

string

Required. The BigQuery dataset id to use for the agent. The dataset must be in the project specified by bqProjectId.
blocklistTables[]

string

Optional. The BigQuery tables to block from being used by the agent.
allowlistTables[]

string

Optional. The BigQuery tables to allow to be used by the agent.
nlQueryConfig

object (NlQueryConfig)

Optional. Customer provided configuration.

NlQueryConfig

Define the customer provided configurations specific to natural language translation to SQL/Python code.

JSON representation 
{
  "nl2sqlPrompt": string,
  "nl2pyPrompt": string,
  "nl2sqlExamples": [
    {
      object (Nl2SqlExample)
    }
  ],
  "schemaDescription": string,
  "bqSqlGenUseCustomPrompt": boolean
}
Fields
nl2sqlPrompt

string

Optional. The customer provided NL2SQL instructions
nl2pyPrompt

string

Optional. The customer provided instructions for LLM to write python code for data analysis.
nl2sqlExamples[]

object (Nl2SqlExample)

Optional. The customer provided NL2SQL examples, including both input and expected sql.
schemaDescription

string

Optional. The natural language description of the schema of the BigQuery dataset.
bqSqlGenUseCustomPrompt

boolean

Optional. Whether to use the custom prompt for the BigQuery SQL Gen service.

Nl2SqlExample

A single NL2SQL example.

JSON representation 
{
  "query": string,
  "expectedSql": string,
  "expectedResponse": string
}
Fields
query

string

Optional. The natural language query to be answered.
expectedSql

string

Optional. The expected SQL output.
expectedResponse

string

Optional. The expected response to the query.

DeploymentInfo

Automatic deployment information for the agent.

JSON representation 
{
  "operation": string,
  "finishTime": string
}
Fields
operation

string

Output only. Long-running operation resource for the deployment. Can be used to poll the deployment status. When the deployment finishes, this field will be empty. If the deployment fails,the field will contain the resource name of the failed LRO, but the operation resource itself will be deleted automatically after some time.
finishTime

string (Timestamp format)

Output only. Deployment finish time - only set if the deployment is finished or failed.

Uses RFC 3339, where generated output will always be Z-normalized and uses 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".

A2AAgentDefinition

Stored definition of an agent that uses A2A.

JSON representation 
{

  // Union field agent_card can be only one of the following:
  "jsonAgentCard": string,
  "remoteAgentCard": {
    object (RemoteAgentcard)
  }
  // End of list of possible types for union field agent_card.
}
Fields
Union field agent_card. Stores agent's name, capabilities, auth info, etc. agent_card can be only one of the following:
jsonAgentCard

string

Optional. The agent card is a JSON string.
remoteAgentCard

object (RemoteAgentcard)

Optional. A remote agent card.

RemoteAgentcard

Deifinition of an agent card hosted remotely.

JSON representation 
{
  "uri": string
}
Fields
uri

string

Required. The URI of the agent card.

Image

Represents an image.

JSON representation 
{

  // Union field storage_method can be only one of the following:
  "uri": string,
  "content": string
  // End of list of possible types for union field storage_method.
}
Fields
Union field storage_method. Can be either a URI or the content encoded as a base64 string. storage_method can be only one of the following:
uri

string

Image URI.
content

string

Base64-encoded image file contents.

DataStoreSpecs

Represents a set of data store specs.

JSON representation 
{
  "specs": [
    {
      object (DataStoreSpec)
    }
  ]
}
Fields
specs[]

object (DataStoreSpec)

Optional. Specs defining DataStores to filter on in a search call and configurations for those data stores. This is only considered for Engines with multiple data stores.

State

Possible values for the lifecycle state of the agent.

Enums
STATE_UNSPECIFIED The state is unspecified.
CONFIGURED The agent is configured, but no deployment triggered yet.
DEPLOYING The agent is being deployed.
DISABLED The agent is available for admins only.
DEPLOYMENT_FAILED The agent deployment failed.
PRIVATE Agent is available only to its creator..
ENABLED Agent is available for users who have access.
SUSPENDED Agent is temporarily unavailable, though visible to users who have access.

StarterPrompt

The starter prompt suggestion to show the user on the landing page of the agent.

JSON representation 
{
  "text": string
}
Fields
text

string

Required. The text of the starter prompt.

Methods

create

 Creates an Agent.

delete

 Deletes an Agent.

deploy

 Deploys an Agent.

get

 Gets an Agent.

list

 Lists all Agents under an Assistant which were created by the caller.

patch

 Updates an Agent