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

資源：Agent

執行預先定義的特定工作。

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)
  },

  // 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

ID。代理程式的資源名稱。格式：projects/{project}/locations/{location}/collections/{collection}/engines/{engine}/assistants/{assistant}/agents/{agent}
displayName

string

這是必要旗標，代理程式的顯示名稱。LLM 可能會使用這項資訊，自動選取代理來回覆使用者查詢。
description

string

這是必要旗標，人類可讀的代理說明。LLM 可能會使用這項資訊，自動選取代理來回覆使用者查詢。
icon

object (Image)

選用。UI 中代表代理程式的圖示。
createTime

string (Timestamp format)

僅供輸出。這個 Agent 的建立時間戳記。

使用 RFC 3339，產生的輸出內容一律會經過 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 正規化，並使用 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)

選用。與代理程式相關聯的 DataStoreSpec。如未設定這個欄位，系統會使用引擎中的所有資料儲存庫。
state

enum (State)

僅供輸出。代理程式的生命週期狀態。
toolSettings
(deprecated)

object (AgentToolSettings)

選用。已淘汰：請改用 agentInvocationSpec。
agentInvocationSpec

object (AgentInvocationSpec)

選用。代理的叫用規格，LLM 會依據這項規格判斷使用時機。
languageCode

string

選用。說明、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

僅供輸出。代理人遭到停權的原因。只有在狀態為「已暫停」時才設定。
rejectionReason

string

僅供輸出。代理程式遭拒的原因。只有在狀態為 PRIVATE，且是因遭到拒絕而進入此狀態時，才需要設定。
deploymentFailureReason

string

僅供輸出。代理程式部署失敗的原因。只有在狀態為 DEPLOYMENT_FAILED 時才會設定。

AdkAgentDefinition

儲存使用 ADK 並部署至 Agent Engine (舊稱 Reasoning 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，使用者必須在瀏覽器中開啟並授權。所有授權都授予後，使用者可以重試查詢，授權會轉送給代理程式。

格式：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，使用者必須在瀏覽器中開啟並授權。授權完成後，使用者可以重試查詢，授權會轉送給代理程式。

格式：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 正規化，並使用 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

object (RemoteAgentcard)

選用。遠端代理程式卡片 (第三方)。

RemoteAgentcard

定義遠端代管的代理程式資訊卡。

JSON 表示法 
{
  "uri": string
}
欄位
uri

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 代理程式暫時無法使用，但仍會顯示給有權存取的使用者。

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

 撤回向大眾提供的代理程式。