Skip to content

Commit 45a5fea

Browse files
cbaueratworkcbaueratwork
authored
Syncing docs (#6)
1 parent 9fd82b1 commit 45a5fea

3 files changed

Lines changed: 271 additions & 38 deletions

File tree

‎README.md‎

Lines changed: 115 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@
77

88
> **Note:** This toolkit is in **Experimental** status.
99
10-
This repository contains the A2UI reference implementation for the Google Maps Agentic UI Toolkit. It includes tools for implementing the Agent-to-User Interface (A2UI) standard, allowing agents to present rich, interactive interfaces across different platforms.
10+
This repository contains the A2UI implementation for the Google Maps Agentic UI Toolkit. It includes components and handlers implementing the Agent-to-User Interface (A2UI) standard, allowing agents to present rich, interactive interfaces across different platforms.
1111

1212
It makes use of the following technologies:
1313

@@ -19,7 +19,7 @@ It makes use of the following technologies:
1919

2020
## Quickstart Guide
2121

22-
To quickly get started, we recommend using the sample project in [a2ui-samples](https://github.com/googlemapssamples/a2ui-samples). This sample project contains the necessary components to run the Python Agent and a React web client that allows you to interact with the agent.
22+
To quickly get started, we recommend using the [Agentic UI Toolkit samples project](https://github.com/googlemaps-samples/a2ui). This sample project contains the necessary components to run the Python Agent and a React web client that allows you to interact with the agent.
2323

2424
### Prerequisites and Tool Setup
2525

@@ -67,8 +67,6 @@ For more information about the environment variables, see the **Google API Key C
6767

6868
This package provides the core Python agent implementations for the Agentic UI Toolkit (MAUI). It includes the base `MAUIAgent` and the extended `MAUIAgentWithGrounding` that uses Vertex Grounding.
6969

70-
This section refers to the file structure within [agent/python-agent](agent/python-agent).
71-
7270
### File Structure
7371

7472
* `agent.py`: Contains the `MAUIAgent` class, which handles session management, LLM interaction, and A2UI schema loading.
@@ -79,7 +77,7 @@ This section refers to the file structure within [agent/python-agent](agent/pyth
7977

8078
### How to Integrate
8179

82-
To integrate these agents into an existing application (like a server), you can refer to the sample in [a2ui-samples/agent/python](https://github.com/googlemaps-samples/a2ui/tree/main/agent/python).
80+
To integrate these agents into an existing application (like a server), you can refer to the sample in [Agentic UI Toolkit Samples](https://github.com/googlemaps-samples/a2ui).
8381

8482
#### 1. Add Dependency
8583
In your application's `pyproject.toml`, add `maui-a2ui-python` to your dependencies:
@@ -94,33 +92,91 @@ maui-a2ui-python = { path = "path/to/a2ui/agent/python-agent" }
9492
```
9593

9694
#### 2. Import and Use
97-
In your Python code (e.g., `__main__.py` or `agent_executor.py`):
95+
96+
The Agentic UI Toolkit includes two agents, one that uses Grounding Lite and one that uses Grounding with Google Maps. The Python integration steps are the same for each, but if you use Grounding with Google Maps, you must follow the instructions to configure your local environment. See the [Accessing Google Maps grounding data](#accessing-google-maps-grounding-data) section below for more information on configuring these services.
97+
98+
Tip: See the [agent_executor.py](https://github.com/googlemaps-samples/a2ui/blob/main/agent/python/agent_executor.py) example in the Agentic UI Toolkit Samples repository for a working example.
99+
100+
Import the MAUIAgent into your Python code (e.g., `__main__.py` or `agent_executor.py`) and
101+
configure the ADK Agent Executor to call it.
98102

99103
```python
104+
# A2UI, ADK, and A2A imports
105+
from a2a.server.agent_execution import AgentExecutor, RequestContext
106+
from a2a.server.events import EventQueue
107+
from a2a.server.tasks import TaskUpdater
108+
from a2a.types import (
109+
DataPart,
110+
Part,
111+
Task,
112+
TaskState,
113+
TextPart,
114+
UnsupportedOperationError,
115+
)
116+
from a2a.utils import (
117+
new_agent_parts_message,
118+
new_agent_text_message,
119+
new_task,
120+
)
121+
from a2a.utils.errors import ServerError
122+
from a2ui.a2a.extension import try_activate_a2ui_extension
123+
124+
# MAUI Agent import
100125
from agent import MAUIAgent
101-
from agent_with_grounding import MAUIAgentWithGrounding
102-
103-
# Initialize the agent
104-
agent = MAUIAgent(base_url="http://localhost:10002")
105-
106-
# Use the agent to stream responses
107-
async for item in agent.stream(query, session_id, ui_version):
108-
if "parts" in item:
109-
# Process A2UI parts
110-
pass
111-
elif "updates" in item:
112-
# Process text updates
113-
pass
114-
```
115126

127+
class MAUIAgentExecutor(AgentExecutor):
128+
129+
def __init__(self, agent: MAUIAgent):
130+
self.agent = agent
131+
132+
async def execute(
133+
self,
134+
context: RequestContext,
135+
event_queue: EventQueue,
136+
) -> None:
137+
query = context.get_user_input()
138+
active_ui_version = try_activate_a2ui_extension(context, self.agent.agent_card)
139+
task = context.current_task
140+
141+
# Create a new task if necessary
142+
if not task:
143+
task = new_task(context.message)
144+
await event_queue.enqueue_event(task)
145+
updater = TaskUpdater(event_queue, task.id, task.context_id)
146+
147+
# Handle each item in the streamed response.
148+
async for item in self.agent.stream(query, task.context_id, active_ui_version):
149+
is_task_complete = item["is_task_complete"]
150+
if not is_task_complete:
151+
message = None
152+
if "parts" in item:
153+
message = new_agent_parts_message(item["parts"], task.context_id, task.id)
154+
elif "updates" in item:
155+
message = new_agent_text_message(item["updates"], task.context_id, task.id)
156+
157+
if message:
158+
await updater.update_status(TaskState.working, message)
159+
continue
160+
161+
final_parts = item["parts"]
162+
163+
await updater.update_status(
164+
TaskState.completed,
165+
new_agent_parts_message(final_parts, task.context_id, task.id),
166+
final=True,
167+
)
168+
break
116169

170+
async def cancel(
171+
self, request: RequestContext, event_queue: EventQueue
172+
) -> Task | None:
173+
raise ServerError(error=UnsupportedOperationError())
174+
```
117175

118176
## MAUI Web Client Library (`@googlemaps/a2ui`)
119177

120178
This package provides the Web (Lit-based) client library for the Agentic UI Toolkit (MAUI). It includes components and utilities to render A2UI surfaces and communicate with an A2A agent server.
121179

122-
This section refers to the file structure within [client/web](client/web).
123-
124180
### How to Build
125181

126182
To build the package for use in an application:
@@ -133,7 +189,7 @@ To build the package for use in an application:
133189

134190
### How to Integrate
135191

136-
To integrate these components into an existing application, you can refer to the sample in `a2ui-samples/client/web/react`.
192+
To integrate these components into an existing application, you can refer to the [Agentic UI Toolkit samples project](https://github.com/googlemaps-samples/a2ui).
137193

138194
#### 1. Link or Install the Package
139195
You can consume the package via npm linking for local development:
@@ -238,6 +294,42 @@ To create a new Google Cloud API Key, follow the instructions here in the [Googl
238294
239295
This key must be exported or contained within a `.env` file as `GEMINI_API_KEY`
240296
297+
## Accessing Google Maps grounding data
298+
299+
Your agent can access Google Maps grounding data in two ways, depending on your project setup and needs:
300+
301+
1. [Grounding Lite MCP](https://developers.google.com/maps/ai/grounding-lite)
302+
2. [Grounding with Google Maps](https://docs.cloud.google.com/vertex-ai/generative-ai/docs/grounding/grounding-with-google-maps)
303+
304+
### Grounding Lite MCP
305+
306+
To use Grounding Lite MCP, you must first enable the Maps Grounding Lite API and create or update an API Key to support the required APIs following the [documentation](https://developers.google.com/maps/ai/grounding-lite#configure_llms_to_use_the_mcp_server).
307+
308+
### Grounding with Google Maps
309+
310+
To use Grounding with Google Maps, there are additional steps you must take to configure your environment:
311+
312+
1. Ensure you have the latest version of the genai python package.
313+
```bash
314+
pip install --upgrade google-genai
315+
```
316+
317+
2. Configure additional environment variables to connect to your project.
318+
```bash
319+
## Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
320+
## with appropriate values for your project.
321+
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
322+
export GOOGLE_CLOUD_LOCATION=global
323+
export GOOGLE_GENAI_USE_VERTEXAI=True
324+
```
325+
326+
3. Ensure you are authenticated to Google Cloud.
327+
```bash
328+
gcloud auth application-default login
329+
```
330+
331+
See the [documentation](https://docs.cloud.google.com/vertex-ai/generative-ai/docs/grounding/grounding-with-google-maps#googlegenaisdk_tools_google_maps_with_txt-python_genai_sdk) for more information.
332+
241333
## Contributing
242334
243335
External contributions are not accepted for this repository. See [contributing guide] for more info.

‎agent/python-agent/README.md‎

Lines changed: 154 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -27,22 +27,162 @@ maui-a2ui-python = { path = "path/to/a2ui/agent/python-agent" }
2727
```
2828

2929
### 2. Import and Use
30-
In your Python code (e.g., `__main__.py` or `agent_executor.py`):
30+
31+
The Agentic UI Toolkit includes two agents, one that uses Grounding Lite and one that uses Grounding with Google Maps. The Python integration steps are the same for each, but if you use Grounding with Google Maps, you must follow the instructions to configure your local environment. See the [Accessing Google Maps grounding data](#accessing-google-maps-grounding-data) section below for more information on configuring these services.
32+
33+
Tip: See the [agent_executor.py](https://github.com/googlemaps-samples/a2ui/blob/main/agent/python/agent_executor.py) example in the Agentic UI Toolkit Samples repository for a working example.
34+
35+
Import the MAUIAgent into your Python code (e.g., `__main__.py` or `agent_executor.py`) and
36+
configure the ADK Agent Executor to call it.
3137

3238
```python
39+
# A2UI, ADK, and A2A imports
40+
from a2a.server.agent_execution import AgentExecutor, RequestContext
41+
from a2a.server.events import EventQueue
42+
from a2a.server.tasks import TaskUpdater
43+
from a2a.types import (
44+
DataPart,
45+
Part,
46+
Task,
47+
TaskState,
48+
TextPart,
49+
UnsupportedOperationError,
50+
)
51+
from a2a.utils import (
52+
new_agent_parts_message,
53+
new_agent_text_message,
54+
new_task,
55+
)
56+
from a2a.utils.errors import ServerError
57+
from a2ui.a2a.extension import try_activate_a2ui_extension
58+
59+
# MAUI Agent import
3360
from agent import MAUIAgent
34-
from agent_with_grounding import MAUIAgentWithGrounding
35-
36-
# Initialize the agent
37-
agent = MAUIAgent(base_url="http://localhost:10002")
38-
39-
# Use the agent to stream responses
40-
async for item in agent.stream(query, session_id, ui_version):
41-
if "parts" in item:
42-
# Process A2UI parts
43-
pass
44-
elif "updates" in item:
45-
# Process text updates
46-
pass
61+
62+
class MAUIAgentExecutor(AgentExecutor):
63+
64+
def __init__(self, agent: MAUIAgent):
65+
self.agent = agent
66+
67+
async def execute(
68+
self,
69+
context: RequestContext,
70+
event_queue: EventQueue,
71+
) -> None:
72+
query = context.get_user_input()
73+
active_ui_version = try_activate_a2ui_extension(context, self.agent.agent_card)
74+
task = context.current_task
75+
76+
# Create a new task if necessary
77+
if not task:
78+
task = new_task(context.message)
79+
await event_queue.enqueue_event(task)
80+
updater = TaskUpdater(event_queue, task.id, task.context_id)
81+
82+
# Handle each item in the streamed response.
83+
async for item in self.agent.stream(query, task.context_id, active_ui_version):
84+
is_task_complete = item["is_task_complete"]
85+
if not is_task_complete:
86+
message = None
87+
if "parts" in item:
88+
message = new_agent_parts_message(item["parts"], task.context_id, task.id)
89+
elif "updates" in item:
90+
message = new_agent_text_message(item["updates"], task.context_id, task.id)
91+
92+
if message:
93+
await updater.update_status(TaskState.working, message)
94+
continue
95+
96+
final_parts = item["parts"]
97+
98+
await updater.update_status(
99+
TaskState.completed,
100+
new_agent_parts_message(final_parts, task.context_id, task.id),
101+
final=True,
102+
)
103+
break
104+
105+
async def cancel(
106+
self, request: RequestContext, event_queue: EventQueue
107+
) -> Task | None:
108+
raise ServerError(error=UnsupportedOperationError())
109+
```
110+
111+
## Google API Keys
112+
113+
### Google Maps API Key
114+
115+
Agentic UI Toolkit requires an API Key to use Google Maps Platform products. To create a Google Maps API Key, follow the instructions in the [Google Maps Platform documentation](https://developers.google.com/maps/documentation/javascript/get-api-key).
116+
117+
Your API Key must have the following APIs enabled in the [Google Cloud Console](https://console.cloud.google.com/apis/credentials):
118+
119+
* Geocoding API
120+
* Maps JavaScript API
121+
* Places UI Kit
122+
* Routes API
123+
124+
To use Grounding Lite MCP, you must also enable:
125+
126+
* Maps Grounding Lite API
127+
128+
To support the use of Grounding Lite within the Python ADK backend, this API Key must be exported or contained within a `.env` file as `GOOGLE_MAPS_API_KEY`.
129+
130+
**Loading the Google Maps JavaScript API**
131+
132+
Your API Key must also be included when loading the Google Maps JavaScript API code. See the [Google Maps Platform Documentation](https://developers.google.com/maps/documentation/javascript/load-maps-js-api) for instructions on how to load the API, including configuring the API Key.
133+
134+
Agentic UI Toolkit requires features available in the Alpha channel. You must use `v=alpha` when loading the Maps JavaScript API. Learn more about versions in the [Google Maps Platform Documentation](https://developers.google.com/maps/documentation/javascript/versions).
135+
136+
Use of Agentic UI Toolkit requires several [Maps JavaScript API libraries](https://developers.google.com/maps/documentation/javascript/libraries). When loading the Google Maps JavaScript API, you must include the following libraries:
137+
138+
* maps
139+
* maps3d
140+
* marker
141+
* places
142+
* routes
143+
144+
### Gemini API Key
145+
146+
*Note: This API is variously referred to in Google Cloud as the* Gemini API *and the* Generative Language API.
147+
148+
If you are using Gemini as your LLM, you will also need a Google Cloud API Key with the *Generative Language API* enabled. In order to enable this API for your API Key, the *Gemini API* must be enabled for your Google Cloud project. You can enable this API in the [API Library](https://console.cloud.google.com/apis/library/generativelanguage.googleapis.com).
149+
150+
To create a new Google Cloud API Key, follow the instructions here in the [Google Cloud docs](https://docs.cloud.google.com/docs/authentication/api-keys#create).
151+
152+
This key must be exported or contained within a `.env` file as `GEMINI_API_KEY`
153+
154+
## Accessing Google Maps grounding data
155+
156+
Your agent can access Google Maps grounding data in two ways, depending on your project setup and needs:
157+
158+
1. [Grounding Lite MCP](https://developers.google.com/maps/ai/grounding-lite)
159+
2. [Grounding with Google Maps](https://docs.cloud.google.com/vertex-ai/generative-ai/docs/grounding/grounding-with-google-maps)
160+
161+
### Grounding Lite MCP
162+
163+
To use Grounding Lite MCP, you must first enable the Maps Grounding Lite API and create or update an API Key to support the required APIs following the [documentation](https://developers.google.com/maps/ai/grounding-lite#configure_llms_to_use_the_mcp_server).
164+
165+
### Grounding with Google Maps
166+
167+
To use Grounding with Google Maps, there are additional steps you must take to configure your environment:
168+
169+
1. Ensure you have the latest version of the genai python package.
170+
```bash
171+
pip install --upgrade google-genai
172+
```
173+
174+
2. Configure additional environment variables to connect to your project.
175+
```bash
176+
## Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
177+
## with appropriate values for your project.
178+
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
179+
export GOOGLE_CLOUD_LOCATION=global
180+
export GOOGLE_GENAI_USE_VERTEXAI=True
181+
```
182+
183+
3. Ensure you are authenticated to Google Cloud.
184+
```bash
185+
gcloud auth application-default login
47186
```
48187

188+
See the [documentation](https://docs.cloud.google.com/vertex-ai/generative-ai/docs/grounding/grounding-with-google-maps#googlegenaisdk_tools_google_maps_with_txt-python_genai_sdk) for more information.

‎client/web/README.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,8 @@ To build the package for use in an application:
1414

1515
## How to Integrate
1616

17-
To integrate these components into an existing application, you can refer to the sample in `a2ui-samples/client/web/react`.
17+
To integrate these components into an existing application, you can refer to the [Agentic UI Toolkit samples project](https://github.com/googlemaps-samples/a2ui).
18+
1819

1920
### 1. Link or Install the Package
2021
You can consume the package via npm linking for local development:

0 commit comments

Comments
 (0)