Skip to content

Commit a3416be

Browse files
yuantian-agentspaceyuantian-agentspace
authored
Add Examples for how to use A2UI on Gemini Enterprise (#1043)
* Add Exmaples for how to use A2UI on Gemini Enterprise * Add license * Remove extra ' from script * correct package name * Rewrite with new A2UI SDK * udpate README.md * Update according to PR feedback * Reformat with uv run pyink .
1 parent 19919ef commit a3416be

29 files changed

+4140
-0
lines changed

‎samples/agent/adk/gemini_enterprise/README.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# A2UI on Gemini Enterprise
2+
3+
This folder contains examples and scripts to develop and use A2UI agents on
4+
**Google Cloud Gemini Enterprise**.
5+
6+
## Folder Structure
7+
8+
This directory is organized into two sub-folders depending the deployment
9+
methods:
10+
11+
- `cloud_run`: Contains scripts and configuration to deploy an agent to
12+
**Cloud Run**. This is suitable for building and deploying AI agents
13+
quickly, leveraging its speed and simplicity.
14+
15+
- Starts with `cloud_run/README.md`.
16+
17+
- `agent_engine`: Contains code to deploy to **Vertex AI Agent Engine**. Agent
18+
Engine provides additional features like agent context management, agent
19+
evaluation, agent lifecycle management, model-based conversation quality
20+
monitoring, and model tuning with context data.
21+
22+
- Starts with `agent_engine/README.md`.
23+
24+
## Shared Resources
25+
26+
- `agent.py`: Contains the JSON schema for A2UI messages, used for validation
27+
during development and at runtime.
28+
- `prompt_builder.py`: Provides prompts including Role, Workflow, and UI
29+
descriptions.
30+
- `agent_executor.py`: A base implementation of an A2A (Agent-to-Agent)
31+
executor that handles A2UI validation and response formatting.
32+
- `contact_data.json`: Fake contact data for demo.
33+
- `tools.py`: A simple tools to find contact data.
34+
- `examples`: Examples for A2UI messages.
35+
36+
## Registration in Gemini Enterprise
37+
38+
Regardless of the deployment method, agents must be registered with Gemini
39+
Enterprise. This involves: 1. **Defining an A2A Agent Card**: Describing the
40+
agent's skills, name, and capabilities (including the **A2UI extension**). 2.
41+
**Configuring Authorization**: Setting up OAuth2 or other authentication
42+
mechanisms to allow the agent to talk to secure services. This is optional for
43+
Cloud Run deployment but **mandatory for Agent Engine deployment**.

‎samples/agent/adk/gemini_enterprise/agent_engine/.env.example‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
PROJECT_ID=<Your GCP Project ID>
2+
LOCATION=<Your GCP Location, for example: us-central1>
3+
STORAGE_BUCKET=<Your GCS Bucket starting with gs://>
4+
GEMINI_ENTERPRISE_APP_ID=<Your Gemini Enterprise App ID. You can create a new App or use an existing one on GCP Gemini Enterprise.>
5+
AGENT_AUTHORIZATION=<Your Agent Authorization. See details in README.md>

‎samples/agent/adk/gemini_enterprise/agent_engine/README.md‎

Lines changed: 240 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,240 @@
1+
# Register an A2UI Agent deployed on Vertex AI Agent Engine with Gemini Enterprise
2+
3+
This sample demonstrates how to deploy an A2UI Agent on **Agent Engine** and
4+
register on **Gemini Enterprise**.
5+
6+
## Overview
7+
8+
High level steps:
9+
10+
- Config Authorization
11+
- Setup environment variables
12+
- Develop A2UI agent with ADK + A2A (sample code provided)
13+
- Deploy the agent to Agent Engine
14+
- Register the agent on Gemini Enterprise
15+
16+
## Config Authorization
17+
18+
Check **Before you begin** section and follow **Obtain authorization details**
19+
section on
20+
[Register and manage A2A agents](https://docs.cloud.google.com/gemini/enterprise/docs/register-and-manage-an-a2a-agent).
21+
Download JSON that looks like:
22+
23+
```
24+
{
25+
"web": {
26+
"client_id": "<client id>",
27+
"project_id": "<Google Cloud project id>",
28+
"auth_uri": "https://accounts.google.com/o/oauth2/auth",
29+
"token_uri": "https://oauth2.googleapis.com/token",
30+
"auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
31+
"client_secret": "<secret>",
32+
"redirect_uris": [
33+
"https://vertexaisearch.cloud.google.com/oauth-redirect",
34+
"https://vertexaisearch.cloud.google.com/static/oauth/oauth.html"
35+
]
36+
}
37+
}
38+
```
39+
40+
NOTE: For this deployment, you can skip the rest of **Register and manage A2A
41+
agents** page.
42+
43+
Replace **YOUR_CLIENT_ID** with `client_id` which can be found in the downloaded
44+
json and save the following as **authorizationUri**
45+
46+
```
47+
https://accounts.google.com/o/oauth2/v2/auth?client_id=<YOUR_CLIENT_ID>&redirect_uri=https%3A%2F%2Fvertexaisearch.cloud.google.com%2Fstatic%2Foauth%2Foauth.html&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fcloud-platform&include_granted_scopes=true&response_type=code&access_type=offline&prompt=consent
48+
```
49+
50+
In your console, run this:
51+
52+
```
53+
curl -X POST \
54+
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
55+
-H "Content-Type: application/json" \
56+
-H "X-Goog-User-Project: <YOUR_PROJECT_ID>" \
57+
"https://<ENDPOINT_LOCATION>-discoveryengine.googleapis.com/v1alpha/projects/<YOUR_PROJECT_ID>/locations/<LOCATION>/authorizations?authorizationId=<AUTH_ID>" \
58+
-d '{
59+
"name": "projects/<YOUR_PROJECT_ID>/locations/<LOCATION>/authorizations/<AUTH_ID>",
60+
"serverSideOauth2": {
61+
"clientId": "<OAUTH_CLIENT_ID>",
62+
"clientSecret": "<OAUTH_CLIENT_SECRET>",
63+
"authorizationUri": "<OAUTH_AUTH_URI>",
64+
"tokenUri": "<OAUTH_TOKEN_URI>"
65+
}
66+
}'
67+
```
68+
69+
Replace the following:
70+
71+
- **YOUR_PROJECT_ID**: the ID of your project. There are 3 occasions
72+
- **ENDPOINT_LOCATION**: the multi-region for your API request. Specify one of
73+
the following values:
74+
- *us* for the US multi-region
75+
- *eu* for the EU multi-region
76+
- *global* for the Global location
77+
- **LOCATION**: the multi-region of your data store: *global*, *us*, or *eu*.
78+
There are 2 occasions
79+
- **AUTH_ID**: The ID of the authorization resource. This is an arbitrary
80+
alphanumeric ID that you define. You need to reference this ID later when
81+
registering an Agent that requires OAuth support. There are 2 occasions.
82+
- **OAUTH_CLIENT_ID**: copy `client_id` from the downloaded JSON.
83+
- **OAUTH_CLIENT_SECRET**: copy `client_secret` from the downloaded JSON.
84+
- **OAUTH_AUTH_URI**: the value of **authorizationUri**. See above.
85+
- **OAUTH_TOKEN_URI**: copy `token_uri` from the downloaded JSON.
86+
87+
NOTE: if `$(gcloud auth print-access-token)` does not work for you, replace it
88+
with `$(gcloud auth application-default print-access-token)` and try again.
89+
90+
As result, you will get **AGENT_AUTHORIZATION** like this:
91+
92+
```
93+
projects/PROJECT_NUMBER/locations/global/authorizations/<AUTH_ID>
94+
```
95+
96+
The value will be used as an environment variable described below.
97+
98+
NOTE: if you already have an agent that is deployed to Agent Engine, skip to
99+
**Manually Register An Agent** section.
100+
101+
## Setup Environment Variables
102+
103+
1. **Copy `.env.example`:** Duplicate the `.env.example` file and rename it to
104+
`.env`.
105+
- `cd /path/to/agent_engine`
106+
- `cp .env.example .env`
107+
2. **Fill `.env`:** Update the `.env` file with your specific Google Cloud
108+
project details:
109+
* `PROJECT_ID`: Your Google Cloud Project ID.
110+
* `LOCATION`: The Google Cloud region you want to deploy the agent in
111+
(e.g., `us-central1`). This location is **not** the same as the
112+
*location* used in the command above.
113+
* `STORAGE_BUCKET`: A Google Cloud Storage bucket name for staging. It
114+
starts with **"gs://"**.
115+
* `GEMINI_ENTERPRISE_APP_ID`: Your Gemini Enterprise Application ID. You
116+
can create a new App or use an existing one on Google Cloud Gemini
117+
Enterprise.
118+
* `AGENT_AUTHORIZATION`: the value **AGENT_AUTHORIZATION** obtained above.
119+
120+
## Running the Script
121+
122+
The `main.py` script performs the following actions:
123+
124+
1. Initializes the Vertex AI client.
125+
2. Defines a sample "Contact Card Agent" skill and creates an agent card.
126+
3. Creates a local `A2aAgent` instance.
127+
4. Deploys the agent to Vertex AI Agent Engine (`client.agent_engines.create`).
128+
5. Fetches the deployed agent's card.
129+
6. Registers the agent on Gemini Enterprise using the Discovery Engine API.
130+
131+
To run the script using `uv`:
132+
133+
1. **Navigate to the script directory:**
134+
- `cd /path/to/agent_engine`
135+
2. **Create and activate a virtual environment:**
136+
- `uv venv`
137+
- `source .venv/bin/activate`
138+
3. **Install dependencies:**
139+
- `uv sync`
140+
4. **Run the script:**
141+
- `uv run deploy.py`
142+
- It may take 5-10 minutes to finish.
143+
144+
## Manually Register An Agent
145+
146+
If you have an Agent that is already deployed to Agent Engine, you can manually
147+
register it on Gemini Enterprise without running "main.py" script.
148+
149+
1. Complete **Config Authorization** section above.
150+
2. Open Google Cloud **Gemini Enterprise**.
151+
3. Click on the **App** you want to register your agent.
152+
- If you don't see the app being listed, click **Edit** to switch location
153+
4. Select **Agents** from the left nav bar.
154+
5. Click **Add agent** and select **Add** on **A2A** card.
155+
6. Copy this following JSON to the "Agent Card JSON" input box.
156+
157+
```
158+
{
159+
"name": "Test Contact Card Agent",
160+
"url": "https://<LOCATION>-aiplatform.googleapis.com/v1beta1/<RESOURCE_NAME>/a2a",
161+
"description": "A helpful assistant agent that can find contact card s.",
162+
"skills": [
163+
{
164+
"description": "A helpful assistant agent that can find contact cards.",
165+
"tags": [
166+
"Contact-Card"
167+
],
168+
"name": "Contact Card Agent",
169+
"examples": [
170+
"Who is John Doe?",
171+
"List all contact cards."
172+
],
173+
"id": "contact_card_agent"
174+
}
175+
],
176+
"version": "1.0.0",
177+
"capabilities": {
178+
"streaming": true,
179+
"extensions": [
180+
{
181+
"uri": "https://a2ui.org/a2a-extension/a2ui/v0.8",
182+
"description": "Ability to render A2UI",
183+
"required": false,
184+
"params": {
185+
"supportedCatalogIds": [
186+
"https://a2ui.org/specification/v0_8/standard_catalog_definition.json"
187+
]
188+
}
189+
}
190+
]
191+
},
192+
"protocolVersion": "0.3.0",
193+
"defaultOutputModes": [
194+
"application/json"
195+
],
196+
"defaultInputModes": [
197+
"text/plain"
198+
],
199+
"supportsAuthenticatedExtendedCard": true,
200+
"preferredTransport": "HTTP+JSON"
201+
}
202+
```
203+
204+
Replace **LOCATION** and **RESOURCE_NAME**.
205+
206+
- LOCATION is where you deploy your agent. For example; us-central1.
207+
- RESOURCE_NAME can be found on Google Cloud **Agent Engine**: click the
208+
agent; click **Service Configuration**; select **Deployment details**;
209+
copy **Resource name**.
210+
211+
Update *name*, *description*, *skills*, *version* as needed. Leave other
212+
values unchanged.
213+
214+
7. Click **Preview Agent Details**
215+
216+
8. Click **Next**
217+
218+
9. Fill the **Agent authorization** form:
219+
220+
- Copy `client_id`, `client_secret`, `token_uri` from the downloaded JSON.
221+
- Copy **authorizationUri** value from the above to **Authorization URL**.
222+
- Leave **Scopes** field empty.
223+
- Click **Finish**
224+
225+
## Test Your Agent
226+
227+
1. Open Google Cloud Console and search for **"Gemini Enterprise"** and click
228+
on it.
229+
2. Open the project you used in the above setting.
230+
3. Click on the **App** you used to register your agent.
231+
- If you don't see your app being listed, click **"Edit"** to switch
232+
location
233+
4. Select **"Agents"** from the left nav bar.
234+
5. Click the three-dot button on the **"Actions"** column and select
235+
**"Previwe"** menu.
236+
6. It will open Gemini Enterprise Agent page.
237+
7. Try queries like *"Find contact card of Sarah"*.
238+
- If this is the first time you start a chat with the agent, it will ask
239+
for manual authorization.
240+
8. You should see a Contact Card being rendered on Gemini Enterprise.

‎samples/agent/adk/gemini_enterprise/agent_engine/__init__.py‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Copyright 2026 Google LLC
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# http://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.
14+
15+
# This file makes this directory a Python package

0 commit comments

Comments
 (0)