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

资源：代理

执行预定义的特定任务。

JSON 表示法 
{
  "name": string,
  "displayName": string,
  "description": string,
  "icon": {
    object (Image)
  },
  "createTime": string,
  "updateTime": string,
  "authorizations": [
    string
  ],
  "authorizationConfig": {
    object (AuthorizationConfig)
  },
  "dataStoreSpecs": {
    object (DataStoreSpecs)
  },
  "state": enum (State),
  "toolSettings": {
    object (AgentToolSettings)
  },
  "languageCode": string,
  "starterPrompts": [
    {
      object (StarterPrompt)
    }
  ],
  "customPlaceholderText": string,
  "sharingConfig": {
    object (SharingConfig)
  },

  // Union field definition can be only one of the following:
  "adkAgentDefinition": {
    object (AdkAgentDefinition)
  },
  "managedAgentDefinition": {
    object (ManagedAgentDefinition)
  },
  "a2aAgentDefinition": {
    object (A2AAgentDefinition)
  },
  "dialogflowAgentDefinition": {
    object (DialogflowAgentDefinition)
  }
  // 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.
}
字段
name

string

标识符。代理的资源名称。格式：projects/{project}/locations/{location}/collections/{collection}/engines/{engine}/assistants/{assistant}/agents/{agent}
displayName

string

必需。代理的显示名称。该字段可能被 LLM 用于自动选择相应代理来响应用户查询。
description

string

必需。代理的人类可读说明。该字段可能被 LLM 用于自动选择相应代理来响应用户查询。
icon

object (Image)

可选。在界面上代表相应代理的图标。
createTime

string (Timestamp format)

仅限输出。创建相应代理时的时间戳。

采用 RFC 3339 标准，生成的输出将始终进行 Z 规范化（即转换为 UTC 零时区格式并在末尾附加 Z），并使用 0、3、6 或 9 个小数位。不带“Z”的偏差时间也是可以接受的。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
updateTime

string (Timestamp format)

仅限输出。相应代理最近一次更新时的时间戳。

采用 RFC 3339 标准，生成的输出将始终进行 Z 规范化（即转换为 UTC 零时区格式并在末尾附加 Z），并使用 0、3、6 或 9 个小数位。不带“Z”的偏差时间也是可以接受的。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
authorizations[]
(deprecated)

string

可选。已弃用：请改用 Agent.authorization_config。相应代理所需授权的列表。
authorizationConfig

object (AuthorizationConfig)

可选。相应代理所需的授权。
dataStoreSpecs

object (DataStoreSpecs)

可选。与代理关联的 DataStoreSpecs。如果不设置此字段，则会使用引擎中的所有数据存储区。
state

enum (State)

仅限输出。代理的生命周期状态。
toolSettings
(deprecated)

object (AgentToolSettings)

可选。已弃用：计划迁移到 AgentCard 定义。
languageCode

string

可选。description、displayName 和 starterPrompts 字段中文本所用语言的代码。
starterPrompts[]

object (StarterPrompt)

可选。要在代理的着陆页上向用户显示的起始提示建议。
customPlaceholderText

string

可选。在用户输入任何文本之前显示在文本框中的自定义占位符文本。
sharingConfig

object (SharingConfig)

可选。代理的共享配置。
联合字段 definition。代理的定义。LINT.IfChange(definition) definition 只能是下列其中一项：
adkAgentDefinition

object (AdkAgentDefinition)

可选。代理的行为被定义为 ADK 代理。
managedAgentDefinition

object (ManagedAgentDefinition)

可选。Google 管理的代理的行为。
a2aAgentDefinition

object (A2AAgentDefinition)

可选。代理的行为被定义为 A2A 代理。
dialogflowAgentDefinition

object (DialogflowAgentDefinition)

可选。代理的行为被定义为 Dialogflow 代理。
联合字段 agent_state_reason。代理处于其当前状态的原因。agent_state_reason 只能是下列其中一项：
suspensionReason

string

仅限输出。代理被暂停的原因。仅在状态为“SUSPENDED”时设置。
rejectionReason

string

仅限输出。代理被拒绝的原因。仅在状态为“PRIVATE”且因被拒绝而进入该状态时设置。
deploymentFailureReason

string

仅限输出。代理部署失败的原因。仅在状态为“DEPLOYMENT_FAILED”时设置。

AdkAgentDefinition

存储使用 ADK 并部署到 Agent Engine（以前称为 Reasoning Engine）的代理的定义。

JSON 表示法 
{
  "toolSettings": {
    object (AgentToolSettings)
  },
  "provisionedReasoningEngine": {
    object (ProvisionedReasoningEngine)
  },
  "authorizations": [
    string
  ]
}
字段
toolSettings

object (AgentToolSettings)

可选。用于定义代理如何呈现给规划器 LLM 的参数。
provisionedReasoningEngine

object (ProvisionedReasoningEngine)

可选。代理所连接的推理引擎。
authorizations[]
(deprecated)

string

可选。已弃用：请改用 Agent.authorizations。所需授权的资源名称。如果用户未获得授权，该服务将返回多个授权 URI，用户必须在浏览器中打开这些 URI 并进行授权。获得所有授权后，用户可以重试查询，系统会将授权转发给代理。

格式：projects/{project}/locations/{location}/authorizations/{authorization}

AgentToolSettings

表示代理的工具的设置，用于 Agentspace 规划器 LLM。

JSON 表示法 
{
  "toolDescription": string,
  "inputParameterName": string,
  "inputParameterDescription": string
}
字段
toolDescription

string

必需。LLM 可能会使用此字段来描述何时应使用代理。
inputParameterName

string

可选。函数调用的参数名称。此参数名称会提供提示，让 LLM 了解参数预计包含的内容类型，例如“question”“command”“searchQuery”等。
inputParameterDescription

string

可选。函数调用的参数说明。此说明可让 LLM 进一步了解参数，例如预计传入的内容类型，以及应对内容执行的操作。

ProvisionedReasoningEngine

跟踪代理所连接的推理引擎。此消息并非用于跟踪代理的生命周期。它仅用于定义参数，以连接到已部署至推理引擎的代理。

JSON 表示法 
{
  "reasoningEngine": string
}
字段
reasoningEngine

string

必需。代理所连接的推理引擎。格式：projects/{project}/locations/{location}/reasoningEngines/{reasoningEngine}

ManagedAgentDefinition

存储由 Google 管理的代理的定义。

JSON 表示法 
{
  "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.
}
字段
toolSettings

object (AgentToolSettings)

可选。用于定义代理如何呈现给规划器 LLM 的参数。
authorizations[]
(deprecated)

string

可选。已弃用：请改用 Agent.authorizations。所需授权的资源名称。如果用户未获得授权，该服务将返回多个授权 URI，用户必须在浏览器中打开这些 URI 并进行授权。获得所有授权后，用户可以重试查询，系统会将授权转发给代理。

格式：projects/{project}/locations/{location}/authorizations/{authorization}
deploymentInfo

object (DeploymentInfo)

仅限输出。代理的自动部署信息。
联合字段 agent_config。代理类型特定配置。agent_config 只能是下列其中一项：
dataScienceAgentConfig

object (DataScienceAgentConfig)

可选。Google 预制数据科学代理的特定配置。此数据结构旨在存储代理的部署和请求时间配置。

DataScienceAgentConfig

Google 预制数据科学代理的特定配置。此数据结构旨在存储代理的部署和请求时间配置。

JSON 表示法 
{
  "bqProjectId": string,
  "bqDatasetId": string,
  "blocklistTables": [
    string
  ],
  "allowlistTables": [
    string
  ],
  "nlQueryConfig": {
    object (NlQueryConfig)
  }
}
字段
bqProjectId

string

必需。数据集所在的 BigQuery 项目 ID。
bqDatasetId

string

必需。要用于代理的 BigQuery 数据集 ID。数据集必须位于 bqProjectId 指定的项目中。
blocklistTables[]

string

可选。要阻止代理使用的 BigQuery 表。
allowlistTables[]

string

可选。要允许代理使用的 BigQuery 表。
nlQueryConfig

object (NlQueryConfig)

可选。客户提供的配置。

NlQueryConfig

定义客户提供的针对“自然语言到 SQL 或 Python 代码”这一转换过程的特定配置。

JSON 表示法 
{
  "nl2sqlPrompt": string,
  "nl2pyPrompt": string,
  "nl2sqlExamples": [
    {
      object (Nl2SqlExample)
    }
  ],
  "schemaDescription": string,
  "bqSqlGenUseCustomPrompt": boolean
}
字段
nl2sqlPrompt

string

可选。客户提供的 NL2SQL 指令
nl2pyPrompt

string

可选。客户提供的指令，让 LLM 编写用于数据分析的 Python 代码。
nl2sqlExamples[]

object (Nl2SqlExample)

可选。客户提供的 NL2SQL 示例，包括输入和预期 SQL。
schemaDescription

string

可选。BigQuery 数据集架构的自然语言说明。
bqSqlGenUseCustomPrompt

boolean

可选。是否为 BigQuery SQL 生成式服务使用自定义提示。

Nl2SqlExample

单个 NL2SQL 示例。

JSON 表示法 
{
  "query": string,
  "expectedSql": string,
  "expectedResponse": string
}
字段
query

string

可选。要回答的自然语言查询。
expectedSql

string

可选。预期的 SQL 输出。
expectedResponse

string

可选。对查询的预期回答。

DeploymentInfo

代理的自动部署信息。

JSON 表示法 
{
  "operation": string,
  "finishTime": string
}
字段
operation

string

仅限输出。部署的长时间运行的操作资源。可用于轮询部署状态。部署完成后，此字段将为空。如果部署失败，此字段将包含失败的 LRO 的资源名称，但操作资源本身会在一段时间后自动删除。
finishTime

string (Timestamp format)

仅限输出。部署完成时间 - 仅在部署完成或失败时设置。

采用 RFC 3339 标准，生成的输出将始终进行 Z 规范化（即转换为 UTC 零时区格式并在末尾附加 Z），并使用 0、3、6 或 9 个小数位。不带“Z”的偏差时间也是可以接受的。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。

A2AAgentDefinition

使用 A2A 的代理的存储定义。

JSON 表示法 
{

  // 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.
}
字段
联合字段 agent_card。存储代理的名称、功能、身份验证信息等。agent_card 只能是下列其中一项：
jsonAgentCard

string

可选。代理卡片是一个 JSON 字符串。
remoteAgentCard

object (RemoteAgentcard)

可选。远程代理卡片。

RemoteAgentcard

远程托管的代理卡片的定义。

JSON 表示法 
{
  "uri": string
}
字段
uri

string

必需。代理卡片的 URI。

DialogflowAgentDefinition

使用 Dialogflow 代理的代理的存储定义。

JSON 表示法 
{
  "toolSettings": {
    object (AgentToolSettings)
  },
  "dialogflowAgent": string
}
字段
toolSettings

object (AgentToolSettings)

可选。用于定义代理如何呈现给规划器 LLM 的参数。
dialogflowAgent

string

必需。底层 Dialogflow 代理的资源名称。格式：projects/{project}/locations/{location}/agents/{agent}

图片

表示图片。

JSON 表示法 
{

  // 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.
}
字段
联合字段 storage_method。可以是 URI，也可以是编码为 base64 字符串的内容。storage_method 只能是下列其中一项：
uri

string

图片 URI。
content

string

采用 Base64 编码的图片文件内容。

AuthorizationConfig

描述所需的授权。

JSON 表示法 
{
  "toolAuthorizations": [
    string
  ],
  "agentAuthorization": string
}
字段
toolAuthorizations[]

string

可选。代理访问其他资源所需的授权列表。身份验证令牌将作为请求正文的一部分传递给代理。
agentAuthorization

string

可选。调用代理所需的授权。身份验证令牌将作为请求身份验证标头的一部分传递给代理。

DataStoreSpecs

表示一组数据存储区规范。

JSON 表示法 
{
  "specs": [
    {
      object (DataStoreSpec)
    }
  ]
}
字段
specs[]

object (DataStoreSpec)

可选。用于定义搜索调用中要过滤的 DataStore 以及这些数据存储区的配置的规范。仅在 Engine 具有多个数据存储区时，系统才会考虑使用此字段。

状态

代理生命周期状态的可能值。

枚举
STATE_UNSPECIFIED 状态未指定。
CONFIGURED 代理已配置，但尚未触发部署。
DEPLOYING 正在部署代理。
DISABLED 代理仅供管理员使用。
DEPLOYMENT_FAILED 代理部署失败。
PRIVATE 只有创建者可以访问代理。
ENABLED 代理可供有访问权限的用户访问。
SUSPENDED 代理暂时不可用，但对有权访问的用户可见。

StarterPrompt

要在代理的着陆页上向用户显示的起始提示建议。

JSON 表示法 
{
  "text": string
}
字段
text

string

必需。起始提示的文本。

SharingConfig

共享相关配置。

JSON 表示法 
{
  "scope": enum (Scope)
}
字段
scope

enum (Scope)

可选。代理的共享范围。

范围

代理的共享范围。

枚举
SCOPE_UNSPECIFIED 默认值。作用与 RESTRICTED 相同。
RESTRICTED 代理会根据 IAM 政策进行共享。
ALL_USERS 代理已与所有用户共享。

方法

create

 创建一个 Agent。

delete

 删除一个 Agent。

deploy

 部署一个 Agent。

disableAgent

 停用一个代理。

enableAgent

 启用一个代理。

get

 获取一个 Agent。

getAgentView

 返回给定 Agent 的 AgentView，其中包含有关该代理的附加信息。

getIamPolicy

 获取一个代理资源的访问权限控制政策。

list

 列出调用方在 Assistant 下创建的所有 Agent。

patch

 更新一个 Agent

rejectAgent

 拒绝可公开访问的代理。

requestAgentReview

 通过使代理可供审核，将其呈现给管理员。

setIamPolicy

 为一个代理资源设置访问权限控制政策。

suspendAgent

 暂停一个代理。

withdrawAgent

 撤销可公开访问的代理。