Agents in Gemini Enterprise: Unlocking Interactivity with A2UI

This article serves as a practical guide for developers who want to take their AI agent interactions to the next level — moving from plain text chat to interactive user interfaces using the A2UI (Agent to UI) protocol.

What is A2UI and what are its capabilities?

A2UI (Agent-to-UI) is an open protocol (a2ui.org) that allows AI agents to send structured user interfaces directly into the chat window. Instead of the model generating long and poorly structured text blocks, we can render for the user:

• Structured Visualizations (cards, columns, rows, tabs).
• Interactive Forms and Checklists (buttons, text inputs, checkboxes, multiple-choice selectors).

Key Concepts:

Interface layouts are defined using a flat JSON structure (the Adjacency List Model) and are processed on the client side to dynamically render modern, responsive UI elements.

How it works in practice (Interaction Showcase)

Imagine an agent designed to help a newcomer in a company (their virtual “Buddy”). The agent provides important information and ensures the newcomer completes all initial requirements. In such a scenario, it is ideal if the user can see a clear checklist and the current status of each task directly in the chat window.

Step 1: User sends a message to the agent

The user writes:

“Hi, I am new to the company, what should I do?”

Step 2: Agent’s response (Generating UI)

The agent doesn’t return plain text, but a JSON array defining the structure and data of the checklist:

[
  {
    "beginRendering": {
      "surfaceId": "default_onboarding",
      "root": "onboarding-checklist-card"
    }
  },
  {
    "dataModelUpdate": {
      "surfaceId": "default_onboarding",
      "contents": [
        {"key": "checklist_title", "valueString": "Welcome to the Company!"},
        {"key": "task1_status", "valueString": "🟢 Active"},
        {"key": "task1_desc", "valueString": "1. Sign safety training"},
        {"key": "task1_btn_text", "valueString": "Sign online"}
      ]
    }
  }
]

Step 3: User interacts with the interface

An interactive card with the checklist and button is rendered for the user:

Step 4: Reaction to user action (Event Handling)

Once the user clicks the “Sign online” button, the frontend client generates and sends a userAction event back to the server:

{
  "userAction": {
    "name": "completeSafetyAction",
    "surfaceId": "default_onboarding",
    "sourceComponentId": "task-1-btn",
    "context": {"taskId": "safety"}
  }
}

This event is translated on the server as a text input: "Selected: completeSafetyAction" and passed to the agent. The agent processes the state, updates the first task's status to "🟢 Completed", and activates the next task.

Step 5: User see updated interface

How to get an A2UI agent into the Gemini Enterprise App

The Gemini Enterprise App currently supports the A2UI standard version 0.8. This is fully sufficient for creating an interactive agent that sends responses in JSON format and gets correctly rendered by the client application. Using the Google Agent Development Kit (ADK), we can easily build such an agent, deploy it to Google Cloud Run, and register it to Gemini Enterprise App using the A2A protocol.

I prepare simple agent — https://github.com/pevikus/agent-a2ui-helloworld.

The Agent logic

Our agent could theoretically generate the entire JSON structure on its own. However, in direct interaction with the LLM, we quickly realize that forcing the model to generate the complete A2UI code (including all Column, Row, and Button definitions) for every response is highly inefficient. It leads to massive token consumption, slow response times, and a high risk of JSON syntax errors that break the rendering of the interface.

Therefore, we utilize a post-generation callback (configured as after_model_callback in ADK):

• We teach the model in its system instructions to send only raw data (dataModelUpdate) and information on which card to render (beginRendering).
• The server-side callback intercepts the generated response, retrieves the corresponding layout template (the surfaceUpdate step) from the local cache on the server, and merges it with the model's data.
• The callback also automatically generates a unique surfaceId for each new response to prevent overwriting and losing previous cards in the chat history.

Deploying the Agent to Cloud Run

To deploy the agent to Cloud Run, we must expose it as a web service (API). For this, we use the to_a2a() function from the ADK library, which automatically wraps our agent in a FastAPI application and sets up all required A2A paths. We then package this FastAPI application into a Docker container and deploy it to Google Cloud Run. Cloud Run automatically generates a secure HTTPS URL, which we use to register the agent in Gemini Enterprise.

Hello World Agent Example

A fully functional agent example is available directly in this Git repository - https://github.com/pevikus/agent-a2ui-helloworld. It is a simple agent that responds exclusively in JSON format, showcasing the capabilities of A2UI and its available components. For production use, this agent must be deployed to Cloud Run and registered within the Gemini Enterprise App.

Lessons Learned: 3 Practical Tips from Development

During the development of a production A2UI agent, we ran into several non-trivial obstacles. Here are 3 key lessons that will save you days of debugging:

1) Local Testing and Diacritics (Bypassing the btoa() bug)

The local development environment (adk web) uses a REST/SSE stream for communication. In the A2A protocol, binary UI data is sent as base64-encoded strings. However, calling the standard JS btoa() function on UTF-8 strings (containing special characters like Czech diacritics) on the local frontend client causes the application to crash (InvalidCharacterError).

• Solution: Detect the environment in the callback. If running locally, send the UI data wrapped in a custom text tag (e.g. <a2ui-json>... in UTF-8) which the frontend client reads safely. When running on Cloud Run, automatically switch to the official A2A base64 format required by Gemini Enterprise.

2) Component Caching

Forcing the LLM to generate the entire A2UI JSON structure (including all Column, Row, and Button definitions) on every input is inefficient. It causes high token usage, slow response times, and occasional JSON syntax errors that break the UI rendering.

• Solution: Keep the UI component definitions (templates) cached on the server. Teach the model in its system instructions only the structure of the data model, and let it output only the data (dataModelUpdate) and the render trigger (beginRendering). The server-side callback then retrieves the template from the cache and constructs the complete UI response itself.

3) Unique surfaceId for Each Response

If you use a static surface ID (e.g., surfaceId: "main") for all agent responses, each new response in the chat will overwrite the previous one. In the chat history, you will only see the last generated card, and the older ones will disappear or turn into empty white boxes.

• Solution: Generate a unique identifier (e.g., surface_{uuid}) in the callback for each response. This ensures that every card in the chat history has its own independent rendering surface, keeping the history stable and interactive.

Conclusion and Summary

The A2UI protocol represents a revolution in how users interact with AI agents. Instead of reading wall-of-text responses, users can complete tasks, view interactive maps, or control charts directly within the Gemini Enterprise chat window. While setting up such an agent requires overcoming some initial architectural challenges (FastAPI backend on Cloud Run, callbacks for component caching, and bypassing UTF-8 encoding), the resulting interactive experience is well worth the effort.

References

• **Official A2UI Specification **— The home page of the protocol with complete documentation.
• **Google Agent Development Kit (ADK)]** — Oficial documentation for Google Agent Development Kit.
• **Register and Manage A2UI Agents]** — Official Google Cloud documentation for integrating custom A2A agents.