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 代理程式在所有技能中支援的一組互動模式。這項設定可以依技能覆寫。定義為 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 表示法 
{

  // Union field scheme can be only one of the following:
  "apiKeySecurityScheme": {
    object (APIKeySecurityScheme)
  },
  "httpAuthSecurityScheme": {
    object (HTTPAuthSecurityScheme)
  },
  "oauth2SecurityScheme": {
    object (OAuth2SecurityScheme)
  },
  "openIdConnectSecurityScheme": {
    object (OpenIdConnectSecurityScheme)
  },
  "mtlsSecurityScheme": {
    object (MutualTlsSecurityScheme)
  }
  // End of list of possible types for union field scheme.
}
欄位

聯集欄位 scheme。

scheme 只能是下列其中一項：
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 表示法 
{

  // Union field flow can be only one of the following:
  "authorizationCode": {
    object (AuthorizationCodeOAuthFlow)
  },
  "clientCredentials": {
    object (ClientCredentialsOAuthFlow)
  },
  "implicit": {
    object (ImplicitOAuthFlow)
  },
  "password": {
    object (PasswordOAuthFlow)
  }
  // End of list of possible types for union field flow.
}
欄位

聯集欄位 flow。

flow 只能是下列其中一項：
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", "customer support", "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 標頭值。