Register and manage A2A agents

Agent2Agent (A2A) Protocol is an open communication protocol and a universal language for agents. The protocol enables agents from different builders and platforms to discover each other, collaborate, and securely delegate tasks. This document explains how Gemini Enterprise administrators can connect agents that are built using A2A and hosted on any platform to Gemini Enterprise, making them available to users in the Gemini Enterprise web app.

Before you begin

Make sure you have the following:

  • The Gemini Enterprise Admin role.

  • Enable the Discovery Engine API. To enable the Discovery Engine API for the Google Cloud project, in the Google Cloud console, go to the Discovery Engine API page.

    Go to Discovery Engine API

  • An existing Gemini Enterprise app. To create an app, see Create an app.

  • An agent that uses the A2A protocol.

    Gemini Enterprise supports the A2A v0.3 streaming mechanism.

    If you use A2A v1.0.0 or later, then use the compatibility packages provided by the SDK to make sure that your agent functions with the earlier mechanism (for example, the a2acompat/a2av0 package for Go or the a2a.compat.v0_3 package for Python).

  • If your A2A agent is hosted on Cloud Run, uses a default .run.app URL directly, and requires authentication, grant the Cloud Run Invoker (roles/run.invoker) role to the Discovery Engine service agent (this doesn't apply when Cloud Run is behind Apigee, a load balancer, or a custom domain):

    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"
    

    Replace the following:

    • PROJECT_ID: the ID of your project.
    • PROJECT_NUMBER: the number of your Google Cloud project.

Configure authentication and authorization

Depending on your agent hosting environment and security requirements, you can configure how Gemini Enterprise authenticates with your agent, how your agent accesses downstream resources and tools on behalf of the end user, and how to secure your agent endpoint:

How Gemini Enterprise authenticates with your agent

When Gemini Enterprise invokes an A2A agent, it can send authentication and authorization data in request headers depending on your hosting and security configuration:

Header Description
X-Serverless-Authorization

Service-to-service IAM authentication (for Cloud Run).

If your A2A agent is hosted on Cloud Run and your agent URL is a default .run.app URL, Gemini Enterprise automatically generates a Google-signed OIDC ID token for the Discovery Engine service agent (service-PROJECT_NUMBER@gcp-sa-discoveryengine.iam.gserviceaccount.com) with your agent URL as the audience, and attaches it in the X-Serverless-Authorization header. If your agent URL uses Apigee, a load balancer, or a custom domain, Gemini Enterprise doesn't send this header.

When Gemini Enterprise calls a default .run.app URL directly, the Cloud Run ingress infrastructure consumes this header to verify that the service agent has the roles/run.invoker IAM role (see Before you begin) before forwarding the request to your application container.

Authorization

End-user OAuth 2.0 authorization (for endpoint invocation, user context, and API access).

If you configure OAuth 2.0 credentials for your A2A agent (see Configure OAuth 2.0 for end-user authorization), Gemini Enterprise acquires an OAuth 2.0 access token or ID token on behalf of the signed-in end user after they grant consent, and sends it in the standard Authorization header (for example, Bearer USER_OAUTH_TOKEN).

For agents hosted on Cloud Run, Cloud Run forwards the Authorization header directly to your container, letting your agent application code read the user token and call downstream APIs on behalf of the user. For A2A agents hosted on Agent Runtime, configuring an OAuth 2.0 authorization resource with the https://www.googleapis.com/auth/cloud-platform scope lets Gemini Enterprise authenticate to the Agent Runtime endpoint on behalf of the user.

Configure OAuth 2.0 for end-user authorization (optional)

For A2A agents, configure OAuth 2.0 credentials in Gemini Enterprise if your agent endpoint requires an end-user OAuth 2.0 token in the Authorization header (for example, to invoke an A2A agent hosted on Agent Runtime or to pass a user token directly to your agent container). For more information about how authentication and authorization headers work, see How Gemini Enterprise authenticates with your agent.

If your A2A agent uses Agent Identity auth manager for tool-level 3-legged OAuth (for example, to access MCP servers or third-party APIs on behalf of the user), see Configure 3-legged OAuth with Agent Identity auth manager.

Follow these steps to create an OAuth client ID:

  1. In the Google Cloud console, on the APIs & Services page, go to the Credentials page.

    Go to Credentials

  2. Select the Google Cloud project, which has the data source that you want the agent to access. For example, select the project that contains the BigQuery dataset that you want the agent to query.

  3. Click Create credentials and select OAuth client ID.

  4. In Application type, select Web application.

  5. In the Authorized redirect URIs section, add the following URIs:

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

  7. In the OAuth client created panel, click Download JSON. The downloaded JSON includes the Client ID, Authorization URI, Token URI, and Client secret for the selected Google Cloud project. You need these details to create an authorization resource.

Configure 3-legged OAuth with Agent Identity auth manager (optional)

If your A2A agent is built with the Agent Development Kit (ADK) and uses Agent Identity auth manager for 3-legged OAuth (3LO), your agent can authenticate to downstream MCP servers, Google Cloud services, or third-party APIs on behalf of the signed-in user.

When a tool in your A2A agent requires user consent, Gemini Enterprise automatically manages the client-side 3LO workflow:

  1. Consent prompt: When your agent returns an adk_request_credential tool interrupt (TASK_STATE_AUTH_REQUIRED), the Gemini Enterprise web app prompts the user to sign in and opens the authorization URI from the auth provider.
  2. User validation and token storage: After the user grants consent, the auth provider redirects to the Gemini Enterprise validation endpoint (https://vertexaisearch.cloud.google.com/validateUserId). Gemini Enterprise validates the session state and finalizes the credentials with Agent Identity auth manager.
  3. Conversation resumption: Gemini Enterprise sends the completed adk_request_credential response back to your A2A agent, which retrieves the user's access token from the auth provider and invokes the tool.

Because Gemini Enterprise handles the consent prompt, validation endpoint, and conversation resumption, you don't need to implement a custom client-side UI application.

Step 1: Set up a 3-legged OAuth auth provider

Follow the steps in Authenticate using 3-legged OAuth with auth manager to enable the Agent Identity API (agentidentity.googleapis.com), configure your OAuth client application, and create a 3-legged OAuth auth provider.

When configuring your OAuth client and auth provider for use with Gemini Enterprise, include the following settings:

  • Authorized redirect URIs: In your OAuth client configuration, add the auth provider's callback redirect URI:

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

    If you reuse the same OAuth client for your Gemini Enterprise agent authorization resource (for example, to let Gemini Enterprise invoke an A2A agent hosted on Agent Runtime), also include the Gemini Enterprise redirect URI (https://vertexaisearch.cloud.google.com/oauth-redirect).

  • Continue URI: Set the continue URI (either as the Default continue URI on the auth provider or as continue_uri in your agent code) to the Gemini Enterprise validation endpoint:

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

Step 2: Configure your A2A agent code

When building an ADK agent and wrapping it with A2aAgent for deployment on Agent Runtime, make sure your agent code meets the following requirements:

  • Install required package versions: Include a2a-sdk[http-server]>=1.0.0, google-cloud-aiplatform[agent_engines,adk]>=1.156.0, and google-adk[a2a,agent-identity,mcp]>2.7.1 in your deployment requirements.
  • Set continue_uri to Gemini Enterprise: Set continue_uri to "https://vertexaisearch.cloud.google.com/validateUserId" in GcpAuthProviderScheme or AgentRegistry.get_mcp_toolset (unless you configured it as the default continue URI on the auth provider).
  • Register GcpAuthProvider inside the runner builder function: Call CredentialManager.register_auth_provider(GcpAuthProvider()) inside the function that builds the Runner in the deployed container worker process, rather than only at the module top level.
  • Use the built-in A2aAgentExecutor: Pass A2aAgentExecutor(runner=build_runner) (from google.adk.a2a.executor.a2a_agent_executor import A2aAgentExecutor) to A2aAgent. Don't use a custom AgentExecutor that only checks event.is_final_response(), because A2aAgentExecutor is required to convert adk_request_credential interrupts into the TASK_STATE_AUTH_REQUIRED A2A task state.
  • Include A2A protocol version 0.3 on the AgentCard: Append an AgentInterface with protocol_version=PROTOCOL_VERSION_0_3 and protocol_binding=TransportProtocol.HTTP_JSON to agent_card.supported_interfaces alongside the default 1.0 interface so Gemini Enterprise can communicate with your agent over A2A v0.3 routes.

ADK + A2A

The following example configures an ADK A2A agent that uses GcpAuthProviderScheme with McpToolset (or AgentRegistry.get_mcp_toolset) to authenticate to an MCP server on behalf of the user:

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

The following example configures an ADK A2A agent that uses AuthenticatedFunctionTool with GcpAuthProviderScheme to call a third-party or Google Cloud REST API on behalf of the user:

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

Step 3: Deploy the A2A agent with Agent Identity and grant access

  1. Deploy your A2aAgent to Agent Runtime with 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. After deployment completes, grant the Agent Identity User (roles/agentidentity.user) role on the auth provider to your deployed agent's SPIFFE principal:

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

    Replace the following:

    • AUTH_PROVIDER_NAME: the name of your auth provider.
    • PROJECT_ID: the ID of your project.
    • LOCATION: the region where your auth provider and agent are deployed (for example, us-central1).
    • ORGANIZATION_ID: your Google Cloud organization ID.
    • PROJECT_NUMBER: the number of your Google Cloud project.
    • ENGINE_ID: the resource ID of your deployed reasoningEngines agent.
  3. Register the deployed A2A agent with Gemini Enterprise using either Register an A2A agent with Gemini Enterprise (Custom agent via A2A) or Import A2A agents from Agent Registry (Custom agent via Agent Runtime). Because the agent is hosted on Agent Runtime, configure an OAuth 2.0 authorization resource in Gemini Enterprise with the https://www.googleapis.com/auth/cloud-platform scope so Gemini Enterprise can invoke the Agent Runtime endpoint.

Secure your A2A agent endpoint

For the authentication headers that Gemini Enterprise sends to your A2A agent, see How Gemini Enterprise authenticates with your agent. When you secure your agent endpoint, or an API gateway in front of it, consider the following:

  • Agent card security schemes: Gemini Enterprise doesn't use the securitySchemes and security fields of your agent card to authenticate with your agent.
  • API keys and custom headers: Gemini Enterprise doesn't support the apiKey security scheme, and doesn't provide a way to add static API keys or other custom header values to the requests that it sends to your agent.
  • Service agent ID token: Gemini Enterprise sends the X-Serverless-Authorization header only when your agent URL is a default Cloud Run URL that ends in .run.app. If your agent URL uses a custom domain, a load balancer, or an API gateway, Gemini Enterprise doesn't send this header.
  • End-user token: If you configure OAuth 2.0 for your agent, Gemini Enterprise sends the end user's token from your OAuth 2.0 provider in the Authorization header.

Secure an agent endpoint with Apigee

If you expose your A2A agent through an Apigee API proxy, the proxy receives the end-user token in the Authorization header but doesn't receive the X-Serverless-Authorization header. To secure the proxy, do the following:

  1. Configure OAuth 2.0 for end-user authorization for your agent (using either a Google Cloud OAuth 2.0 client ID or a third-party OAuth 2.0 provider), and provide those OAuth 2.0 details when you register the agent. Configuring OAuth 2.0 is required when securing an Apigee API proxy; don't skip the authorization step during registration.
  2. In your agent card, set url to the URL of your Apigee API proxy.
  3. In the API proxy, validate the end-user token in the Authorization header before you forward the request to your agent. Choose the Apigee policy based on the token format that your OAuth 2.0 provider issues:
    • Third-party OAuth 2.0 providers that issue signed JWT access tokens: Use the VerifyJWT policy to verify the token signature against your provider's public JSON Web Key Set (JWKS) URI and validate the issuer (iss) and audience (aud) claims.
    • Google OAuth 2.0 (accounts.google.com): Google OAuth 2.0 access tokens (ya29...) are opaque tokens rather than signed JWTs. Use a ServiceCallout policy to call https://oauth2.googleapis.com/tokeninfo and verify the audience (aud) and scope fields.

Register an A2A agent with Gemini Enterprise

You can register your A2A agent with Gemini Enterprise using either the Google Cloud console or the REST API. This makes the agent available to users within a Gemini Enterprise app.

Console

To register an A2A agent using the Google Cloud console, follow these steps:

  1. In the Google Cloud console, go to the Gemini Enterprise page.

    Gemini Enterprise

  2. Click the name of the app that you want to register the agent with.

  3. Click Agents > Add Agents.

  4. In the Choose an agent type section, click Add for Custom agent via A2A.

  5. In the Agent card JSON field, enter the agent card details in JSON format. For a complete list of available fields, see the Agent2Agent (A2A) Protocol Official Specification. The following example only uses the required fields.

    For example:

    {
      "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. Click Preview agent details > Next.

  7. Complete the setup using one of the following methods:

    • If you don't want the agent to access Google Cloud resources on your behalf and your agent endpoint doesn't require an Authorization header, click Skip & Finish to skip this step.
    • If you have configured 3LO with auth manager, click Skip & Finish and the agent requests access dynamically.
    • If you have not configured 3LO with auth manager or your agent endpoint requires an Authorization header (for example, when securing an Apigee API proxy), follow these steps:

      1. Enter Client ID, Client secret, Authorization URI, and Token URI that you generated in Configure OAuth 2.0 for end-user authorization (optional).

      2. Enter the Scopes.

      3. Click Finish.

REST

To register an A2A agent using the REST API, follow these steps:

Add the authorization resource to Gemini Enterprise (optional)

If the agent must access Google Cloud resources on behalf of a user, run the following command to register the authorization resource you created in the Configure authorization details (optional) section with 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"
      }
   }'

Replace the following:

  • PROJECT_ID: the ID of your project.
  • PROJECT_NUMBER: the number of your Google Cloud project.
  • ENDPOINT_LOCATION: the multi-region for your API request. Specify one of the following values:
    • us for the US multi-region
    • eu for the EU multi-region
    • global for the Global location
    For more information, see Specify a multi-region for your data store.
  • LOCATION: the multi-region of your data store: global, us, or eu
  • AUTH_ID: the ID of the authorization resource. This is an arbitrary alphanumeric ID that you define. You need to reference this ID later when registering an Agent that requires OAuth support.
  • OAUTH_CLIENT_ID: the OAuth 2.0 client identifier you obtained when you created the OAuth credentials.
  • OAUTH_CLIENT_SECRET: the OAuth 2.0 client secret you obtained when you created the OAuth credentials.
  • OAUTH_AUTH_URI: the Authorization URI. To authorize your app, construct a specific Authorization URI using the details from your OAuth credentials JSON file. Copy the following template, and replace the placeholders with your specific values.

    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: you can add the scopes you need. For example, the following OAuth scope string requests read-only access to your Google Drive and Google Docs.

      scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fdrive.readonly%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fdocuments.readonly
      
  • OAUTH_TOKEN_URI: the token URI you obtained when you created the OAuth credentials.

More information about Authorization URI parameters.

To help ensure that the URI works correctly, verify the following fields:

Parameter Value or action
client_id Replace with the client_id that's found in your downloaded JSON.
redirect_uri Don't change. Must be https://vertexaisearch.cloud.google.com/static/oauth/oauth.html.
scope

List the Google API scopes that your app needs to access on behalf of the user. For example, to grant access to BigQuery, use the scope https://www.googleapis.com/auth/bigquery and for read-only access to Google Docs, use https://www.googleapis.com/auth/documents.readonly.

If you're using multiple scopes, separate them with a space, which becomes %20 in the URL.

include_granted_scopes Must be true.
response_type Must be code to receive an authorization code.
access_type Set to offline to help ensure that you receive a refresh token.
prompt Set to consent to help ensure that the user is always shown a consent screen.

Register your A2A agent

To create and register an agent with Gemini Enterprise, use the agents.create method. The following command uses only the required fields. For a complete list of available fields, see the Agent2Agent (A2A) Protocol Official Specification.

Run this command to register your A2A agent with 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"
  }
}
'

Replace the following:

  • ENDPOINT_LOCATION: the multi-region for your API request. Specify one of the following values:
    • us for the US multi-region
    • eu for the EU multi-region
    • global for the Global location
    For more information, see Specify a multi-region for your data store.
  • LOCATION: the multi-region of your data store: global, us, or eu
  • PROJECT_ID: the ID of your project.
  • APP_ID: the ID of the app with which you want to register the agent.
  • AGENT_NAME: the unique identifier for the agent.
  • AGENT_DISPLAY_NAME: the name of the agent that is displayed on the web app.
  • AGENT_DESCRIPTION: the description of what the agent can do.
  • PROTOCOLVERSION: the version of the A2A protocol the agent supports. For more information on the supported versions, see the A2A release notes.
  • AGENT_URL: the endpoint URL of the agent.
  • AGENT_VERSION: the version of the agent.
  • INPUT_MODE: the default input media type. For example, application/json or text/plain.
  • OUTPUT_MODE: the default output media type. For example, text/plain" or image/png.
  • CAPABILITIES: a JSON object containing supported A2A features. For example, \"streaming\": true or \"pushNotifications\": false.
  • SKILLS: a list of the AgentSkill object that the agent offers.
  • authorizationConfig: If you obtained the authorization details and want the agent to access Google Cloud resources on behalf of the user, add the authorization_config field to your JSON resource.

Show author and contact information for an agent (optional)

By default, an A2A agent that you register shows no author in Gemini Enterprise. To show who built the agent and who users can contact about it, add the agent metadata extension to the capabilities.extensions field of the agent card JSON that you use to register or update the agent:

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

Keep the other agent card fields from the registration example alongside capabilities. In the REST API, the extension is part of the escaped jsonAgentCard string.

The params field supports the following values. Both are optional.

Parameter Description
authorName The name of the person, team, or company that built the agent. The agent gallery shows it as By AUTHOR_NAME on the agent's card, and the Agent Info dialog shows it as Author. The gallery shows this name only when the agent has no owner name of its own. Names that contain the word "Google" aren't shown, so that they can't be mistaken for agents built by Google.
contactEmail An email address where users can reach the author. The Agent Info dialog shows it as Contact.

Each value must be a string of at most 256 characters, and contactEmail must be a valid email address. Gemini Enterprise ignores values that don't meet these requirements. Gemini Enterprise doesn't verify the author name or contact email.

List agents connected to an app

The following code sample demonstrates how you can get the details of all the agents connected to your 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"

Replace the variables with values:

  • ENDPOINT_LOCATION: the multi-region for your API request. Specify one of the following values:
    • us for the US multi-region
    • eu for the EU multi-region
    • global for the Global location
    For more information, see Specify a multi-region for your data store.
  • PROJECT_ID: the ID of your Google Cloud project.
  • LOCATION: the multi-region of your app: global, us, or eu.
  • APP_ID: the ID of your Gemini Enterprise app.

If your agent isn't prebuilt by Google, the response includes a name field in the first few lines. The value of this field contains the Agent ID at the end of the path. For example, in the following response, the Agent ID is 12345678901234567890:

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

View the details of an A2A agent

The following code sample demonstrates how you can retrieve the details of an agent that was registered with 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"

Replace the variables with values:

  • ENDPOINT_LOCATION: the multi-region for your API request. Specify one of the following values:
    • us for the US multi-region
    • eu for the EU multi-region
    • global for the Global location
    For more information, see Specify a multi-region for your data store.
  • PROJECT_ID: the ID of your Google Cloud project.
  • LOCATION: the multi-region of your app: global, us, or eu.
  • APP_ID: the ID of your Gemini Enterprise app.
  • AGENT_ID: the ID of the agent. You can find the agent ID by listing the agents connected to your app.

Update an A2A agent

You can modify the details of an existing A2A agent registered with Gemini Enterprise using either the Google Cloud console or the REST API.

Console

To update an A2A agent using the Google Cloud console, follow these steps:

  1. In the Google Cloud console, go to the Gemini Enterprise page.

    Gemini Enterprise

  2. Click the name of the app that includes the agent you want to update.

  3. Click Agents.

  4. Click the name of the A2A (Custom) agent to update, and then click Edit.

  5. In the Agent card JSON field, update the agent card details in JSON format. For a complete list of available fields, see the Agent2Agent (A2A) Protocol Official Specification. The following example only uses the required fields.

    For example:

    {
      "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. Click Save.

REST

To update details of an A2A agent that is registered with Gemini Enterprise, use the agents.patch method. The following command uses only the required fields. For a complete list of available fields, see the Agent2Agent (A2A) Protocol Official Specification.

Run this command to update your A2A agent with 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"
  }
}
'

Replace the following:

  • ENDPOINT_LOCATION: the multi-region for your API request. Specify one of the following values:
    • us for the US multi-region
    • eu for the EU multi-region
    • global for the Global location
    For more information, see Specify a multi-region for your data store.
  • LOCATION: the multi-region of your data store: global, us, or eu.
  • PROJECT_ID: the ID of your project.
  • APP_ID: the ID of the app that you want to register the agent.
  • AGENT_ID: the ID of the agent. You can find the agent ID by listing the agents connected to your app.
  • AGENT_NAME: the unique identifier for the agent.
  • AGENT_DISPLAY_NAME: the name of the agent that is displayed on the web app.
  • AGENT_DESCRIPTION: the description of what the agent can do.
  • PROTOCOLVERSION: the version of the A2A protocol that the agent supports. For more information on the supported versions, see the A2A release notes.
  • AGENT_URL: the endpoint URL of the agent.
  • AGENT_VERSION: the version of the agent.
  • INPUT_MODE: the default input media type. For example, application/json or text/plain.
  • OUTPUT_MODE: the default output media type. For example, text/plain or image/png.
  • CAPABILITIES: a JSON object containing supported A2A features. For example, \"streaming\": true or \"pushNotifications\": false.
  • SKILLS: a list of the AgentSkill object that the agent offers.
  • authorizationConfig: If you obtained the authorization details and want the agent to access Google Cloud resources on behalf of the user, add the authorization_config field to your JSON resource.

Delete an A2A agent

The following code sample demonstrates how you can delete an agent that is connected to your 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"

Replace the variables with values:

  • ENDPOINT_LOCATION: the multi-region for your API request. Specify one of the following values:
    • us for the US multi-region
    • eu for the EU multi-region
    • global for the Global location
    For more information, see Specify a multi-region for your data store.
  • PROJECT_ID: the ID of your Google Cloud project.
  • LOCATION: the multi-region of your app: global, us, or eu
  • APP_ID: the ID of your Gemini Enterprise app.
  • AGENT_ID: the ID of the agent. You can find the agent ID by listing the agents connected to your app.

What's next

  • Use the agent that you registered with Gemini Enterprise on the web app.