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

ID。服務專員的資源名稱。格式：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 標準化，並使用 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)

(選用步驟) 已淘汰：計畫遷移至 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

僅供輸出。代理遭停權的原因。只有在狀態為「已暫停」時才設定。
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，使用者必須在瀏覽器中開啟並授權。授權完成後，使用者可以重試查詢，授權會轉送給代理程式。

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

格式：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 表示法 
{

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