Guide for incorporating the ADK in my UI

[riturajtiwari]

Is there a guide on how best to integrate the ADK in my own UI, such as the best way to list agents, look for events and manage conversation turns?

[adk-bot]

Response from ADK Answering Agent (experimental, answer may be inaccurate)

TLDR: The recommended way to integrate the ADK with a custom UI is to create a backend that uses runner.run_async to process agent logic. This method returns a stream of Event objects. Your UI should listen to this stream and check event.is_final_response() to identify the end of a conversational turn. For web development, we highly recommend using the AG-UI framework with CopilotKit, as it's specifically designed to simplify building UIs for ADK agents. To list agents, your backend will need to expose an endpoint that lists the agents found in your project's src/my_app/agents/ directory.

---

Hello! Thank you for your question. Here’s a guide on how to approach integrating the ADK into your custom UI, covering the points you raised.

Managing Conversation Turns and Events

The core of the interaction between a UI and the ADK is managed through a stream of Event objects. The primary function you'll use is runner.run_async, which executes the agent's logic and yields events as they happen. [1]

A key part of handling this stream in your UI is to identify the final response for a given turn. The Event object has a helper method, is_final_response(), for this exact purpose. [1, 2]

Here is a basic example of how you would process events from the runner:

from adk.api import Session, new_message

async def process_user_request(session: Session, user_input: str):
    # Add the user's message to the session
    session.add(new_message(user_input))

    # Run the agent and process the stream of events
    async for event in session.runner.run_async():
        print(f"Received event: {event.content}")

        # Check if this is the final event for the turn
        if event.is_final_response():
            print("Agent's turn is complete.")
            # You can now update the UI to indicate the turn is over
            break

Conversations are tracked using a Session object, which maintains the history of events and the agent's state across multiple turns. [3]

Building a Custom UI

While you can build a UI from scratch, we provide tools to make this much easier, especially for web-based interfaces.

• Server-Sent Events (SSE): For real-time communication, a good pattern is to expose an SSE endpoint from your backend (e.g., using FastAPI). Your frontend can then connect to this endpoint to receive the stream of events from the runner. The documentation provides an example of how to set this up. [4]
• AG-UI and CopilotKit: This is our recommended solution for building rich user experiences. AG-UI is a framework designed to work with ADK, and it uses CopilotKit to handle the complexities of streaming conversations and rendering UI components. It greatly simplifies the process of building a frontend for your agents. [5]

Listing Agents

The ADK framework discovers agents based on a specific directory structure. When you run adk web, it looks for agents within the src/your_app/agents/ directory. Each agent is expected to be in its own subdirectory containing an agent.py file. [6]

The adk web development UI includes a dropdown to select between these discovered agents. If you are building a custom UI, you would need to create a simple API endpoint in your backend application that inspects this directory and returns a list of available agents to your frontend.

You can also structure agents into teams or hierarchies by defining a parent agent and passing other agents to its sub_agents parameter. Your UI could potentially reflect this hierarchical structure. [7, 8]

We hope this guidance helps you get started!

---

[1] ADK Events
[2] ADK Project Overview and Architecture (source)
[3] ADK Sessions
[4] Custom Streaming in ADK
[5] AG-UI Tutorial
[6] ADK Project Overview and Architecture (source)
[7] Multi-agent Systems in ADK
[8] Building a Team of Agents Tutorial

[hangfei]

You can also check out how adk-web(https://github.com/google/adk-web) is implemented.

[riturajtiwari]

Thanks @hangfei ! The direction that worked for us was a 2-service combo - Copilot Kit for frontend and AG-UI+ADK as aa single integrated service for the agent backend.

[rcleveng]

I'm not sure if it's recommended or not, but I also added the AG-UI to the same service as ADK exposed (trying to minimize services and also not have to fork and replace what already exists).

It'd be great to have that documented as a "well lit path" or documented as "here be dragons"