Repository navigation
Conversation
… apps ADK ships runners for Slack and Microsoft Teams but none for Google Chat, so every team builds its own webhook middleware. GoogleChatRunner serves a Chat app's HTTP endpoint, verifies that each request is signed by Google Chat, acknowledges it right away because Chat gives up after 30 seconds, runs the agent in the background, and posts the replies with the Chat API. Sessions follow what users see in Chat: each thread of a threaded space, or each conversation session of a direct message, is one session, while an unthreaded direct message or group conversation is a single session. Events from Chat apps and from Chat apps built as Workspace add-ons are both accepted. Install with `pip install "google-adk[google-chat]"`.
Google Chat now reports direct messages and group chats as threaded, because users can start in-line threads in them. GoogleChatRunner treated that as one conversation per thread, so every top-level DM message started a new session and got its reply in a thread. Only named spaces, and DMs with conversation sessions turned on, are now organized by thread. A message written inside an in-line thread of a DM still gets its reply in that thread, in the DM's session. Also document that, in spaces, Chat only sends the app messages that mention it.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Link to Issue or Description of Change
2. Or, if no issue exists, describe the change:
Problem:
ADK ships runners for Slack (
SlackRunner) and Microsoft Teams (TeamsRunner) but nothing for Google Chat. Teams that want an ADK agent in Google Chat each write their own webhook middleware: acknowledge the event before Chat's 30-second limit, run the agent in the background, post the answer back with the Chat API, and decide how Chat conversations map to ADK sessions. That last choice is easy to get wrong. If every top-level message in a DM becomes its own session, or sessions expire on a timer, the agent forgets the conversation while the Chat history still shows it.Solution:
Add
google.adk.integrations.google_chat.GoogleChatRunner, modeled onTeamsRunner:Endpoint. It serves a Chat app's HTTP endpoint with aiohttp (
create_app/start), accepting events from both Chat apps and Chat apps built as Google Workspace add-ons.Request verification. It checks the bearer token that Google Chat signs, for both audiences:
email/email_verifiedagainstchat@system.gserviceaccount.com, or against the add-on's per-project service account.audience=Noneturns verification off for local testing and logs a warning.Background runs. It acknowledges each event right away with
{}, runs the agent in the background, and serializes runs per session. Background replies are drained on shutdown.Replies. It posts replies with
spaces.messages.createas the app (chat.botscope, Application Default Credentials by default). In threaded spaces it replies in the thread usingREPLY_MESSAGE_FALLBACK_TO_NEW_THREAD. The client is httpx, using the repo's_mtls_utils, so it moves tochat.mtls.googleapis.comand presents the client certificate when mTLS is configured.Session mapping:
sessionState == THREAD) gets one session per session thread.The user id is the sender (
users/{id}), as inTeamsRunner. Session ids are hashed, because Chat resource names contain/.Agent input and output. The runner reads
argumentText, so the agent never sees the app's@mention. Thought parts are not posted. Errors produce a generic reply and never expose exception text.Also included:
google-chatextra (aiohttp only)GOOGLE_CHATexperimental feature flagdocs/guides/integrations/google_chat/google_chat_runner/index.mdcontributing/samples/integrations/google_chat_agentsampleTesting Plan
Unit Tests:
tests/unittests/integrations/google_chat/test_google_chat_runner.pydrives the real aiohttp endpoint with Chat events and records replies on a fake Chat API server. Only the LLM (MockModel) and Google's token verification are faked. It covers:I mutated the session-mapping and account-check logic, and the tests fail as expected.
pre-commit runpasses on all changed files, including the compliance and mTLS checks.mypy(strict) reports no issues for the new package.Manual End-to-End (E2E) Tests:
To exercise the real
google-authverification path rather than the faked one, I served the runner locally with a fake Chat API, usinggcloud auth print-identity-tokenas a genuine Google-signed ID token. The audience and account were taken from that token's claims:I also ran the sample as a live Google Chat app:
--no-cpu-throttling), Gemini on Vertex AI, and request verification on.The live test found a bug that the first version's unit tests missed. Chat now reports DMs as
spaceThreadingState: THREADED_MESSAGESwithoutsessionState, so every top-level DM message started a new session and got a threaded reply. The second commit fixes this, and the unit tests now use the real payload shape.Checklist
Additional context
TeamsRunner. Attachments, cards and slash commands are not passed to the agent.spaces.streamMessages(Developer Preview), are left out. They could come in follow-ups.