Loading events in adk

[lenixbyte]

How do we emit semantic progress/loading events in Google ADK so the UI can display states like “Searching…” or “Modifying…” ?

[adk-bot]

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

TLDR: Use ADK's Session State to communicate loading states. Have your tools update a key in the session state (e.g., ui_status: "Searching...") before a long-running operation and then clear it upon completion. Your UI should listen for Event objects and update its display based on the state_delta in those events.

---

Hello! That's a great question. Here’s how you can handle semantic progress and loading events in Google ADK.

The recommended approach is to use ADK's Session State to explicitly signal these UI changes. Here is a step-by-step guide:

1. Update the Session State from a Tool: Before a tool begins a long-running operation (like a search or a modification), it can update the session state to indicate that it's starting. Once the operation is complete, it can update the state again.

   You can create a simple tool to manage this state. For example, a tool that updates the state to "Searching..." before calling the actual search tool.

   from adk.api import tool
   
   @tool
   def search_with_status(query: str) -> str:
     """Searches for the query and updates the UI status."""
     # Update the state to show a "Searching..." message in the UI
     update_state({"ui_status": f"Searching for {query}..."})
   
     # --- Perform your actual long-running search operation here ---
     results = your_search_function(query)
     # -------------------------------------------------------------
   
     # Clear the status message from the UI
     update_state({"ui_status": None})
   
     return results

   This approach is demonstrated in some of the ADK samples, which use a similar update_state tool to modify the session. [1]

2. Listen for State Changes in the UI: Your UI layer should be connected to the ADK run or run_live method. This method yields Event objects. Your UI code should listen for these events and check for changes in the session state.

   Each Event object contains an actions field, which in turn can have a state_delta. This delta contains only what has changed in the state. [2] When your UI receives an event with a state_delta that includes your ui_status key, it should update the display accordingly.

3. Alternative - Inferring State from Tool Calls: Another way is for the UI to infer the state by listening for specific tool call and tool output events. When the UI sees an event that a tool like google_search has been called, it can display a "Searching..." message. When it sees the corresponding output event from that tool, it can hide the message. This works well for simple cases and is a core part of how ADK's event-driven architecture is designed. [2, 3]

By explicitly managing a ui_status in the session state, you can provide more granular and semantic information to your users, like "Modifying...", "Analyzing...", etc., directly from the logic of your agent and tools.

For more details, you can refer to the official documentation on Events [2] and Session State (Context) [4].

---

[1] agent.py in rewind_session sample - https://github.com/google/adk-python/blob/main/contributing/samples/rewind_session/agent.py
[2] ADK Events Documentation - https://google.github.io/adk-docs/events/
[3] ADK Streaming Developer Guide - https://google.github.io/adk-docs/streaming/dev-guide/part3/
[4] ADK Context (Session State) Documentation - https://google.github.io/adk-docs/context/