Registrare e gestire gli agenti A2A

Il protocollo Agent2Agent (A2A) è un protocollo di comunicazione aperto e un linguaggio universale per gli agenti. Il protocollo consente agli agenti di diversi builder e piattaforme di scoprirsi a vicenda, collaborare e delegare le attività in modo sicuro. Questo documento spiega come gli amministratori di Gemini Enterprise possono connettere a Gemini Enterprise gli agenti creati utilizzando A2A e ospitati su qualsiasi piattaforma, rendendoli disponibili agli utenti nell'app web Gemini Enterprise.

Prima di iniziare

Assicurati di disporre di quanto segue:

  • Il ruolo Gemini Enterprise Admin.

  • Abilita l'API Discovery Engine. Per abilitare l'API Discovery Engine per il progetto Google Cloud, nella console Google Cloud , vai alla pagina API Discovery Engine.

    Vai all'API Discovery Engine

  • Un'app Gemini Enterprise esistente. Per creare un'app, consulta Crea un'app.

  • Un agente che utilizza il protocollo A2A.

    Gemini Enterprise supporta il meccanismo di streaming A2A v0.3.

    Se utilizzi A2A v1.0.0 o versioni successive, utilizza i pacchetti di compatibilità forniti dall'SDK per assicurarti che l'agente funzioni con il meccanismo precedente (ad esempio, il pacchetto a2acompat/a2av0 per Go o il pacchetto a2a.compat.v0_3 per Python).

  • Se l'agente A2A è ospitato su Cloud Run, utilizza direttamente un URL .run.app predefinito e richiede l'autenticazione, concedi il ruolo Cloud Run Invoker (roles/run.invoker) all'agente di servizio Discovery Engine (questo non si applica quando Cloud Run è dietro Apigee, un bilanciatore del carico o un dominio personalizzato):

    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"
    

    Sostituisci quanto segue:

    • PROJECT_ID: l'ID progetto.
    • PROJECT_NUMBER: il numero del tuo progetto Google Cloud .

Configura l'autenticazione e l'autorizzazione

A seconda dell'ambiente di hosting dell'agente e dei requisiti di sicurezza, puoi configurare il modo in cui Gemini Enterprise si autentica con l'agente, il modo in cui l'agente accede alle risorse e agli strumenti downstream per conto dell'utente finale e il modo in cui proteggere l'endpoint dell'agente:

Come Gemini Enterprise si autentica con il tuo agente

Quando Gemini Enterprise richiama un agente A2A, può inviare dati di autenticazione e autorizzazione nelle intestazioni della richiesta a seconda della configurazione di hosting e sicurezza:

Intestazione Descrizione
X-Serverless-Authorization

Autenticazione IAM service-to-service (per Cloud Run).

Se l'agente A2A è ospitato su Cloud Run e l'URL dell'agente è un URL .run.app predefinito, Gemini Enterprise genera automaticamente un token ID OIDC firmato da Google per l'agente di servizio Discovery Engine (service-PROJECT_NUMBER@gcp-sa-discoveryengine.iam.gserviceaccount.com) con l'URL dell'agente come pubblico e lo allega nell'intestazione X-Serverless-Authorization. Se l'URL dell'agente utilizza Apigee, un bilanciatore del carico o un dominio personalizzato, Gemini Enterprise non invia questa intestazione.

Quando Gemini Enterprise chiama direttamente un URL .run.app predefinito, l'infrastruttura di traffico in entrata di Cloud Run utilizza questa intestazione per verificare che l'agente di servizio disponga del ruolo IAM roles/run.invoker (consulta Prima di iniziare) prima di inoltrare la richiesta al container dell'applicazione.

Authorization

Autorizzazione OAuth 2.0 dell'utente finale (per la chiamata dell'endpoint, il contesto utente e l'accesso all'API).

Se configuri le credenziali OAuth 2.0 per l'agente A2A (consulta Configura OAuth 2.0 per l'autorizzazione dell'utente finale), Gemini Enterprise acquisisce un token di accesso o un token ID OAuth 2.0 per conto dell'utente finale che ha eseguito l'accesso dopo che ha concesso il consenso e lo invia nell'intestazione Authorization standard (ad esempio, Bearer USER_OAUTH_TOKEN).

Per gli agenti ospitati su Cloud Run, Cloud Run inoltra l'intestazione Authorization direttamente al container, consentendo al codice dell'applicazione dell'agente di leggere il token utente e chiamare le API downstream per conto dell'utente. Per gli agenti A2A ospitati su Agent Runtime, la configurazione di una risorsa di autorizzazione OAuth 2.0 con l'ambito https://www.googleapis.com/auth/cloud-platform consente a Gemini Enterprise di autenticarsi nell'endpoint Agent Runtime per conto dell'utente.

Configura OAuth 2.0 per l'autorizzazione dell'utente finale (facoltativo)

Per gli agenti A2A, configura le credenziali OAuth 2.0 in Gemini Enterprise se l'Agent Endpoint richiede un token OAuth 2.0 dell'utente finale nell'intestazione Authorization (ad esempio, per richiamare un agente A2A ospitato su Agent Runtime o per passare un token utente direttamente al container dell'agente). Per saperne di più su come funzionano le intestazioni di autenticazione e autorizzazione, consulta In che modo Gemini Enterprise esegue l'autenticazione con l'agente.

Se l'agente A2A utilizza il gestore di autenticazione di Agent Identity per OAuth a tre vie a livello di strumento (ad esempio per accedere ai server MCP o alle API di terze parti per conto dell'utente), consulta Configura OAuth a tre vie con il gestore di autenticazione di Agent Identity.

Per creare un ID client OAuth, segui questi passaggi:

  1. Nella console Google Cloud , nella pagina API e servizi, vai alla pagina Credenziali.

    Vai a credenziali

  2. Seleziona il progetto Google Cloud , che contiene l'origine dati a cui vuoi che l'agente acceda. Ad esempio, seleziona il progetto che contiene il set di dati BigQuery su cui vuoi che l'agente esegua query.

  3. Fai clic su Crea credenziali e seleziona ID client OAuth.

  4. In Tipo di applicazione, seleziona Applicazione web.

  5. Nella sezione URI di reindirizzamento autorizzati, aggiungi i seguenti URI:

    • https://vertexaisearch.cloud.google.com/oauth-redirect
    • https://vertexaisearch.cloud.google.com/static/oauth/oauth.html
  6. Fai clic su Crea.

  7. Nel riquadro Client OAuth creato, fai clic su Scarica JSON. Il file JSON scaricato include Client ID, Authorization URI, Token URI e Client secret per il progetto Google Cloud selezionato. Questi dettagli sono necessari per creare una risorsa di autorizzazione.

(Facoltativo) Configura OAuth a tre vie con il gestore di autenticazione di Agent Identity

Se l'agente A2A è creato con l'Agent Development Kit (ADK) e utilizza il gestore di autenticazione di Agent Identity per OAuth a tre vie (3LO), può autenticarsi con i server MCP, Google Cloudi servizi o le API di terze parti downstream per conto dell'utente che ha eseguito l'accesso.

Quando uno strumento nell'agente A2A richiede il consenso dell'utente, Gemini Enterprise gestisce automaticamente il workflow 3LO lato client:

  1. Richiesta di consenso: quando l'agente restituisce un'interruzione dello strumento adk_request_credential (TASK_STATE_AUTH_REQUIRED), l'app web Gemini Enterprise chiede all'utente di accedere e apre l'URI di autorizzazione del provider di autenticazione.
  2. Convalida dell'utente e archiviazione dei token: dopo che l'utente ha concesso il consenso, il provider di autenticazione reindirizza all'endpoint di convalida di Gemini Enterprise (https://vertexaisearch.cloud.google.com/validateUserId). Gemini Enterprise convalida lo stato della sessione e finalizza le credenziali con il gestore di autenticazione di Agent Identity.
  3. Ripresa della conversazione: Gemini Enterprise invia la risposta adk_request_credential completata al tuo agente A2A, che recupera il token di accesso dell'utente dal provider di autenticazione e richiama lo strumento.

Poiché Gemini Enterprise gestisce la richiesta di consenso, l'endpoint di convalida e la ripresa della conversazione, non è necessario implementare un'applicazione UI lato client personalizzata.

Passaggio 1: configura un provider di autenticazione OAuth a tre vie

Segui i passaggi descritti in Autentica utilizzando OAuth a tre vie con Auth Manager per abilitare l'API Agent Identity (agentidentity.googleapis.com), configurare l'applicazione client OAuth e creare un provider di autenticazione OAuth a tre vie.

Quando configuri il client OAuth e il provider di autenticazione da utilizzare con Gemini Enterprise, includi le seguenti impostazioni:

  • URI di reindirizzamento autorizzati: nella configurazione del client OAuth, aggiungi l'URI di reindirizzamento di callback del provider di autenticazione:

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

    Se riutilizzi lo stesso client OAuth per la risorsa di autorizzazione dell'agente Gemini Enterprise (ad esempio, per consentire a Gemini Enterprise di richiamare un agente A2A ospitato su Agent Runtime), includi anche l'URI di reindirizzamento di Gemini Enterprise (https://vertexaisearch.cloud.google.com/oauth-redirect).

  • URI di continuazione: imposta l'URI di continuazione (come URI di continuazione predefinito sul provider di autenticazione o come continue_uri nel codice dell'agente) sull'endpoint di convalida di Gemini Enterprise:

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

Passaggio 2: configura il codice agente A2A

Quando crei un agente ADK e lo racchiudi con A2aAgent per il deployment su Agent Runtime, assicurati che il codice dell'agente soddisfi i seguenti requisiti:

  • Installa le versioni dei pacchetti richieste: includi a2a-sdk[http-server]>=1.0.0, google-cloud-aiplatform[agent_engines,adk]>=1.156.0 e google-adk[a2a,agent-identity,mcp]>2.7.1 nei requisiti di deployment.
  • Imposta continue_uri su Gemini Enterprise: imposta continue_uri su "https://vertexaisearch.cloud.google.com/validateUserId" in GcpAuthProviderScheme o AgentRegistry.get_mcp_toolset (a meno che tu non lo abbia configurato come URI di continuazione predefinito sul provider di autenticazione).
  • Registra GcpAuthProvider all'interno della funzione di creazione del runner: chiama CredentialManager.register_auth_provider(GcpAuthProvider()) all'interno della funzione che crea Runner nel processo worker del container di cui è stato eseguito il deployment, anziché solo al livello superiore del modulo.
  • Utilizza il A2aAgentExecutor integrato: passa A2aAgentExecutor(runner=build_runner) (from google.adk.a2a.executor.a2a_agent_executor import A2aAgentExecutor) a A2aAgent. Non utilizzare un AgentExecutor personalizzato che controlla solo event.is_final_response(), perché A2aAgentExecutor è necessario per convertire le interruzioni adk_request_credential nello stato dell'attività A2A TASK_STATE_AUTH_REQUIRED.
  • Includi la versione 0.3 del protocollo A2A su AgentCard: aggiungi un AgentInterface con protocol_version=PROTOCOL_VERSION_0_3 e protocol_binding=TransportProtocol.HTTP_JSON a agent_card.supported_interfaces insieme all'interfaccia 1.0 predefinita in modo che Gemini Enterprise possa comunicare con il tuo agente tramite le route A2A v0.3.

ADK + A2A

L'esempio seguente configura un agente ADK A2A che utilizza GcpAuthProviderScheme con McpToolset (o AgentRegistry.get_mcp_toolset) per autenticarsi su un server MCP per conto dell'utente:

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

L'esempio seguente configura un agente ADK A2A che utilizza AuthenticatedFunctionTool con GcpAuthProviderScheme per chiamare un'API REST di terze parti o Google Cloudper conto dell'utente:

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

Passaggio 3: esegui il deployment dell'agente A2A con l'identità dell'agente e concedi l'accesso

  1. Esegui il deployment di A2aAgent in Agent Runtime con 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. Al termine del deployment, concedi il ruolo Utente identità agente (roles/agentidentity.user) nel provider di autenticazione all'entità SPIFFE dell'agente di cui è stato eseguito il deployment:

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

    Sostituisci quanto segue:

    • AUTH_PROVIDER_NAME: il nome del provider di autenticazione.
    • PROJECT_ID: l'ID progetto.
    • LOCATION: la regione in cui è stato eseguito il deployment del provider di autenticazione e dell'agente (ad esempio, us-central1).
    • ORGANIZATION_ID: il tuo ID organizzazione Google Cloud.
    • PROJECT_NUMBER: il numero del tuo progetto Google Cloud .
    • ENGINE_ID: l'ID risorsa dell'agente reasoningEngines di cui hai eseguito il deployment.
  3. Registra l'agente A2A di cui è stato eseguito il deployment con Gemini Enterprise utilizzando Registra un agente A2A con Gemini Enterprise (Agente personalizzato tramite A2A) o Importa agenti A2A da Agent Registry (Agente personalizzato tramite Agent Runtime). Poiché l'agente è ospitato su Agent Runtime, configura una risorsa di autorizzazione OAuth 2.0 in Gemini Enterprise con l'ambito https://www.googleapis.com/auth/cloud-platform in modo che Gemini Enterprise possa richiamare l'endpoint Agent Runtime.

Proteggi l'endpoint dell'agente A2A

Per le intestazioni di autenticazione che Gemini Enterprise invia al tuo agente A2A, consulta In che modo Gemini Enterprise esegue l'autenticazione con il tuo agente. Quando proteggi l'Agent Endpoint o un API Gateway di fronte, tieni presente quanto segue:

  • Schemi di sicurezza della scheda dell'agente: Gemini Enterprise non utilizza i campi securitySchemes e security della scheda dell'agente per l'autenticazione con l'agente.
  • Chiavi API e intestazioni personalizzate: Gemini Enterprise non supporta lo schema di sicurezza apiKey e non fornisce un modo per aggiungere chiavi API statiche o altri valori di intestazione personalizzati alle richieste che invia al tuo agente.
  • Token ID dell'agente di servizio: Gemini Enterprise invia l'intestazione X-Serverless-Authorization solo quando l'URL dell'agente è un URL Cloud Run predefinito che termina con .run.app. Se l'URL dell'agente utilizza un dominio personalizzato, un bilanciatore del carico o un API Gateway, Gemini Enterprise non invia questa intestazione.
  • Token dell'utente finale: se configuri OAuth 2.0 per l'agente, Gemini Enterprise invia il token dell'utente finale dal tuo provider OAuth 2.0 nell'intestazione Authorization.

Proteggi un endpoint dell'agente con Apigee

Se esponi l'agente A2A tramite un proxy API Apigee, il proxy riceve il token dell'utente finale nell'intestazione Authorization, ma non riceve l'intestazione X-Serverless-Authorization. Per proteggere il proxy, segui questi passaggi:

  1. Configura OAuth 2.0 per l'autorizzazione dell'utente finale per il tuo agente (utilizzando un ID client OAuth 2.0 Google Cloud o un provider OAuth 2.0 di terze parti) e fornisci i dettagli di OAuth 2.0 quando registri l'agente. La configurazione di OAuth 2.0 è obbligatoria quando proteggi un proxy API Apigee; non saltare il passaggio di autorizzazione durante la registrazione.
  2. Nella scheda dell'agente, imposta url sull'URL del proxy API Apigee.
  3. Nel proxy API, convalida il token dell'utente finale nell'intestazione Authorization prima di inoltrare la richiesta all'agente. Scegli la policy Apigee in base al formato del token emesso dal tuo provider OAuth 2.0:
    • Provider OAuth 2.0 di terze parti che emettono token di accesso JWT firmati: utilizza la policy VerifyJWT per verificare la firma del token rispetto all'URI del set di chiavi web JSON (JWKS) pubblico del provider e convalidare i claim dell'emittente (iss) e del pubblico (aud).
    • Google OAuth 2.0 (accounts.google.com): i token di accesso Google OAuth 2.0 (ya29...) sono token opachi anziché JWT firmati. Utilizza una policy ServiceCallout per chiamare https://oauth2.googleapis.com/tokeninfo e verificare i campi relativi al pubblico (aud) e scope.

Registra un agente A2A con Gemini Enterprise

Puoi registrare il tuo agente A2A con Gemini Enterprise utilizzando la consoleGoogle Cloud o l'API REST. In questo modo, l'agente sarà disponibile per gli utenti all'interno di un'app Gemini Enterprise.

Console

Per registrare un agente A2A utilizzando la console Google Cloud , segui questi passaggi:

  1. Nella console Google Cloud , vai alla pagina Gemini Enterprise.

    Gemini Enterprise

  2. Fai clic sul nome dell'app con cui vuoi registrare l'agente.

  3. Fai clic su Agenti > Aggiungi agenti.

  4. Nella sezione Scegli un tipo di agente, fai clic su Aggiungi per Agente personalizzato tramite A2A.

  5. Nel campo JSON scheda agente, inserisci i dettagli della scheda agente in formato JSON. Per un elenco completo dei campi disponibili, consulta la specifica ufficiale del protocollo Agent2Agent (A2A). L'esempio seguente utilizza solo i campi obbligatori.

    Ad esempio:

    {
      "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. Fai clic su Visualizza l'anteprima dei dettagli dell'agente > Avanti.

  7. Completa la configurazione utilizzando uno dei seguenti metodi:

    • Se non vuoi che l'agente acceda alle risorse Google Cloud per tuo conto e l'Agent Endpoint non richiede un'intestazione Authorization, fai clic su Salta e termina per saltare questo passaggio.
    • Se hai configurato 3LO con Auth Manager, fai clic su Salta e termina e l'agente richiederà l'accesso in modo dinamico.
    • Se non hai configurato 3LO con il gestore di autenticazione o se l'Agent Endpoint richiede un'intestazione Authorization (ad esempio, quando proteggi un proxy API Apigee), segui questi passaggi:

      1. Inserisci ID client, Client secret, URI di autorizzazione e URI del token che hai generato in Configura OAuth 2.0 per l'autorizzazione dell'utente finale (facoltativo).

      2. Inserisci gli Ambiti.

      3. Fai clic su Fine.

REST

Per registrare un agente A2A utilizzando l'API REST, segui questi passaggi:

(Facoltativo) Aggiungi la risorsa di autorizzazione a Gemini Enterprise

Se l'agente deve accedere alle risorse Google Cloud per conto di un utente, esegui il seguente comando per registrare la risorsa di autorizzazione creata nella sezione Configura i dettagli di autorizzazione (facoltativo) con 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"
      }
   }'

Sostituisci quanto segue:

  • PROJECT_ID: l'ID progetto.
  • PROJECT_NUMBER: il numero del tuo progetto Google Cloud .
  • ENDPOINT_LOCATION: la località multiregionale per la richiesta API. Specifica uno dei seguenti valori:
    • us per la multi-regione Stati Uniti
    • eu per la multi-regione UE
    • global per la località globale
    Per saperne di più, consulta Specifica una multi-regione per il datastore.
  • LOCATION: la località multiregionale del datastore: global, us o eu
  • AUTH_ID: l'ID della risorsa di autorizzazione. Si tratta di un ID alfanumerico arbitrario definito da te. Dovrai fare riferimento a questo ID in un secondo momento, quando registrerai un agente che richiede il supporto di OAuth.
  • OAUTH_CLIENT_ID: l'identificatore client OAuth 2.0 che hai ottenuto quando hai creato le credenziali OAuth.
  • OAUTH_CLIENT_SECRET: il client secret OAuth 2.0 che hai ottenuto quando hai creato le credenziali OAuth.
  • OAUTH_AUTH_URI: l'URI di autorizzazione. Per autorizzare la tua app, crea un URI di autorizzazione specifico utilizzando i dettagli del file JSON delle credenziali OAuth. Copia il seguente template e sostituisci i segnaposto con i tuoi valori specifici.

    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: puoi aggiungere gli ambiti di cui hai bisogno. Ad esempio, la seguente stringa di ambito OAuth richiede l'accesso di sola lettura a Google Drive e Documenti Google.

      scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fdrive.readonly%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fdocuments.readonly
      
  • OAUTH_TOKEN_URI: l'URI del token ottenuto durante la creazione delle credenziali OAuth.

Scopri di più sui parametri URI di autorizzazione.

Per assicurarti che l'URI funzioni correttamente, verifica i seguenti campi:

Parametro Valore o azione
client_id Sostituisci con il valore client_id che si trova nel file JSON scaricato.
redirect_uri Non cambiare. Deve essere https://vertexaisearch.cloud.google.com/static/oauth/oauth.html.
scope

Elenca gli ambiti delle API di Google a cui la tua app deve accedere per conto dell'utente. Ad esempio, per concedere l'accesso a BigQuery, utilizza l'ambito https://www.googleapis.com/auth/bigquery, mentre per l'accesso di sola lettura a Documenti Google, utilizza https://www.googleapis.com/auth/documents.readonly.

Se utilizzi più ambiti, separali con uno spazio, che diventa %20 nell'URL.

include_granted_scopes Deve essere true.
response_type Devi essere code per ricevere un codice di autorizzazione.
access_type Impostalo su offline per assicurarti di ricevere un token di aggiornamento.
prompt Imposta su consent per assicurarti che all'utente venga sempre mostrata una schermata per il consenso.

Registra il tuo agente A2A

Per creare e registrare un agente con Gemini Enterprise, utilizza il metodo agents.create. Il seguente comando utilizza solo i campi obbligatori. Per un elenco completo dei campi disponibili, consulta la specifica ufficiale del protocollo Agent2Agent (A2A).

Esegui questo comando per registrare l'agente A2A con 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"
  }
}
'

Sostituisci quanto segue:

  • ENDPOINT_LOCATION: la località multiregionale per la richiesta API. Specifica uno dei seguenti valori:
    • us per la multi-regione Stati Uniti
    • eu per la multi-regione UE
    • global per la località globale
    Per saperne di più, consulta Specifica una multi-regione per il datastore.
  • LOCATION: la località multiregionale del datastore: global, us o eu
  • PROJECT_ID: l'ID progetto.
  • APP_ID: l'ID dell'app con cui vuoi registrare l'agente.
  • AGENT_NAME: l'identificatore univoco dell'agente.
  • AGENT_DISPLAY_NAME: il nome dell'agente visualizzato nell'app web.
  • AGENT_DESCRIPTION: la descrizione di ciò che l'agente può fare.
  • PROTOCOLVERSION: la versione del protocollo A2A supportata dall'agente. Per saperne di più sulle versioni supportate, consulta le note di rilascio di A2A.
  • AGENT_URL: l'URL dell'endpoint dell'agente.
  • AGENT_VERSION: la versione dell'agente.
  • INPUT_MODE: il tipo di media di input predefinito. Ad esempio, application/json o text/plain.
  • OUTPUT_MODE: il tipo di media di output predefinito. Ad esempio, text/plain" o image/png.
  • CAPABILITIES: un oggetto JSON contenente le funzionalità A2A supportate. Ad esempio: \"streaming\": true o \"pushNotifications\": false.
  • SKILLS: un elenco di oggetti AgentSkill offerti dall'agente.
  • authorizationConfig: se hai ottenuto i dettagli di autorizzazione e vuoi che l'agente acceda alle risorse Google Cloud per conto dell'utente, aggiungi il campo authorization_config alla risorsa JSON.

Mostra l'autore e i dati di contatto di un agente (facoltativo)

Per impostazione predefinita, un agente A2A che registri non mostra alcun autore in Gemini Enterprise. Per mostrare chi ha creato l'agente e chi gli utenti possono contattare in merito, aggiungi l'estensione dei metadati dell'agente al campo capabilities.extensions del file JSON della scheda dell'agente che utilizzi per registrare o aggiornare l'agente:

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

Mantieni gli altri campi della scheda dell'agente dell'esempio di registrazione insieme a capabilities. Nell'API REST, l'estensione fa parte della stringa jsonAgentCard con escape.

Il campo params supporta i valori seguenti. Entrambi sono facoltativi.

Parametro Descrizione
authorName Il nome della persona, del team o dell'azienda che ha creato l'agente. La galleria degli agenti lo mostra come Di AUTHOR_NAME nella scheda dell'agente, mentre la finestra di dialogo Informazioni sull'agente lo mostra come Autore. La galleria mostra questo nome solo quando l'agente non ha un nome del proprietario. I nomi che contengono la parola "Google" non vengono mostrati, in modo che non possano essere scambiati per agenti creati da Google.
contactEmail Un indirizzo email a cui gli utenti possono contattare l'autore. La finestra di dialogo Informazioni sull'agente lo mostra come Contatto.

Ogni valore deve essere una stringa di massimo 256 caratteri e contactEmail deve essere un indirizzo email valido. Gemini Enterprise ignora i valori che non soddisfano questi requisiti. Gemini Enterprise non verifica il nome dell'autore o l'email di contatto.

Elenca gli agenti connessi a un'app

Il seguente esempio di codice mostra come ottenere i dettagli di tutti gli agenti connessi alla tua app:

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"

Sostituisci le variabili con i valori:

  • ENDPOINT_LOCATION: la località multiregionale per la richiesta API. Specifica uno dei seguenti valori:
    • us per la multi-regione Stati Uniti
    • eu per la multi-regione UE
    • global per la località globale
    Per saperne di più, consulta Specifica una multi-regione per il datastore.
  • PROJECT_ID: l'ID del tuo progetto Google Cloud .
  • LOCATION: la località multiregionale della tua app: global, us o eu.
  • APP_ID: l'ID dell'app Gemini Enterprise.

Se l'agente non è predefinito da Google, la risposta include un campo name nelle prime righe. Il valore di questo campo contiene l'ID agente alla fine del percorso. Ad esempio, nella seguente risposta, l'ID agente è 12345678901234567890:

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

Visualizza i dettagli di un agente A2A

Il seguente esempio di codice mostra come recuperare i dettagli di un agente registrato con 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"

Sostituisci le variabili con i valori:

  • ENDPOINT_LOCATION: la località multiregionale per la richiesta API. Specifica uno dei seguenti valori:
    • us per la multi-regione Stati Uniti
    • eu per la multi-regione UE
    • global per la località globale
    Per saperne di più, consulta Specifica una multi-regione per il datastore.
  • PROJECT_ID: l'ID del tuo progetto Google Cloud .
  • LOCATION: la località multiregionale della tua app: global, us o eu.
  • APP_ID: l'ID dell'app Gemini Enterprise.
  • AGENT_ID: l'ID dell'agente. Puoi trovare l'ID agente elencando gli agenti connessi alla tua app.

Aggiorna un agente A2A

Puoi modificare i dettagli di un agente A2A esistente registrato con Gemini Enterprise utilizzando la console Google Cloud o l'API REST.

Console

Per aggiornare un agente A2A utilizzando la console Google Cloud , segui questi passaggi:

  1. Nella console Google Cloud , vai alla pagina Gemini Enterprise.

    Gemini Enterprise

  2. Fai clic sul nome dell'app che include l'agente che vuoi aggiornare.

  3. Fai clic su Agenti.

  4. Fai clic sul nome dell'agente A2A (personalizzato) da aggiornare, quindi fai clic su Modifica.

  5. Nel campo JSON scheda agente, aggiorna i dettagli della scheda agente in formato JSON. Per un elenco completo dei campi disponibili, consulta la specifica ufficiale del protocollo Agent2Agent (A2A). L'esempio seguente utilizza solo i campi obbligatori.

    Ad esempio:

    {
      "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. Fai clic su Salva.

REST

Per aggiornare i dettagli di un agente A2A registrato con Gemini Enterprise, utilizza il metodo agents.patch. Il seguente comando utilizza solo i campi obbligatori. Per un elenco completo dei campi disponibili, consulta la specifica ufficiale del protocollo Agent2Agent (A2A).

Esegui questo comando per aggiornare l'agente A2A con 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"
  }
}
'

Sostituisci quanto segue:

  • ENDPOINT_LOCATION: la località multiregionale per la richiesta API. Specifica uno dei seguenti valori:
    • us per la multi-regione Stati Uniti
    • eu per la multi-regione UE
    • global per la località globale
    Per saperne di più, consulta Specifica una multi-regione per il datastore.
  • LOCATION: la località multiregionale del datastore: global, us o eu.
  • PROJECT_ID: l'ID progetto.
  • APP_ID: l'ID dell'app in cui vuoi registrare l'agente.
  • AGENT_ID: l'ID dell'agente. Puoi trovare l'ID agente elencando gli agenti connessi alla tua app.
  • AGENT_NAME: l'identificatore univoco dell'agente.
  • AGENT_DISPLAY_NAME: il nome dell'agente visualizzato nell'app web.
  • AGENT_DESCRIPTION: la descrizione di ciò che l'agente può fare.
  • PROTOCOLVERSION: la versione del protocollo A2A supportata dall'agente. Per saperne di più sulle versioni supportate, consulta le note di rilascio di A2A.
  • AGENT_URL: l'URL dell'endpoint dell'agente.
  • AGENT_VERSION: la versione dell'agente.
  • INPUT_MODE: il tipo di media di input predefinito. Ad esempio, application/json o text/plain.
  • OUTPUT_MODE: il tipo di media di output predefinito. Ad esempio, text/plain o image/png.
  • CAPABILITIES: un oggetto JSON contenente le funzionalità A2A supportate. Ad esempio: \"streaming\": true o \"pushNotifications\": false.
  • SKILLS: un elenco di oggetti AgentSkill offerti dall'agente.
  • authorizationConfig: se hai ottenuto i dettagli di autorizzazione e vuoi che l'agente acceda alle risorse Google Cloud per conto dell'utente, aggiungi il campo authorization_config alla risorsa JSON.

Elimina un agente A2A

Il seguente esempio di codice mostra come eliminare un agente connesso alla tua app:

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"

Sostituisci le variabili con i valori:

  • ENDPOINT_LOCATION: la località multiregionale per la richiesta API. Specifica uno dei seguenti valori:
    • us per la multi-regione Stati Uniti
    • eu per la multi-regione UE
    • global per la località globale
    Per saperne di più, consulta Specifica una multi-regione per il datastore.
  • PROJECT_ID: l'ID del tuo progetto Google Cloud .
  • LOCATION: la località multiregionale della tua app: global, us o eu
  • APP_ID: l'ID dell'app Gemini Enterprise.
  • AGENT_ID: l'ID dell'agente. Puoi trovare l'ID agente elencando gli agenti connessi alla tua app.

Passaggi successivi

  • Utilizza l'agente che hai registrato con Gemini Enterprise nell'app web.