Method: projects.locations.collections.engines.assistants.agents.a2a.v1.getCard

v1.getCard 會傳回代理的代理資訊卡。

HTTP 要求


GET https://discoveryengine.googleapis.com/v1/{tenant=projects/*/locations/*/collections/*/engines/*/assistants/*/agents/*}/a2a/v1/card

這些網址使用 gRPC 轉碼語法。

路徑參數

參數
tenant

string

選用租戶，以路徑參數的形式提供。實驗功能，1.0 版發布時可能仍會變更。

要求主體

要求主體必須為空白。

回應主體

AgentCard 會傳達重要資訊：- 整體詳細資料 (版本、名稱、說明、用途) - 技能：代理可執行的動作/解決方案組合 - 代理支援的預設模式/內容類型。- 驗證需求 下一個 ID：19

如果成功，回應主體會含有以下結構的資料：

JSON 表示法 
{
  "protocolVersion": string,
  "name": string,
  "description": string,
  "url": string,
  "preferredTransport": string,
  "additionalInterfaces": [
    {
      object (AgentInterface)
    }
  ],
  "provider": {
    object (AgentProvider)
  },
  "version": string,
  "documentationUrl": string,
  "capabilities": {
    object (AgentCapabilities)
  },
  "securitySchemes": {
    string: {
      object (SecurityScheme)
    },
    ...
  },
  "security": [
    {
      object (Security)
    }
  ],
  "defaultInputModes": [
    string
  ],
  "defaultOutputModes": [
    string
  ],
  "skills": [
    {
      object (AgentSkill)
    }
  ],
  "supportsAuthenticatedExtendedCard": boolean,
  "signatures": [
    {
      object (AgentCardSignature)
    }
  ],
  "iconUrl": string
}
欄位
protocolVersion

string

這個代理支援的 A2A 通訊協定版本。
name

string

人類可讀的代理名稱。例如：「Recipe Agent」
description

string

代理的行動/解決方案空間說明。範例：「協助使用者尋找食譜和烹飪的代理。」
url

string

代理主機的網址。這是代理程式宣告的偏好端點。
preferredTransport

string

偏好端點的傳輸方式。如果留空，預設為 JSONRPC。
additionalInterfaces[]

object (AgentInterface)

宣布支援其他傳輸方式。用戶端可以使用任何支援的傳輸方式。
provider

object (AgentProvider)

代理的服務供應商。
version

string

代理程式版本。例如：「1.0.0」
documentationUrl

string

提供代理程式相關額外文件的網址。
capabilities

object (AgentCapabilities)

代理支援的 A2A 功能集。
securitySchemes

map (key: string, value: object (SecurityScheme))

用於向這個代理程式驗證身分的安全性配置詳細資料。
security[]

object (Security)

protolint:disable REPEATED_FIELD_NAMES_PLURALIZED 聯絡服務專員的安全規定。這份清單可以視為 AND 的 OR。清單中的每個物件都會說明一組可能的要求，這些要求必須存在於要求中。舉例來說，您可以指定「呼叫端必須使用 OAuth 或 API 金鑰和 mTLS」。示例：security { schemes { key: "oauth" value { list: ["read"] } } } security { schemes { key: "api-key" } schemes { key: "mtls" } }
defaultInputModes[]

string

protolint:enable REPEATED_FIELD_NAMES_PLURALIZED The set of interaction modes that the agent supports across all skills. 這項設定可以依技能覆寫。定義為 MIME 類型。
defaultOutputModes[]

string

這個代理程式支援的輸出內容 MIME 類型。
skills[]

object (AgentSkill)

技能代表代理可執行的能力單位。這可能有點抽象，但代表代理程式極有可能成功執行的動作。
supportsAuthenticatedExtendedCard

boolean

代理程式是否支援在使用者通過驗證時提供擴充代理程式資訊卡，也就是說，.well-known 中的資訊卡是否與 v1.getCard 中的資訊卡不同。
signatures[]

object (AgentCardSignature)

為這個 AgentCard 計算的 JSON Web 簽章。
iconUrl

string

代理圖示的網址 (選填)。

授權範圍

需要下列其中一種 OAuth 範圍：

  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/discoveryengine.readwrite
  • https://www.googleapis.com/auth/discoveryengine.serving.readwrite

詳情請參閱Authentication Overview。

IAM 權限

需要 tenant 資源的下列 IAM 權限：

  • discoveryengine.agents.get

詳情請參閱 IAM 說明文件。

AgentInterface

定義代理的額外運輸資訊。

JSON 表示法 
{
  "url": string,
  "transport": string,
  "tenant": string
}
欄位
url

string

這個介面的網址。
transport

string

傳輸作業支援這個網址。這是開放式表單字串，可輕鬆擴充許多傳輸通訊協定。官方支援的核心通訊協定為 JSONRPC、GRPC 和 HTTP+JSON。
tenant

string

呼叫代理程式時，要在要求中設定的租戶。實驗功能，1.0 版發布時可能仍會變更。

AgentProvider

代表服務專員的服務供應商相關資訊。

JSON 表示法 
{
  "url": string,
  "organization": string
}
欄位
url

string

供應商參考網址，例如「https://ai.google.dev」
organization

string

供應商機構名稱，例如「Google」

AgentCapabilities

定義代理支援的 A2A 特徵集

JSON 表示法 
{
  "streaming": boolean,
  "pushNotifications": boolean,
  "extensions": [
    {
      object (AgentExtension)
    }
  ]
}
欄位
streaming

boolean

代理程式是否支援串流回應
pushNotifications

boolean

如果代理程式可以將推播通知傳送至用戶端 Webhook
extensions[]

object (AgentExtension)

這個代理程式支援的擴充功能。

AgentExtension

代理程式支援的擴充功能聲明。

JSON 表示法 
{
  "uri": string,
  "description": string,
  "required": boolean,
  "params": {
    object
  }
}
欄位
uri

string

擴充功能的 URI。例如：「https://developers.google.com/identity/protocols/oauth2」
description

string

說明這個代理如何使用這項擴充功能。例如：「Google OAuth 2.0 驗證」
required

boolean

用戶端是否必須遵守擴充功能的特定規定。範例：false
params

object (Struct format)

擴充功能的選用設定。

SecurityScheme

JSON 表示法 
{

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "apiKeySecurityScheme": {
    object (APIKeySecurityScheme)
  },
  "httpAuthSecurityScheme": {
    object (HTTPAuthSecurityScheme)
  },
  "oauth2SecurityScheme": {
    object (OAuth2SecurityScheme)
  },
  "openIdConnectSecurityScheme": {
    object (OpenIdConnectSecurityScheme)
  },
  "mtlsSecurityScheme": {
    object (MutualTlsSecurityScheme)
  }
  // End of mutually exclusive fields.
}
欄位
以下列出互斥欄位。回應中最多會設定一個欄位：
apiKeySecurityScheme

object (APIKeySecurityScheme)
httpAuthSecurityScheme

object (HTTPAuthSecurityScheme)
oauth2SecurityScheme

object (OAuth2SecurityScheme)
openIdConnectSecurityScheme

object (OpenIdConnectSecurityScheme)
mtlsSecurityScheme

object (MutualTlsSecurityScheme)
互斥欄位的結尾。

APIKeySecurityScheme

JSON 表示法 
{
  "description": string,
  "location": string,
  "name": string
}
欄位
description

string

這項安全機制。
location

string

API 金鑰的位置，有效值為「query」、「header」或「cookie」
name

string

要使用的標頭、查詢或 Cookie 參數名稱。

HTTPAuthSecurityScheme

JSON 表示法 
{
  "description": string,
  "scheme": string,
  "bearerFormat": string
}
欄位
description

string

這項安全機制。
scheme

string

要在 Authorization 標頭中使用的 HTTP 驗證機制名稱，如 RFC7235 所定義。使用的值應在 IANA 驗證方案登錄檔中註冊。值不區分大小寫，如 RFC7235 所定義。
bearerFormat

string

提示用戶端，瞭解不記名權杖的格式。不記名權杖通常是由授權伺服器產生，因此這項資訊主要用於說明文件。

OAuth2SecurityScheme

JSON 表示法 
{
  "description": string,
  "flows": {
    object (OAuthFlows)
  },
  "oauth2MetadataUrl": string
}
欄位
description

string

這項安全機制。
flows

object (OAuthFlows)

包含支援的流程類型設定資訊的物件
oauth2MetadataUrl

string

oauth2 授權伺服器中繼資料的網址 RFC8414。必須提供 TLS。

OAuthFlows

JSON 表示法 
{

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "authorizationCode": {
    object (AuthorizationCodeOAuthFlow)
  },
  "clientCredentials": {
    object (ClientCredentialsOAuthFlow)
  },
  "implicit": {
    object (ImplicitOAuthFlow)
  },
  "password": {
    object (PasswordOAuthFlow)
  }
  // End of mutually exclusive fields.
}
欄位
以下列出互斥欄位。回應中最多會設定一個欄位：
authorizationCode

object (AuthorizationCodeOAuthFlow)
clientCredentials

object (ClientCredentialsOAuthFlow)
implicit

object (ImplicitOAuthFlow)
password

object (PasswordOAuthFlow)
互斥欄位的結尾。

AuthorizationCodeOAuthFlow

JSON 表示法 
{
  "authorizationUrl": string,
  "tokenUrl": string,
  "refreshUrl": string,
  "scopes": {
    string: string,
    ...
  }
}
欄位
authorizationUrl

string

這個流程要使用的授權網址。這項資訊必須以網址形式提供。OAuth2 標準規定必須使用 TLS
tokenUrl

string

這個流程要使用的權杖網址。這項資訊必須以網址形式提供。OAuth2 標準規定必須使用 TLS。
refreshUrl

string

用於取得更新權杖的網址。這項資訊必須以網址形式提供。OAuth2 標準規定必須使用 TLS。
scopes

map (key: string, value: string)

OAuth2 安全性機制適用的範圍。範圍名稱與簡短說明之間的對應。地圖可能沒有任何內容。

ClientCredentialsOAuthFlow

JSON 表示法 
{
  "tokenUrl": string,
  "refreshUrl": string,
  "scopes": {
    string: string,
    ...
  }
}
欄位
tokenUrl

string

這個流程要使用的權杖網址。這項資訊必須以網址形式提供。OAuth2 標準規定必須使用 TLS。
refreshUrl

string

用於取得更新權杖的網址。這項資訊必須以網址形式提供。OAuth2 標準規定必須使用 TLS。
scopes

map (key: string, value: string)

OAuth2 安全性機制適用的範圍。範圍名稱與簡短說明之間的對應。地圖可能沒有任何內容。

ImplicitOAuthFlow

JSON 表示法 
{
  "authorizationUrl": string,
  "refreshUrl": string,
  "scopes": {
    string: string,
    ...
  }
}
欄位
authorizationUrl

string

這個流程要使用的授權網址。這項資訊必須以網址形式提供。OAuth2 標準規定必須使用 TLS
refreshUrl

string

用於取得更新權杖的網址。這項資訊必須以網址形式提供。OAuth2 標準規定必須使用 TLS。
scopes

map (key: string, value: string)

OAuth2 安全性機制適用的範圍。範圍名稱與簡短說明之間的對應。地圖可能沒有任何內容。

PasswordOAuthFlow

JSON 表示法 
{
  "tokenUrl": string,
  "refreshUrl": string,
  "scopes": {
    string: string,
    ...
  }
}
欄位
tokenUrl

string

這個流程要使用的權杖網址。這項資訊必須以網址形式提供。OAuth2 標準規定必須使用 TLS。
refreshUrl

string

用於取得更新權杖的網址。這項資訊必須以網址形式提供。OAuth2 標準規定必須使用 TLS。
scopes

map (key: string, value: string)

OAuth2 安全性機制適用的範圍。範圍名稱與簡短說明之間的對應。地圖可能沒有任何內容。

OpenIdConnectSecurityScheme

JSON 表示法 
{
  "description": string,
  "openIdConnectUrl": string
}
欄位
description

string

這項安全機制。
openIdConnectUrl

string

用於探索 [[OpenID-Connect-Discovery]] 提供者中繼資料的知名網址。

MutualTlsSecurityScheme

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

string

這項安全機制。

安全性

JSON 表示法 
{
  "schemes": {
    string: {
      object (StringList)
    },
    ...
  }
}
欄位
schemes

map (key: string, value: object (StringList))

StringList

protolint:disable REPEATED_FIELD_NAMES_PLURALIZED

JSON 表示法 
{
  "list": [
    string
  ]
}
欄位
list[]

string

AgentSkill

AgentSkill 代表代理可執行的動作/解決方案單元。您可以將這視為一種高度可靠的解決方案，可指派代理提供。代理可自主選擇如何及何時使用特定技能，但用戶端應有信心，只要定義技能，就能可靠地執行該動作單元。

JSON 表示法 
{
  "id": string,
  "name": string,
  "description": string,
  "tags": [
    string
  ],
  "examples": [
    string
  ],
  "inputModes": [
    string
  ],
  "outputModes": [
    string
  ],
  "security": [
    {
      object (Security)
    }
  ]
}
欄位
id

string

這個代理程式內的技能專屬 ID。
name

string

使用者可解讀的技能名稱。
description

string

使用者 (或 LLM) 可理解的技能詳細資料和行為說明。
tags[]

string

一組技能標籤，可提升分類/使用率。例如：["cooking", "客戶服務", "billing"]
examples[]

string

這項技能設計用來處理的一組查詢範例。這些範例應有助於來電者瞭解如何向代理提出要求，以達成特定目標。範例：["I need a recipe for bread"]
inputModes[]

string

支援的可能輸入模式。
outputModes[]

string

可能產生的輸出模態
security[]

object (Security)

protolint:disable REPEATED_FIELD_NAMES_PLURALIZED 代理程式運用這項技能時必須使用的安全機制。如同整體 AgentCard.security，這份清單代表安全需求物件的邏輯 OR。每個物件都是一組必須一起使用的安全機制 (邏輯 AND)。protolint:enable REPEATED_FIELD_NAMES_PLURALIZED

AgentCardSignature

AgentCardSignature 代表 AgentCard 的 JWS 簽章。這符合 RFC 7515 JSON Web Signature (JWS) 的 JSON 格式。

JSON 表示法 
{
  "protected": string,
  "signature": string,
  "header": {
    object
  }
}
欄位
protected

string

這是必要旗標，簽章的受保護 JWS 標頭。這一律是 base64url 編碼的 JSON 物件。必填。
signature

string

這是必要旗標，計算出的簽章，經過 base64url 編碼。必填。
header

object (Struct format)

未受保護的 JWS 標頭值。