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.
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/a2av0package for Go or thea2a.compat.v0_3package for Python).If your A2A agent is hosted on Cloud Run, uses a default
.run.appURL 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: Learn how Gemini Enterprise sends service-to-service IAM and end-user OAuth 2.0 headers when invoking your A2A agent endpoint.
- Configure OAuth 2.0 for end-user authorization:
Configure an OAuth 2.0 authorization resource in Gemini Enterprise so
Gemini Enterprise acquires an end-user token and sends it in the
Authorizationheader when calling your agent (for example, to invoke an A2A agent hosted on Agent Runtime on Gemini Enterprise Agent Platform or pass a user token directly to your agent container). - Configure 3-legged OAuth with Agent Identity auth manager: Configure a 3-legged OAuth (3LO) auth provider in Agent Identity auth manager so your A2A agent can request user-delegated tokens on demand for specific tools, such as Model Context Protocol (MCP) servers or third-party APIs.
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 When Gemini Enterprise calls a default |
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 For agents hosted on Cloud Run, Cloud Run forwards the |
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:
In the Google Cloud console, on the APIs & Services page, go to the Credentials page.
-
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.
Click Create credentials and select OAuth client ID.
In Application type, select Web application.
In the Authorized redirect URIs section, add the following URIs:
https://vertexaisearch.cloud.google.com/oauth-redirecthttps://vertexaisearch.cloud.google.com/static/oauth/oauth.html
Click Create.
In the OAuth client created panel, click Download JSON. The downloaded JSON includes the
Client ID,Authorization URI,Token URI, andClient secretfor 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:
- Consent prompt: When your agent returns an
adk_request_credentialtool 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. - 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. - Conversation resumption: Gemini Enterprise sends the completed
adk_request_credentialresponse 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>/oauthcallbackIf 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_uriin 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, andgoogle-adk[a2a,agent-identity,mcp]>2.7.1in your deployment requirements. - Set
continue_urito Gemini Enterprise: Setcontinue_urito"https://vertexaisearch.cloud.google.com/validateUserId"inGcpAuthProviderSchemeorAgentRegistry.get_mcp_toolset(unless you configured it as the default continue URI on the auth provider). - Register
GcpAuthProviderinside the runner builder function: CallCredentialManager.register_auth_provider(GcpAuthProvider())inside the function that builds theRunnerin the deployed container worker process, rather than only at the module top level. - Use the built-in
A2aAgentExecutor: PassA2aAgentExecutor(runner=build_runner)(from google.adk.a2a.executor.a2a_agent_executor import A2aAgentExecutor) toA2aAgent. Don't use a customAgentExecutorthat only checksevent.is_final_response(), becauseA2aAgentExecutoris required to convertadk_request_credentialinterrupts into theTASK_STATE_AUTH_REQUIREDA2A task state. - Include A2A protocol version
0.3on theAgentCard: Append anAgentInterfacewithprotocol_version=PROTOCOL_VERSION_0_3andprotocol_binding=TransportProtocol.HTTP_JSONtoagent_card.supported_interfacesalongside the default1.0interface 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
Deploy your
A2aAgentto Agent Runtime withidentity_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", ], }, )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 deployedreasoningEnginesagent.
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-platformscope 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
securitySchemesandsecurityfields of your agent card to authenticate with your agent. - API keys and custom headers: Gemini Enterprise doesn't support the
apiKeysecurity 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-Authorizationheader 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
Authorizationheader.
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:
- 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.
- In your agent card, set
urlto the URL of your Apigee API proxy. - In the API proxy, validate the end-user token in the
Authorizationheader 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 callhttps://oauth2.googleapis.com/tokeninfoand verify the audience (aud) andscopefields.
- 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 (
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:
In the Google Cloud console, go to the Gemini Enterprise page.
Click the name of the app that you want to register the agent with.
Click Agents > Add Agents.
In the Choose an agent type section, click Add for Custom agent via A2A.
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" ] }Click Preview agent details > Next.
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
Authorizationheader, 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
Authorizationheader (for example, when securing an Apigee API proxy), follow these steps:Enter Client ID, Client secret, Authorization URI, and Token URI that you generated in Configure OAuth 2.0 for end-user authorization (optional).
Enter the Scopes.
Click Finish.
- If you don't want the agent to access Google Cloud resources on your
behalf and your agent endpoint doesn't require an
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:usfor the US multi-regioneufor the EU multi-regionglobalfor the Global location
LOCATION: the multi-region of your data store:global,us, oreuAUTH_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 If you're using multiple scopes, separate
them with a space, which becomes |
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:usfor the US multi-regioneufor the EU multi-regionglobalfor the Global location
LOCATION: the multi-region of your data store:global,us, oreuPROJECT_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/jsonortext/plain.OUTPUT_MODE: the default output media type. For example,text/plain"orimage/png.CAPABILITIES: a JSON object containing supported A2A features. For example,\"streaming\": trueor\"pushNotifications\": false.SKILLS: a list of theAgentSkillobject 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 theauthorization_configfield to your JSON resource.AUTH_ID: the value that you used for AUTH_ID in the Add an authorization resource to Gemini Enterprise section.
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:
usfor the US multi-regioneufor the EU multi-regionglobalfor the Global location
- PROJECT_ID: the ID of your Google Cloud project.
- LOCATION: the multi-region of your app:
global,us, oreu. - 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:
usfor the US multi-regioneufor the EU multi-regionglobalfor the Global location
- PROJECT_ID: the ID of your Google Cloud project.
- LOCATION: the multi-region of your app:
global,us, oreu. - 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:
In the Google Cloud console, go to the Gemini Enterprise page.
Click the name of the app that includes the agent you want to update.
Click Agents.
Click the name of the A2A (Custom) agent to update, and then click Edit.
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" ] }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:usfor the US multi-regioneufor the EU multi-regionglobalfor the Global location
LOCATION: the multi-region of your data store:global,us, oreu.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/jsonortext/plain.OUTPUT_MODE: the default output media type. For example,text/plainorimage/png.CAPABILITIES: a JSON object containing supported A2A features. For example,\"streaming\": trueor\"pushNotifications\": false.SKILLS: a list of theAgentSkillobject 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 theauthorization_configfield to your JSON resource.AUTH_ID: the value that you used for AUTH_ID in the Add an authorization resource to Gemini Enterprise section.
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:
usfor the US multi-regioneufor the EU multi-regionglobalfor the Global location
- PROJECT_ID: the ID of your Google Cloud project.
- LOCATION: the multi-region of your app:
global,us, oreu - 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.