REST Resource: projects.locations.collections.engines.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,

  // 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} 或 projects/{project}/locations/{location}/collections/{collection}/engines/{engine}/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

可选。说明、displayName 和 starterPrompts 字段中文字的语言代码。
starterPrompts[]

object (StarterPrompt)

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

string

可选。用户输入任何文本之前，文本框中显示的自定义占位符文本。
联合字段 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 Gen 服务使用自定义提示。

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

必需。初始提示的文本。

方法

create

 创建 Agent。

delete

 删除 Agent。

deploy

 部署 Agent。

get

 获取 Agent。

getAgentView

 针对给定的 Agent 返回一个 AgentView，其中包含有关代理的其他信息。

list

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

patch

 更新 Agent