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)
  },
  "agentInvocationSpec": {
    object (AgentInvocationSpec)
  },
  "languageCode": string,
  "starterPrompts": [
    {
      object (StarterPrompt)
    }
  ],
  "customPlaceholderText": string,
  "sharingConfig": {
    object (SharingConfig)
  },
  "observabilityConfig": {
    object (ObservabilityConfig)
  },

  // 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,
  "creationFailureReason": 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)

可选。已弃用：请改用 agentInvocationSpec。
agentInvocationSpec

object (AgentInvocationSpec)

可选。代理的调用规范，供 LLM 决定何时使用代理。
languageCode

string

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

object (StarterPrompt)

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

string

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

object (SharingConfig)

可选。代理的共享配置。
observabilityConfig

object (ObservabilityConfig)

可选。代理的可观测性配置。
联合字段 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”时设置。
creationFailureReason

string

仅限输出。代理创建（配置）失败的原因。仅在状态为“CREATION_FAILED”时设置。

AdkAgentDefinition

存储使用 ADK 并部署到 Agent Engine（以前称为推理引擎）的智能体的定义。

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

object (AgentToolSettings)

可选。用于定义代理如何呈现给规划器 LLM 的参数。已弃用：请改用 Agent.agent_invocation_spec。
provisionedReasoningEngine

object (ProvisionedReasoningEngine)

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

string

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

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

AgentToolSettings

已弃用：请改用 AgentInvocationSpec。表示代理的工具的设置，供 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
(deprecated)

object (AgentToolSettings)

可选。用于定义代理如何呈现给规划器 LLM 的参数。已弃用：请改用 Agent.agent_invocation_spec。
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 表示法 
{
  "cloudMarketplaceConfig": {
    object (CloudMarketplaceConfig)
  },

  // 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.
}
字段
cloudMarketplaceConfig

object (CloudMarketplaceConfig)

可选。特定于从 Cloud Marketplace 部署的代理的配置。
联合字段 agent_card。存储代理的名称、功能、身份验证信息等。agent_card 只能是下列其中一项：
jsonAgentCard

string

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

object (RemoteAgentcard)

可选。已弃用：请勿用于新集成。请改用 jsonAgentCard。 远程代理卡片（第三方）。

RemoteAgentcard

已弃用：远程托管的代理卡片的定义。请勿用于新集成。请改用 jsonAgentCard；远程代理卡片的 URI 可以嵌入在 JSON 载荷中。保留此属性是为了向后兼容现有的代理注册表导入。

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

string

必需。已弃用：请参阅外围消息。代理卡片的 URI。

CloudMarketplaceConfig

特定于从 Cloud Marketplace 部署的代理的配置。

JSON 表示法 
{
  "entitlement": string,
  "order": string
}
字段
entitlement

string

必需。与此代理相关联的 Marketplace 授权。格式：projects/{project}/entitlements/{entitlement}。
order

string

仅限输出。相应代理所属的 Marketplace 订单。格式：billingAccounts/{billingAccount}/orders/{order}

DialogflowAgentDefinition

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

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

object (AgentToolSettings)

可选。用于定义代理如何呈现给规划器 LLM 的参数。已弃用：请改用 agentInvocationSpec。
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 代理暂时不可用，但对有权访问的用户可见。
CREATING 正在创建代理。
CREATION_FAILED 代理创建（配置）失败。终端。如需重试，调用方必须先执行 agents.delete 以清除失败的资源，然后再重新创建；无法就地覆盖失败的代理。仅针对异步配置的代理设置。

AgentInvocationSpec

代理的调用规范，供 LLM 决定何时调用代理。

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

string

必需。用于指导 LLM 何时调用代理的说明。好的说明应清晰简洁地说明代理的功能，例如：“此代理可以预订航班和查看航班状态。”

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。

get

 获取 Agent。

list

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

patch

 更新一个 Agent

rejectAgent

 拒绝可公开访问的代理。

requestAgentReview

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

withdrawAgent

 撤销可公开访问的代理。