Mendaftarkan dan mengelola agen A2A

Protokol Agent2Agent (A2A) adalah protokol komunikasi terbuka dan bahasa universal untuk agen. Protokol ini memungkinkan agen dari berbagai builder dan platform untuk saling menemukan, berkolaborasi, dan mendelegasikan tugas dengan aman. Dokumen ini menjelaskan cara administrator Gemini Enterprise dapat menghubungkan agen yang dibuat menggunakan A2A dan dihosting di platform mana pun ke Gemini Enterprise, sehingga agen tersebut tersedia bagi pengguna di aplikasi web Gemini Enterprise.

Sebelum memulai

Pastikan Anda memiliki:

  • Peran Gemini Enterprise Admin.

  • Aktifkan Discovery Engine API. Untuk mengaktifkan Discovery Engine API untuk project Google Cloud, di konsol Google Cloud , buka halaman Discovery Engine API.

    Buka Discovery Engine API

  • Aplikasi Gemini Enterprise yang sudah ada. Untuk membuat aplikasi, lihat Membuat aplikasi.

  • Agen yang menggunakan protokol A2A.

    Gemini Enterprise mendukung mekanisme streaming A2A v0.3.

    Jika Anda menggunakan A2A v1.0.0 atau yang lebih baru, gunakan paket kompatibilitas yang disediakan oleh SDK untuk memastikan agen Anda berfungsi dengan mekanisme sebelumnya (misalnya, paket a2acompat/a2av0 untuk Go atau paket a2a.compat.v0_3 untuk Python).

  • Jika agen A2A Anda dihosting di Cloud Run, menggunakan URL .run.app default secara langsung, dan memerlukan autentikasi, berikan peran Cloud Run Invoker (roles/run.invoker) ke agen layanan Discovery Engine (ini tidak berlaku jika Cloud Run berada di belakang Apigee, load balancer, atau domain kustom):

    gcloud projects add-iam-policy-binding <var>PROJECT_ID</var> \
       --member="serviceAccount:service-<var>PROJECT_NUMBER</var>@gcp-sa-discoveryengine.iam.gserviceaccount.com" \
       --role="roles/run.invoker"
    

    Ganti kode berikut:

    • PROJECT_ID: ID project Anda.
    • PROJECT_NUMBER: jumlah project Google Cloud Anda.

Mengonfigurasi autentikasi dan otorisasi

Bergantung pada lingkungan hosting agen dan persyaratan keamanan Anda, Anda dapat mengonfigurasi cara Gemini Enterprise melakukan autentikasi dengan agen Anda, cara agen Anda mengakses resource dan alat downstream atas nama pengguna akhir, dan cara mengamankan endpoint agen Anda:

Cara Gemini Enterprise melakukan autentikasi dengan agen Anda

Saat Gemini Enterprise memanggil agen A2A, Gemini Enterprise dapat mengirim data autentikasi dan otorisasi di header permintaan, bergantung pada konfigurasi hosting dan keamanan Anda:

Header Deskripsi
X-Serverless-Authorization

Autentikasi IAM service-to-service (untuk Cloud Run).

Jika agen A2A Anda dihosting di Cloud Run dan URL agen Anda adalah URL .run.app default, Gemini Enterprise akan otomatis membuat token ID OIDC yang ditandatangani Google untuk agen layanan Discovery Engine (service-PROJECT_NUMBER@gcp-sa-discoveryengine.iam.gserviceaccount.com) dengan URL agen Anda sebagai audiens, dan melampirkannya di header X-Serverless-Authorization. Jika URL agen Anda menggunakan Apigee, load balancer, atau domain kustom, Gemini Enterprise tidak akan mengirim header ini.

Saat Gemini Enterprise memanggil URL .run.app default secara langsung, infrastruktur ingress Cloud Run menggunakan header ini untuk memverifikasi bahwa agen layanan memiliki peran IAM roles/run.invoker (lihat Sebelum memulai) sebelum meneruskan permintaan ke container aplikasi Anda.

Authorization

Otorisasi OAuth 2.0 pengguna akhir (untuk pemanggilan endpoint, konteks pengguna, dan akses API).

Jika Anda mengonfigurasi kredensial OAuth 2.0 untuk agen A2A (lihat Mengonfigurasi OAuth 2.0 untuk otorisasi pengguna akhir), Gemini Enterprise akan memperoleh token akses atau token ID OAuth 2.0 atas nama pengguna akhir yang login setelah mereka memberikan izin, dan mengirimkannya di header Authorization standar (misalnya, Bearer USER_OAUTH_TOKEN).

Untuk agen yang dihosting di Cloud Run, Cloud Run meneruskan header Authorization langsung ke container Anda, sehingga kode aplikasi agen Anda dapat membaca token pengguna dan memanggil API downstream atas nama pengguna. Untuk agen A2A yang dihosting di Agent Runtime, mengonfigurasi resource otorisasi OAuth 2.0 dengan cakupan https://www.googleapis.com/auth/cloud-platform memungkinkan Gemini Enterprise melakukan autentikasi ke endpoint Agent Runtime atas nama pengguna.

Mengonfigurasi OAuth 2.0 untuk otorisasi pengguna akhir (opsional)

Untuk agen A2A, konfigurasikan kredensial OAuth 2.0 di Gemini Enterprise jika endpoint agen Anda memerlukan token OAuth 2.0 pengguna akhir di header Authorization (misalnya, untuk memanggil agen A2A yang dihosting di Agent Runtime atau untuk meneruskan token pengguna langsung ke container agen Anda). Untuk mengetahui informasi selengkapnya tentang cara kerja header autentikasi dan otorisasi, lihat Cara Gemini Enterprise melakukan autentikasi dengan agen Anda.

Jika agen A2A Anda menggunakan pengelola autentikasi Agent Identity untuk OAuth 3-legged tingkat alat (misalnya, untuk mengakses server MCP atau API pihak ketiga atas nama pengguna), lihat Mengonfigurasi OAuth 3-legged dengan pengelola autentikasi Agent Identity.

Ikuti langkah-langkah berikut untuk membuat client ID OAuth:

  1. Di konsol Google Cloud , di halaman APIs & Services, buka halaman Credentials.

    Buka Kredensial

  2. Pilih project Google Cloud , yang memiliki sumber data yang ingin diakses oleh agen. Misalnya, pilih project yang berisi set data BigQuery yang ingin Anda kueri oleh agen.

  3. Klik Create credentials, lalu pilih OAuth client ID.

  4. Di Application type, pilih aplikasi web.

  5. Di bagian Authorized redirect URIs, tambahkan URI berikut:

    • https://vertexaisearch.cloud.google.com/oauth-redirect
    • https://vertexaisearch.cloud.google.com/static/oauth/oauth.html
  6. Klik Create.

  7. Di panel OAuth client created, klik Download JSON. JSON yang didownload mencakup Client ID, Authorization URI, Token URI, dan Client secret untuk project Google Cloud yang dipilih. Anda memerlukan detail ini untuk membuat resource otorisasi.

Mengonfigurasi 3-legged OAuth dengan pengelola autentikasi Agent Identity (opsional)

Jika agen A2A Anda dibuat dengan Agent Development Kit (ADK) dan menggunakan pengelola autentikasi Agent Identity untuk OAuth 3-legged (3LO), agen Anda dapat melakukan autentikasi ke server MCP, Google Cloud layanan, atau API pihak ketiga downstream atas nama pengguna yang login.

Jika alat di agen A2A Anda memerlukan izin pengguna, Gemini Enterprise akan otomatis mengelola alur kerja 3LO sisi klien:

  1. Dialog izin: Saat agen Anda menampilkan interupsi alat adk_request_credential (TASK_STATE_AUTH_REQUIRED), aplikasi web Gemini Enterprise akan meminta pengguna untuk login dan membuka URI otorisasi dari penyedia autentikasi.
  2. Validasi pengguna dan penyimpanan token: Setelah pengguna memberikan izin, penyedia autentikasi akan mengalihkan ke endpoint validasi Gemini Enterprise (https://vertexaisearch.cloud.google.com/validateUserId). Gemini Enterprise memvalidasi status sesi dan menyelesaikan kredensial dengan pengelola autentikasi Agent Identity.
  3. Melanjutkan percakapan: Gemini Enterprise mengirimkan respons adk_request_credential yang telah selesai kembali ke agen A2A Anda, yang mengambil token akses pengguna dari penyedia autentikasi dan memanggil alat.

Karena Gemini Enterprise menangani perintah izin, endpoint validasi, dan melanjutkan percakapan, Anda tidak perlu mengimplementasikan aplikasi UI sisi klien kustom.

Langkah 1: Siapkan penyedia autentikasi OAuth 3-legged

Ikuti langkah-langkah di Melakukan autentikasi menggunakan 3-legged OAuth dengan pengelola autentikasi untuk mengaktifkan Agent Identity API (agentidentity.googleapis.com), mengonfigurasi aplikasi klien OAuth, dan membuat penyedia autentikasi 3-legged OAuth.

Saat mengonfigurasi klien OAuth dan penyedia autentikasi untuk digunakan dengan Gemini Enterprise, sertakan setelan berikut:

  • Authorized redirect URIs: Dalam konfigurasi klien OAuth, tambahkan URI pengalihan callback penyedia autentikasi:

    https://agentidentitycredentials.googleapis.com/v1/projects/<var>PROJECT_ID</var>/locations/<var>LOCATION</var>/authProviders/<var>AUTH_PROVIDER_NAME</var>/oauthcallback
    

    Jika Anda menggunakan kembali klien OAuth yang sama untuk resource otorisasi agen Gemini Enterprise (misalnya, untuk mengizinkan Gemini Enterprise memanggil agen A2A yang dihosting di Agent Runtime), sertakan juga URI pengalihan Gemini Enterprise (https://vertexaisearch.cloud.google.com/oauth-redirect).

  • Continue URI: Tetapkan URI lanjutkan (sebagai Default continue URI di penyedia autentikasi atau sebagai continue_uri dalam kode agen Anda) ke endpoint validasi Gemini Enterprise:

    https://vertexaisearch.cloud.google.com/validateUserId
    

Langkah 2: Konfigurasikan kode agen A2A Anda

Saat membangun agen ADK dan menggabungkannya dengan A2aAgent untuk deployment di Agent Runtime, pastikan kode agen Anda memenuhi persyaratan berikut:

  • Instal versi paket yang diperlukan: Sertakan a2a-sdk[http-server]>=1.0.0, google-cloud-aiplatform[agent_engines,adk]>=1.156.0, dan google-adk[a2a,agent-identity,mcp]>2.7.1 dalam persyaratan deployment Anda.
  • Tetapkan continue_uri ke Gemini Enterprise: Tetapkan continue_uri ke "https://vertexaisearch.cloud.google.com/validateUserId" di GcpAuthProviderScheme atau AgentRegistry.get_mcp_toolset (kecuali jika Anda mengonfigurasinya sebagai URI lanjutkan default di penyedia autentikasi).
  • Daftarkan GcpAuthProvider di dalam fungsi runner builder: Panggil CredentialManager.register_auth_provider(GcpAuthProvider()) di dalam fungsi yang membangun Runner dalam proses worker container yang di-deploy, bukan hanya di tingkat teratas modul.
  • Gunakan A2aAgentExecutor bawaan: Teruskan A2aAgentExecutor(runner=build_runner) (from google.adk.a2a.executor.a2a_agent_executor import A2aAgentExecutor) ke A2aAgent. Jangan gunakan AgentExecutor kustom yang hanya memeriksa event.is_final_response(), karena A2aAgentExecutor diperlukan untuk mengonversi interupsi adk_request_credential menjadi status tugas A2A TASK_STATE_AUTH_REQUIRED.
  • Sertakan protokol A2A versi 0.3 di AgentCard: Tambahkan AgentInterface dengan protocol_version=PROTOCOL_VERSION_0_3 dan protocol_binding=TransportProtocol.HTTP_JSON ke agent_card.supported_interfaces bersama antarmuka 1.0 default agar Gemini Enterprise dapat berkomunikasi dengan agen Anda melalui rute A2A v0.3.

ADK + A2A

Contoh berikut mengonfigurasi agen A2A ADK yang menggunakan GcpAuthProviderScheme dengan McpToolset (atau AgentRegistry.get_mcp_toolset) untuk melakukan autentikasi ke server MCP atas nama pengguna:

from a2a.types import AgentInterface, AgentSkill
from a2a.utils.constants import PROTOCOL_VERSION_0_3, PROTOCOL_VERSION_1_0, TransportProtocol
from google.adk.a2a.executor.a2a_agent_executor import A2aAgentExecutor
from google.adk.agents import LlmAgent
from google.adk.artifacts.in_memory_artifact_service import InMemoryArtifactService
from google.adk.auth.credential_manager import CredentialManager
from google.adk.integrations.agent_identity import GcpAuthProvider, GcpAuthProviderScheme
from google.adk.memory.in_memory_memory_service import InMemoryMemoryService
from google.adk.runners import Runner
from google.adk.sessions.in_memory_session_service import InMemorySessionService
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams
from google.adk.tools.mcp_tool.mcp_toolset import McpToolset
from vertexai.agent_engines.templates.a2a import A2aAgent, create_agent_card

# Redirect URI for Gemini Enterprise user validation
CONTINUE_URI = "https://vertexaisearch.cloud.google.com/validateUserId"

auth_scheme = GcpAuthProviderScheme(
    name="projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME",
    scopes=["OAUTH_SCOPE"],
    continue_uri=CONTINUE_URI,
)

mcp_tools = McpToolset(
    connection_params=StreamableHTTPConnectionParams(
        url="https://YOUR_MCP_SERVER_URL"
    ),
    auth_scheme=auth_scheme,
)

# Alternatively, if your MCP server is registered in Agent Registry
# with an outbound auth provider binding, use AgentRegistry.get_mcp_toolset:
# from google.adk.integrations.agent_registry import AgentRegistry
# registry = AgentRegistry(project_id="PROJECT_ID", location="LOCATION")
# mcp_tools = registry.get_mcp_toolset(
#     mcp_server_name="projects/PROJECT_ID/locations/LOCATION/mcpServers/MCP_SERVER_ID",
#     continue_uri=CONTINUE_URI,
# )

adk_agent = LlmAgent(
    model="gemini-2.5-flash",
    name="AGENT_NAME",
    description="AGENT_DESCRIPTION",
    instruction="AGENT_INSTRUCTIONS",
    tools=[mcp_tools],
)

def build_runner() -> Runner:
    # Register GcpAuthProvider inside the deployed worker process
    CredentialManager.register_auth_provider(GcpAuthProvider())
    return Runner(
        app_name=adk_agent.name,
        agent=adk_agent,
        artifact_service=InMemoryArtifactService(),
        session_service=InMemorySessionService(),
        memory_service=InMemoryMemoryService(),
    )

agent_card = create_agent_card(
    agent_name="AGENT_DISPLAY_NAME",
    description="AGENT_DESCRIPTION",
    skills=[
        AgentSkill(
            id="SKILL_ID",
            name="SKILL_NAME",
            description="SKILL_DESCRIPTION",
            tags=[],
        )
    ],
)

agent_card.supported_interfaces = [
    AgentInterface(
        protocol_binding=TransportProtocol.HTTP_JSON,
        protocol_version=PROTOCOL_VERSION_1_0,
        url="",
    ),
    AgentInterface(
        protocol_binding=TransportProtocol.HTTP_JSON,
        protocol_version=PROTOCOL_VERSION_0_3,
        url="",
    ),
]

a2a_agent = A2aAgent(
    agent_card=agent_card,
    agent_executor_builder=lambda: A2aAgentExecutor(runner=build_runner),
)

ADK + A2A

Contoh berikut mengonfigurasi agen A2A ADK yang menggunakan AuthenticatedFunctionTool dengan GcpAuthProviderScheme untuk memanggil REST API pihak ketiga atau Google Cloud atas nama pengguna:

from a2a.types import AgentInterface, AgentSkill
from a2a.utils.constants import PROTOCOL_VERSION_0_3, PROTOCOL_VERSION_1_0, TransportProtocol
from google.adk.a2a.executor.a2a_agent_executor import A2aAgentExecutor
from google.adk.agents import LlmAgent
from google.adk.artifacts.in_memory_artifact_service import InMemoryArtifactService
from google.adk.auth.auth_credential import AuthCredential
from google.adk.auth.auth_tool import AuthConfig
from google.adk.auth.credential_manager import CredentialManager
from google.adk.integrations.agent_identity import GcpAuthProvider, GcpAuthProviderScheme
from google.adk.memory.in_memory_memory_service import InMemoryMemoryService
from google.adk.runners import Runner
from google.adk.sessions.in_memory_session_service import InMemorySessionService
from google.adk.tools.authenticated_function_tool import AuthenticatedFunctionTool
import httpx
from vertexai.agent_engines.templates.a2a import A2aAgent, create_agent_card

# Redirect URI for Gemini Enterprise user validation
CONTINUE_URI = "https://vertexaisearch.cloud.google.com/validateUserId"

auth_config = AuthConfig(
    auth_scheme=GcpAuthProviderScheme(
        name="projects/PROJECT_ID/locations/LOCATION/authProviders/AUTH_PROVIDER_NAME",
        scopes=["OAUTH_SCOPE"],
        continue_uri=CONTINUE_URI,
    )
)

async def call_external_api(credential: AuthCredential, query: str) -> str:
    """Calls an external API using the end user's OAuth token."""
    token = None
    if credential and credential.http and credential.http.credentials:
        token = credential.http.credentials.token
    if not token:
        return "Error: No authentication token available."

    async with httpx.AsyncClient() as client:
        response = await client.get(
            "https://YOUR_API_ENDPOINT",
            headers={"Authorization": f"Bearer {token}"},
            params={"q": query},
        )
        response.raise_for_status()
        return response.text

authenticated_tool = AuthenticatedFunctionTool(
    func=call_external_api,
    auth_config=auth_config,
)

adk_agent = LlmAgent(
    model="gemini-2.5-flash",
    name="AGENT_NAME",
    description="AGENT_DESCRIPTION",
    instruction="AGENT_INSTRUCTIONS",
    tools=[authenticated_tool],
)

def build_runner() -> Runner:
    # Register GcpAuthProvider inside the deployed worker process
    CredentialManager.register_auth_provider(GcpAuthProvider())
    return Runner(
        app_name=adk_agent.name,
        agent=adk_agent,
        artifact_service=InMemoryArtifactService(),
        session_service=InMemorySessionService(),
        memory_service=InMemoryMemoryService(),
    )

agent_card = create_agent_card(
    agent_name="AGENT_DISPLAY_NAME",
    description="AGENT_DESCRIPTION",
    skills=[
        AgentSkill(
            id="SKILL_ID",
            name="SKILL_NAME",
            description="SKILL_DESCRIPTION",
            tags=[],
        )
    ],
)

agent_card.supported_interfaces = [
    AgentInterface(
        protocol_binding=TransportProtocol.HTTP_JSON,
        protocol_version=PROTOCOL_VERSION_1_0,
        url="",
    ),
    AgentInterface(
        protocol_binding=TransportProtocol.HTTP_JSON,
        protocol_version=PROTOCOL_VERSION_0_3,
        url="",
    ),
]

a2a_agent = A2aAgent(
    agent_card=agent_card,
    agent_executor_builder=lambda: A2aAgentExecutor(runner=build_runner),
)

Langkah 3: Deploy agen A2A dengan Identitas Agen dan berikan akses

  1. Deploy A2aAgent Anda ke Agent Runtime dengan identity_type=types.IdentityType.AGENT_IDENTITY:

    import vertexai
    from vertexai import types
    
    client = vertexai.Client(
        project="<var>PROJECT_ID</var>",
        location="<var>LOCATION</var>",
        http_options=dict(api_version="v1beta1"),
    )
    
    remote_a2a_agent = client.agent_engines.create(
        agent=a2a_agent,
        config={
            "display_name": "<var>AGENT_DISPLAY_NAME</var>",
            "identity_type": types.IdentityType.AGENT_IDENTITY,
            "requirements": [
                "a2a-sdk[http-server]>=1.0.0",
                "google-cloud-aiplatform[agent_engines,adk]>=1.156.0",
                "google-adk[a2a,agent-identity,mcp]>2.7.1",
                "google-genai",
                "httpx",
            ],
        },
    )
    
  2. Setelah deployment selesai, berikan peran Agent Identity User (roles/agentidentity.user) di penyedia autentikasi ke akun utama SPIFFE agen yang di-deploy:

    gcloud agent-identity auth-providers add-iam-policy-binding <var>AUTH_PROVIDER_NAME</var> \
        --project="<var>PROJECT_ID</var>" \
        --location="<var>LOCATION</var>" \
        --role="roles/agentidentity.user" \
        --member="principal://agents.global.org-<var>ORGANIZATION_ID</var>.system.id.goog/resources/aiplatform/projects/<var>PROJECT_NUMBER</var>/locations/<var>LOCATION</var>/reasoningEngines/<var>ENGINE_ID</var>"
    

    Ganti kode berikut:

    • AUTH_PROVIDER_NAME: nama penyedia autentikasi Anda.
    • PROJECT_ID: ID project Anda.
    • LOCATION: region tempat penyedia autentikasi dan agen Anda di-deploy (misalnya, us-central1).
    • ORGANIZATION_ID: ID organisasi Google Cloud Anda.
    • PROJECT_NUMBER: jumlah project Google Cloud Anda.
    • ENGINE_ID: ID resource agen reasoningEngines yang di-deploy.
  3. Daftarkan agen A2A yang di-deploy ke Gemini Enterprise menggunakan Daftarkan agen A2A ke Gemini Enterprise (Agen kustom melalui A2A) atau Impor agen A2A dari Agent Registry (Agen kustom melalui Agent Runtime). Karena agen dihosting di Agent Runtime, konfigurasikan resource otorisasi OAuth 2.0 di Gemini Enterprise dengan cakupan https://www.googleapis.com/auth/cloud-platform agar Gemini Enterprise dapat memanggil endpoint Agent Runtime.

Mengamankan endpoint agen A2A Anda

Untuk header autentikasi yang dikirim Gemini Enterprise ke agen A2A Anda, lihat Cara Gemini Enterprise melakukan autentikasi dengan agen Anda. Saat Anda mengamankan endpoint agen, atau gateway API di depannya, pertimbangkan hal berikut:

  • Skema keamanan kartu agen: Gemini Enterprise tidak menggunakan kolom securitySchemes dan security kartu agen Anda untuk melakukan autentikasi dengan agen Anda.
  • Kunci API dan header kustom: Gemini Enterprise tidak mendukung skema keamanan apiKey, dan tidak menyediakan cara untuk menambahkan kunci API statis atau nilai header kustom lainnya ke permintaan yang dikirim ke agen Anda.
  • Token ID agen layanan: Gemini Enterprise mengirimkan header X-Serverless-Authorization hanya jika URL agen Anda adalah URL Cloud Run default yang diakhiri dengan .run.app. Jika URL agen Anda menggunakan domain kustom, load balancer, atau gateway API, Gemini Enterprise tidak akan mengirim header ini.
  • Token pengguna akhir: Jika Anda mengonfigurasi OAuth 2.0 untuk agen Anda, Gemini Enterprise akan mengirimkan token pengguna akhir dari penyedia OAuth 2.0 Anda di header Authorization.

Mengamankan endpoint agen dengan Apigee

Jika Anda mengekspos agen A2A melalui proxy API Apigee, proxy akan menerima token pengguna akhir di header Authorization, tetapi tidak menerima header X-Serverless-Authorization. Untuk mengamankan proxy, lakukan hal berikut:

  1. Konfigurasikan OAuth 2.0 untuk otorisasi pengguna akhir untuk agen Anda (menggunakan Google Cloud client ID OAuth 2.0 atau penyedia OAuth 2.0 pihak ketiga), dan berikan detail OAuth 2.0 tersebut saat Anda mendaftarkan agen. Mengonfigurasi OAuth 2.0 diperlukan saat mengamankan proxy API Apigee; jangan lewati langkah otorisasi selama pendaftaran.
  2. Di kartu agen, tetapkan url ke URL proxy API Apigee Anda.
  3. Di proxy API, validasi token pengguna akhir di header Authorization sebelum Anda meneruskan permintaan ke agen. Pilih kebijakan Apigee berdasarkan format token yang dikeluarkan oleh penyedia OAuth 2.0 Anda:
    • Penyedia OAuth 2.0 pihak ketiga yang menerbitkan token akses JWT yang ditandatangani: Gunakan kebijakan VerifyJWT untuk memverifikasi tanda tangan token terhadap URI JSON Web Key Set (JWKS) publik penyedia Anda dan memvalidasi klaim penerbit (iss) dan audiens (aud).
    • Google OAuth 2.0 (accounts.google.com): Token akses Google OAuth 2.0 (ya29...) adalah token buram, bukan JWT yang ditandatangani. Gunakan kebijakan ServiceCallout untuk memanggil https://oauth2.googleapis.com/tokeninfo dan memverifikasi kolom audiens (aud) dan scope.

Mendaftarkan agen A2A ke Gemini Enterprise

Anda dapat mendaftarkan agen A2A ke Gemini Enterprise menggunakan konsolGoogle Cloud atau REST API. Tindakan ini akan membuat agen tersedia bagi pengguna dalam aplikasi Gemini Enterprise.

Konsol

Untuk mendaftarkan agen A2A menggunakan konsol Google Cloud , ikuti langkah-langkah berikut:

  1. Di konsol Google Cloud , buka halaman Gemini Enterprise.

    Gemini Enterprise

  2. Klik nama aplikasi yang ingin Anda daftarkan dengan agen.

  3. Klik Agents > Add Agents.

  4. Di bagian Choose an agent type, klik Add untuk Custom agent via A2A.

  5. Di kolom Agent card JSON, masukkan detail kartu agen dalam format JSON. Untuk mengetahui daftar lengkap kolom yang tersedia, lihat Spesifikasi Resmi Protokol Agent2Agent (A2A). Contoh berikut hanya menggunakan kolom wajib diisi.

    Contoh:

    {
      "protocolVersion": "0.3",
      "name": "Hello World Agent",
      "description": "Just a hello world agent",
      "url": "https://example.com/myagent",
      "iconUrl": "data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iOTkiIGhlaWdodD0iOTkiIHN0eWxlPSJiYWNrZ3JvdW5kLWNvbG9yOmdyYXk7IiB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciPjxwYXRoIGQ9Ik0zMyAwaDMzdjMzSDMzeiBNMCAzM2gzM3YzM0gweiBNNjYgMzNoMzN2MzNINjZ6IE0zMyA2NmgzM3YzM0gzM3oiIGZpbGw9ImJsdWUiLz48L3N2Zz4=",
      "version": "1.0.0",
      "capabilities": {
      },
      "skills": [
        {
          "id": "data-analysis",
          "name": "Data Analysis",
          "description": "Data analysis",
          "tags": []
        }
      ],
      "defaultInputModes": [
        "text/plain"
      ],
      "defaultOutputModes": [
        "text/plain"
      ]
    }
    
  6. Klik Pratinjau detail agen > Berikutnya.

  7. Selesaikan penyiapan menggunakan salah satu metode berikut:

    • Jika Anda tidak ingin agen mengakses resource Google Cloud atas nama Anda dan endpoint agen Anda tidak memerlukan header Authorization, klik Skip & Finish untuk melewati langkah ini.
    • Jika Anda telah mengonfigurasi 3LO dengan pengelola autentikasi, klik Skip & Finish dan agen akan meminta akses secara dinamis.
    • Jika Anda belum mengonfigurasi 3LO dengan pengelola autentikasi atau endpoint agen Anda memerlukan header Authorization (misalnya, saat mengamankan proxy API Apigee), ikuti langkah-langkah berikut:

      1. Masukkan Client ID, Client secret, Authorization URI, dan Token URI yang Anda buat di Mengonfigurasi OAuth 2.0 untuk otorisasi pengguna akhir (opsional).

      2. Masukkan Cakupan.

      3. Klik Selesai.

REST

Untuk mendaftarkan agen A2A menggunakan REST API, ikuti langkah-langkah berikut:

Menambahkan resource otorisasi ke Gemini Enterprise (opsional)

Jika agen harus mengakses resource Google Cloud atas nama pengguna, jalankan perintah berikut untuk mendaftarkan resource otorisasi yang Anda buat di bagian Mengonfigurasi detail otorisasi (opsional) dengan Gemini Enterprise:

curl -X POST \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   -H "X-Goog-User-Project: PROJECT_ID" \
   "https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_NUMBER/locations/LOCATION/authorizations?authorizationId=AUTH_ID" \
   -d '{
      "name": "projects/PROJECT_NUMBER/locations/LOCATION/authorizations/AUTH_ID",
      "serverSideOauth2": {
         "clientId": "OAUTH_CLIENT_ID",
         "clientSecret": "OAUTH_CLIENT_SECRET",
         "authorizationUri": "OAUTH_AUTH_URI",
         "tokenUri": "OAUTH_TOKEN_URI"
      }
   }'

Ganti kode berikut:

  • PROJECT_ID: ID project Anda.
  • PROJECT_NUMBER: jumlah project Google Cloud Anda.
  • ENDPOINT_LOCATION: multi-region untuk permintaan API Anda. Tentukan salah satu nilai berikut:
    • us untuk multi-region AS
    • eu untuk multi-region Uni Eropa
    • global untuk lokasi Global
    Untuk mengetahui informasi selengkapnya, lihat Menentukan multi-region untuk penyimpanan data Anda.
  • LOCATION: multi-region penyimpanan data Anda: global, us, atau eu
  • AUTH_ID: ID resource otorisasi. Ini adalah ID alfanumerik arbitrer yang Anda tentukan. Anda harus merujuk ID ini nanti saat mendaftarkan Agen yang memerlukan dukungan OAuth.
  • OAUTH_CLIENT_ID: ID klien OAuth 2.0 yang Anda peroleh saat membuat kredensial OAuth.
  • OAUTH_CLIENT_SECRET: rahasia klien OAuth 2.0 yang Anda peroleh saat membuat kredensial OAuth.
  • OAUTH_AUTH_URI: URI Otorisasi. Untuk mengizinkan aplikasi Anda, buat URI Otorisasi tertentu menggunakan detail dari file JSON kredensial OAuth Anda. Salin template berikut, dan ganti placeholder dengan nilai spesifik Anda.

    https://accounts.google.com/o/oauth2/v2/auth?client_id=OAUTH_CLIENT_ID&redirect_uri=https%3A%2F%2Fvertexaisearch.cloud.google.com%2Fstatic%2Foauth%2Foauth.html&scope=YOUR_CUSTOM_SCOPES&include_granted_scopes=true&response_type=code&access_type=offline&prompt=consent
    
    • YOUR_CUSTOM_SCOPES: Anda dapat menambahkan cakupan yang diperlukan. Misalnya, string cakupan OAuth berikut meminta akses hanya baca ke Google Drive dan Google Dokumen Anda.

      scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fdrive.readonly%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fdocuments.readonly
      
  • OAUTH_TOKEN_URI: URI token yang Anda peroleh saat membuat kredensial OAuth.

Informasi selengkapnya tentang parameter URI Otorisasi.

Untuk membantu memastikan URI berfungsi dengan benar, verifikasi kolom berikut:

Parameter Nilai atau tindakan
client_id Ganti dengan client_id yang ditemukan di JSON yang Anda download.
redirect_uri Jangan ubah. Harus berupa https://vertexaisearch.cloud.google.com/static/oauth/oauth.html.
scope

Cantumkan cakupan Google API yang perlu diakses aplikasi Anda atas nama pengguna. Misalnya, untuk memberikan akses ke BigQuery, gunakan cakupan https://www.googleapis.com/auth/bigquery dan untuk akses hanya baca ke Google Dokumen, gunakan https://www.googleapis.com/auth/documents.readonly.

Jika Anda menggunakan beberapa cakupan, pisahkan dengan spasi, yang menjadi %20 di URL.

include_granted_scopes Harus berupa true.
response_type Harus berusia code tahun untuk menerima kode otorisasi.
access_type Tetapkan ke offline untuk membantu memastikan bahwa Anda menerima token refresh.
prompt Tetapkan ke consent untuk membantu memastikan bahwa pengguna selalu melihat layar izin.

Mendaftarkan agen A2A Anda

Untuk membuat dan mendaftarkan agen ke Gemini Enterprise, gunakan metode agents.create. Perintah berikut hanya menggunakan kolom yang wajib diisi. Untuk mengetahui daftar lengkap kolom yang tersedia, lihat Spesifikasi Resmi Protokol Agent2Agent (A2A).

Jalankan perintah ini untuk mendaftarkan agen A2A Anda ke Gemini Enterprise:

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents \
-d '
{
  "name": "AGENT_NAME",
  "displayName": "AGENT_DISPLAY_NAME",
  "description": "AGENT_DESCRIPTION",
  "a2aAgentDefinition": {
    "jsonAgentCard": "{\"protocolVersion\":\"PROTOCOLVERSION\",\"name\":\"AGENT_NAME\",\"description\":\"AGENT_DESCRIPTION\",\"url\":\"AGENT_URL\",\"version\":\"AGENT_VERSION\",\"defaultInputModes\":[\"INPUT_MODE\"],\"defaultOutputModes\":[\"OUTPUT_MODE\"],\"capabilities\":{ CAPABILITIES },\"skills\":[SKILLS]}"
  },
  "authorizationConfig": {
    "agentAuthorization": "projects/PROJECT_ID/locations/LOCATION/authorizations/AUTH_ID"
  }
}
'

Ganti kode berikut:

  • ENDPOINT_LOCATION: multi-region untuk permintaan API Anda. Tentukan salah satu nilai berikut:
    • us untuk multi-region AS
    • eu untuk multi-region Uni Eropa
    • global untuk lokasi Global
    Untuk mengetahui informasi selengkapnya, lihat Menentukan multi-region untuk penyimpanan data Anda.
  • LOCATION: multi-region penyimpanan data Anda: global, us, atau eu
  • PROJECT_ID: ID project Anda.
  • APP_ID: ID aplikasi yang ingin Anda daftarkan ke agen.
  • AGENT_NAME: ID unik untuk agen.
  • AGENT_DISPLAY_NAME: nama agen yang ditampilkan di aplikasi web.
  • AGENT_DESCRIPTION: deskripsi tentang hal yang dapat dilakukan agen.
  • PROTOCOLVERSION: versi protokol A2A yang didukung agen. Untuk mengetahui informasi selengkapnya tentang versi yang didukung, lihat catatan rilis A2A.
  • AGENT_URL: URL endpoint agen.
  • AGENT_VERSION: versi agen.
  • INPUT_MODE: jenis media input default. Misalnya, application/json atau text/plain.
  • OUTPUT_MODE: jenis media output default. Misalnya, text/plain" atau image/png.
  • CAPABILITIES: objek JSON yang berisi fitur A2A yang didukung. Misalnya \"streaming\": true atau \"pushNotifications\": false.
  • SKILLS: daftar objek AgentSkill yang ditawarkan agen.
  • authorizationConfig: Jika Anda telah mendapatkan detail otorisasi dan ingin agen mengakses resource Google Cloud atas nama pengguna, tambahkan kolom authorization_config ke resource JSON Anda.

Menampilkan informasi penulis dan kontak untuk agen (opsional)

Secara default, agen A2A yang Anda daftarkan tidak menampilkan penulis di Gemini Enterprise. Untuk menampilkan siapa yang membuat agen dan siapa yang dapat dihubungi pengguna tentang agen tersebut, tambahkan ekstensi metadata agen ke kolom capabilities.extensions JSON kartu agen yang Anda gunakan untuk mendaftarkan atau memperbarui agen:

{
  "capabilities": {
    "extensions": [
      {
        "uri": "https://www.googleapis.com/gemini-enterprise/a2a/extensions/agent_metadata/v1",
        "params": {
          "authorName": "Example Team",
          "contactEmail": "agent-support@example.com"
        }
      }
    ]
  }
}

Pertahankan kolom kartu agen lainnya dari contoh pendaftaran bersama dengan capabilities. Di REST API, ekstensi adalah bagian dari string jsonAgentCard yang di-escape.

Kolom params mendukung nilai berikut. Keduanya bersifat opsional.

Parameter Deskripsi
authorName Nama orang, tim, atau perusahaan yang membuat agen. Galeri agen menampilkannya sebagai Oleh AUTHOR_NAME di kartu agen, dan dialog Info Agen menampilkannya sebagai Penulis. Galeri hanya menampilkan nama ini jika agen tidak memiliki nama pemiliknya sendiri. Nama yang berisi kata "Google" tidak ditampilkan, agar tidak disalahartikan sebagai agen yang dibuat oleh Google.
contactEmail Alamat email yang dapat digunakan pengguna untuk menghubungi penulis. Dialog Agent Info menampilkannya sebagai Contact.

Setiap nilai harus berupa string maksimal 256 karakter, dan contactEmail harus berupa alamat email yang valid. Gemini Enterprise mengabaikan nilai yang tidak memenuhi persyaratan ini. Gemini Enterprise tidak memverifikasi nama penulis atau email kontak.

Mencantumkan agen yang terhubung ke aplikasi

Contoh kode berikut menunjukkan cara mendapatkan detail semua agen yang terhubung ke aplikasi Anda:

REST

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents"

Ganti variabel dengan nilai:

  • ENDPOINT_LOCATION: multi-region untuk permintaan API Anda. Tentukan salah satu nilai berikut:
    • us untuk multi-region AS
    • eu untuk multi-region Uni Eropa
    • global untuk lokasi Global
    Untuk mengetahui informasi selengkapnya, lihat Menentukan multi-region untuk penyimpanan data Anda.
  • PROJECT_ID: ID project Google Cloud Anda.
  • LOCATION: multi-region aplikasi Anda: global, us, atau eu.
  • APP_ID: ID aplikasi Gemini Enterprise Anda.

Jika agen Anda tidak dibuat otomatis oleh Google, responsnya akan menyertakan kolom name di beberapa baris pertama. Nilai kolom ini berisi ID Agen di akhir jalur. Misalnya, dalam respons berikut, ID Agen adalah 12345678901234567890:

{
"name": "projects/123456/locations/global/collections/default_collection/engines/my-app/assistants/default_assistant/agents/12345678901234567890",
...
}

Melihat detail agen A2A

Contoh kode berikut menunjukkan cara mengambil detail agen yang terdaftar di Gemini Enterprise:

REST

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents/AGENT_ID"

Ganti variabel dengan nilai:

  • ENDPOINT_LOCATION: multi-region untuk permintaan API Anda. Tentukan salah satu nilai berikut:
    • us untuk multi-region AS
    • eu untuk multi-region Uni Eropa
    • global untuk lokasi Global
    Untuk mengetahui informasi selengkapnya, lihat Menentukan multi-region untuk penyimpanan data Anda.
  • PROJECT_ID: ID project Google Cloud Anda.
  • LOCATION: multi-region aplikasi Anda: global, us, atau eu.
  • APP_ID: ID aplikasi Gemini Enterprise Anda.
  • AGENT_ID: ID agen. Anda dapat menemukan ID agen dengan mencantumkan agen yang terhubung ke aplikasi Anda.

Mengupdate agen A2A

Anda dapat mengubah detail agen A2A yang ada yang terdaftar di Gemini Enterprise menggunakan konsol Google Cloud atau REST API.

Konsol

Untuk mengupdate agen A2A menggunakan konsol Google Cloud , ikuti langkah-langkah berikut:

  1. Di konsol Google Cloud , buka halaman Gemini Enterprise.

    Gemini Enterprise

  2. Klik nama aplikasi yang menyertakan agen yang ingin Anda perbarui.

  3. Klik Agents.

  4. Klik nama agen A2A (Custom) yang akan diupdate, lalu klik Edit.

  5. Di kolom Agent card JSON, perbarui detail kartu agen dalam format JSON. Untuk mengetahui daftar lengkap kolom yang tersedia, lihat Spesifikasi Resmi Protokol Agent2Agent (A2A). Contoh berikut hanya menggunakan kolom wajib diisi.

    Contoh:

    {
      "protocolVersion": "0.3",
      "name": "Hello World Agent",
      "description": "Just a hello world agent",
      "url": "https://example.com/myagent",
      "iconUrl": "data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iOTkiIGhlaWdodD0iOTkiIHN0eWxlPSJiYWNrZ3JvdW5kLWNvbG9yOmdyYXk7IiB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciPjxwYXRoIGQ9Ik0zMyAwaDMzdjMzSDMzeiBNMCAzM2gzM3YzM0gweiBNNjYgMzNoMzN2MzNINjZ6IE0zMyA2NmgzM3YzM0gzM3oiIGZpbGw9ImJsdWUiLz48L3N2Zz4=",
      "version": "1.1.0",
      "capabilities": {
      },
      "skills": [
        {
          "id": "data-analysis",
          "name": "Data Analysis",
          "description": "Data analysis",
          "tags": []
        }
      ],
      "defaultInputModes": [
        "text/plain"
      ],
      "defaultOutputModes": [
        "text/plain"
      ]
    }
    
  6. Klik Simpan.

REST

Untuk memperbarui detail agen A2A yang terdaftar di Gemini Enterprise, gunakan metode agents.patch. Perintah berikut hanya menggunakan kolom yang wajib diisi. Untuk mengetahui daftar lengkap kolom yang tersedia, lihat Spesifikasi Resmi Protokol Agent2Agent (A2A).

Jalankan perintah ini untuk mengupdate agen A2A Anda dengan Gemini Enterprise:

curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents/AGENT_ID \
-d '
{
  "name": "AGENT_NAME",
  "displayName": "AGENT_DISPLAY_NAME",
  "description": "AGENT_DESCRIPTION",
  "a2aAgentDefinition": {
    "jsonAgentCard": "{\"protocolVersion\":\"PROTOCOLVERSION\",\"name\":\"AGENT_NAME\",\"description\":\"AGENT_DESCRIPTION\",\"url\":\"AGENT_URL\",\"version\":\"AGENT_VERSION\",\"defaultInputModes\":[\"INPUT_MODE\"],\"defaultOutputModes\":[\"OUTPUT_MODE\"],\"capabilities\":{ CAPABILITIES },\"skills\":[SKILLS]}"
  },
  "authorizationConfig": {
    "agentAuthorization": "projects/PROJECT_ID/locations/LOCATION/authorizations/AUTH_ID"
  }
}
'

Ganti kode berikut:

  • ENDPOINT_LOCATION: multi-region untuk permintaan API Anda. Tentukan salah satu nilai berikut:
    • us untuk multi-region AS
    • eu untuk multi-region Uni Eropa
    • global untuk lokasi Global
    Untuk mengetahui informasi selengkapnya, lihat Menentukan multi-region untuk penyimpanan data Anda.
  • LOCATION: multi-region penyimpanan data Anda: global, us, atau eu.
  • PROJECT_ID: ID project Anda.
  • APP_ID: ID aplikasi tempat Anda ingin mendaftarkan agen.
  • AGENT_ID: ID agen. Anda dapat menemukan ID agen dengan mencantumkan agen yang terhubung ke aplikasi Anda.
  • AGENT_NAME: ID unik untuk agen.
  • AGENT_DISPLAY_NAME: nama agen yang ditampilkan di aplikasi web.
  • AGENT_DESCRIPTION: deskripsi tentang hal yang dapat dilakukan agen.
  • PROTOCOLVERSION: versi protokol A2A yang didukung agen. Untuk mengetahui informasi selengkapnya tentang versi yang didukung, lihat catatan rilis A2A.
  • AGENT_URL: URL endpoint agen.
  • AGENT_VERSION: versi agen.
  • INPUT_MODE: jenis media input default. Misalnya, application/json atau text/plain.
  • OUTPUT_MODE: jenis media output default. Misalnya, text/plain atau image/png.
  • CAPABILITIES: objek JSON yang berisi fitur A2A yang didukung. Misalnya \"streaming\": true atau \"pushNotifications\": false.
  • SKILLS: daftar objek AgentSkill yang ditawarkan agen.
  • authorizationConfig: Jika Anda telah mendapatkan detail otorisasi dan ingin agen mengakses resource Google Cloud atas nama pengguna, tambahkan kolom authorization_config ke resource JSON Anda.

Menghapus agen A2A

Contoh kode berikut menunjukkan cara menghapus agen yang terhubung ke aplikasi Anda:

REST

curl -X DELETE \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents/AGENT_ID"

Ganti variabel dengan nilai:

  • ENDPOINT_LOCATION: multi-region untuk permintaan API Anda. Tentukan salah satu nilai berikut:
    • us untuk multi-region AS
    • eu untuk multi-region Uni Eropa
    • global untuk lokasi Global
    Untuk mengetahui informasi selengkapnya, lihat Menentukan multi-region untuk penyimpanan data Anda.
  • PROJECT_ID: ID project Google Cloud Anda.
  • LOCATION: multi-region aplikasi Anda: global, us, atau eu
  • APP_ID: ID aplikasi Gemini Enterprise Anda.
  • AGENT_ID: ID agen. Anda dapat menemukan ID agen dengan mencantumkan agen yang terhubung ke aplikasi Anda.

Langkah berikutnya

  • Gunakan agen yang Anda daftarkan ke Gemini Enterprise di aplikasi web.