Skip to content

feat(integrations): add GoogleChatRunner to run agents as Google Chat apps - #8148

Open
batou9150 wants to merge 2 commits into
google:mainfrom
batou9150:feat/google-chat-runner
Open

batou9150 wants to merge 2 commits into
google:mainfrom
batou9150:feat/google-chat-runner

Conversation

@batou9150

@batou9150 batou9150 commented Nov 14, 2026 •

Copy link
Copy Markdown

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 on TeamsRunner:

  • 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:

    • HTTP endpoint URL: a Google-signed ID token. The runner checks email / email_verified against chat@system.gserviceaccount.com, or against the add-on's per-project service account.
    • Project number: a JWT self-signed by Chat, checked against Chat's x509 certs.

    audience=None turns 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.create as the app (chat.bot scope, Application Default Credentials by default). In threaded spaces it replies in the thread using REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD. The client is httpx, using the repo's _mtls_utils, so it moves to chat.mtls.googleapis.com and presents the client certificate when mTLS is configured.

  • Session mapping:

    • A thread in a threaded space is one session.
    • A DM with conversation sessions turned on (sessionState == THREAD) gets one session per session thread.
    • An unthreaded DM or group conversation is one session as a whole.

    The user id is the sender (users/{id}), as in TeamsRunner. 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:

  • the google-chat extra (aiohttp only)
  • the GOOGLE_CHAT experimental feature flag
  • a unit guide at docs/guides/integrations/google_chat/google_chat_runner/index.md
  • the contributing/samples/integrations/google_chat_agent sample

Testing Plan

Unit Tests:

  • I have added or updated unit tests for my change.
  • All unit tests pass locally.

tests/unittests/integrations/google_chat/test_google_chat_runner.py drives 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:

  • reply routing for DMs and threads
  • one session per DM or group chat, even though Chat reports them as threaded, with replies inside an in-line thread when the user writes there
  • acknowledging before the agent finishes
  • the DM, threaded-space and DM-session mappings
  • URL-safe session ids
  • add-on events
  • mention stripping
  • ordering within a session
  • ignored events (other types, bot senders, empty text)
  • thought parts not posted
  • error replies (agent failure, blocked response, Chat API failure)
  • draining on shutdown
  • 401 for missing, invalid or wrong-account tokens
  • add-on service account and project-number JWT verification
  • mTLS endpoint selection
$ pytest tests/unittests/integrations/google_chat -q
27 passed

$ pytest tests/unittests -n auto -q
24890 passed, 113 skipped, 39 xfailed, 2 xpassed, 44 subtests passed in 366.01s

I mutated the session-mapping and account-check logic, and the tests fail as expected. pre-commit run passes 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-auth verification path rather than the faked one, I served the runner locally with a fake Chat API, using gcloud auth print-identity-token as a genuine Google-signed ID token. The audience and account were taken from that token's claims:

real google token: HTTP 200
tampered token: HTTP 401
no token: HTTP 401
replies posted to Chat API: ['pong']

I also ran the sample as a live Google Chat app:

  • Deployment: Cloud Run (--no-cpu-throttling), Gemini on Vertex AI, and request verification on.
  • App: a Chat app built as a Workspace add-on, so the add-on service account path was exercised.
Scenario Result
Requests without a Chat-signed token (no token, or a valid Google ID token from another account) HTTP 401
Chat events All acknowledged with HTTP 200 in under 0.1 s, with replies posted afterwards through the Chat API
Space, @mention in a thread Reply in that thread, with context kept across mentions in the thread
DM, top-level messages Top-level replies, one session for the whole DM
DM, message written inside an in-line thread Reply in that thread, still in the DM's session (a fact given in the thread was recalled at top level)

The live test found a bug that the first version's unit tests missed. Chat now reports DMs as spaceThreadingState: THREADED_MESSAGES without sessionState, 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

  • I have read the CONTRIBUTING.md document.
  • I have performed a self-review of my own code.
  • I have commented my code, particularly in hard-to-understand areas.
  • I have added tests that prove my fix is effective or that my feature works.
  • New and existing unit tests pass locally with my changes.
  • I have manually tested my changes end-to-end.
  • Any dependent changes have been merged and published in downstream modules.

Additional context

  • Scope. Text only, matching TeamsRunner. Attachments, cards and slash commands are not passed to the agent.
  • Out of scope. Proactive messages, and streaming through the new spaces.streamMessages (Developer Preview), are left out. They could come in follow-ups.

… 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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants