AI-282: Document the TypeScript Google ADK integration - #5212
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
📖 Docs PR preview links
|
There was a problem hiding this comment.
🟡 Changes recommended
The parent TypeScript SDK integration list omits the new Google ADK guide.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Pull request overview
Adds a prerelease TypeScript guide for durable Google ADK agents, pending the synchronized samples update.
Changes:
- Documents setup, tools, MCP, streaming, testing, observability, and replay safety.
- Adds the guide to the TypeScript sidebar and integrations grid.
File summaries
| File | Description |
|---|---|
docs/develop/typescript/integrations/google-adk-agents.mdx |
Adds the integration guide. |
sidebars.js |
Adds sidebar navigation. |
src/components/IntegrationsGrid/integrations-data.json |
Adds the TypeScript integration card. |
Review details
- Files reviewed: 3/3 changed files
- Comments generated: 1
- Review effort level: Balanced
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
DABH
left a comment
DABH
left a comment
There was a problem hiding this comment.
Thanks for putting this together - nice to have the TS page landing next to Python and Go, and everything on it checks out against the plugin source as far as I can tell. The comments mostly fall into four themes: (1) the install line needs the ADK peer range now that 2.0.0 is latest; (2) the hello world stops before the run loop, and there's no client step or import paths, so I don't think a reader can get an agent running from the page alone yet; (3) the streaming, retry and heartbeat wording needs tightening to match the README/source (the heartbeat one is partly my fault from #2321); (4) three of the eight sample scenarios never get mentioned.
Two things not tied to a line in this diff:
docs/develop/typescript/index.mdxL85-93 lists the TS integrations and needs this page added (Copilot flagged this too) - the Python and Go index pages both list their ADK guides.- Most of the missing code needs a small samples-typescript follow-up to add markers (a
basicscenario, and hoisting the fake-provider toggles out of the marked regions). Happy to help with that one.
#515 has merged, so once snipsync shows no diff this can come out of draft. Also see the naming comment on the slug - would rather settle that before this publishes.
| @@ -0,0 +1,156 @@ | |||
| --- | |||
| id: google-adk-agents | |||
There was a problem hiding this comment.
Naming question rather than a blocker, but it's free now and costs a redirect later: Python and Go both live at /integrations/google-adk, and every other cross-SDK integration shares one slug (openai-agents / strands-agents / langsmith). I get that the TS pages follow the npm name, but Python's module is google_adk_agents and its slug is still google-adk, title/sidebar_label here already say "Google ADK", and ReleaseNoteHeader's guidePath builds /develop/<sdk>/<path> assuming the trailing path matches across SDKs. Would you be open to google-adk? (Same change in sidebars.js and the registry href.)
There was a problem hiding this comment.
P.S. We are working on cutting over to a separate repo (AI-420) and plan to rename this to google-adk there for parity - so should do that here now anyways
| - Google ADK | ||
| - TypeScript SDK | ||
| - Temporal SDKs | ||
| description: Run Google ADK agent graphs as durable Temporal Workflows while model and MCP calls execute as retryable Activities. |
There was a problem hiding this comment.
(nit) The three ADK pages share a title, so in search results the description is the only differentiator, and the sibling pages all name their SDK. AGENTS.md also asks for roughly 120-155 chars (this is 116).
| description: Run Google ADK agent graphs as durable Temporal Workflows while model and MCP calls execute as retryable Activities. | |
| description: Run Google ADK agents as durable Temporal Workflows in TypeScript, with model and MCP calls running as retryable Activities. |
| application on the same version. | ||
|
|
||
| ```bash | ||
| npm install @temporalio/google-adk-agents @google/adk @google/genai |
There was a problem hiding this comment.
The peer range on the package is @google/adk >=1.5.0 <1.6.0, and @google/adk@latest is 2.0.0 now (1.6.0 shipped 8/6, 2.0.0 on 8/21), so the unpinned install is a bit of a trap. I checked with npm install --dry-run: npm 11 happens to back off to 1.5.0 to satisfy the peer dep, but --legacy-peer-deps (and yarn/pnpm in practice) pull 2.0.0, which the README says can break the workflow bundle (README:22-25, "the ceiling is exact by design"). Can we pin it in the command and say why, like the README does? Probably worth a Node version line too (package engines is >=20.3, the samples README says 22+).
| npm install @temporalio/google-adk-agents @google/adk @google/genai | |
| npm install @temporalio/google-adk-agents "@google/adk@>=1.5.0 <1.6.0" "@google/genai@^2.9.0" |
Then something like: "Version 1.23.0 of the integration supports @google/adk 1.5.x only. The upper bound is deliberate: the plugin's Workflow-sandbox shims are keyed to that ADK line, and a newer minor or major (1.6.0 and 2.0.0 are both published) can break the Workflow bundle."
| ``` | ||
|
|
||
| The Worker reads Gemini credentials from `GOOGLE_API_KEY` or `GEMINI_API_KEY`. Credentials stay in the Worker process | ||
| and are not stored in Workflow inputs or Event History. |
There was a problem hiding this comment.
The credentials sentence is right (nothing credential-shaped in InvokeModelArgs), but the flip side is that the full LlmRequest (contents, system instruction, tool schemas) and the LlmResponse[] are Activity inputs/results, so prompts and responses land in Event History and the UI. Worth a sentence pointing at Payload Codecs (/develop/typescript/best-practices/data-handling/data-encryption), the 2MB payload limit, and CAN for long chats? FWIW the Python/Go ADK pages don't say this either, so not blocking on it - but this sentence kind of invites the question.
|
|
||
| Use the standard ADK `LlmAgent` and runner APIs in your Workflow, but configure the agent with `TemporalModel`. Each | ||
| call through `TemporalModel` becomes an Activity, while the runner and agent graph remain in deterministic Workflow | ||
| code. |
There was a problem hiding this comment.
Related: the page never says where TemporalModel comes from. The root entry only exports GoogleAdkPlugin (src/index.ts); TemporalModel, TemporalMCPToolset, activityAsTool and markModelFailureHandled live at @temporalio/google-adk-agents/workflow, the doubles at /testing, and both snippets start after their imports - so import { TemporalModel } from '@temporalio/google-adk-agents' is the first thing people will try, and it doesn't compile. openai-agents.mdx has a little import-paths table for exactly this (L47-57), worth copying that pattern?
| ## Add observability | ||
|
|
||
| Compose `GoogleAdkPlugin` after `OpenTelemetryPlugin` from `@temporalio/interceptors-opentelemetry` to export ADK's | ||
| agent, model, and tool spans from the Workflow sandbox. The Workflow interceptor suppresses span export during replay. |
There was a problem hiding this comment.
Small precision thing: IIUC the replay gate is the OTel plugin's Worker sink (default callDuringReplay: false), not a Workflow interceptor - and that makes export at-least-once rather than exactly-once, since a Workflow Task retry re-runs live (README:236-242; the exact-count test in telemetry.test.ts is pinned on the same thing). Also, ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS=false is inert in the sandbox because process.env is {} there (src/plugin.ts:85), which I'd mention right next to the "attributes can contain prompts" sentence since that's the first knob people will reach for. Maybe also the one-line plugins: [new OpenTelemetryPlugin(...), new GoogleAdkPlugin()] array plus the OTel package install, like openai-agents.mdx does (L635-640)?
| - Model calls and MCP operations are not repeated during Workflow replay. A failed Activity attempt can be retried | ||
| according to its retry policy. |
There was a problem hiding this comment.
This reads as "set a retry policy and failures retry", but most model 4xx are marked non-retryable regardless of policy - only 408/409/429/5xx/no-status retry (src/activities.ts:33, 244-257; README:118-122: "a bad request fails the Workflow on the first attempt no matter the retry policy"). And since ADK absorbs model errors into events, the plugin re-raises when the Workflow/Update frame returns, so a try/catch around the runner won't see it - the escape hatch is onModelErrorCallback + markModelFailureHandled. Bigger picture, I think this deserves its own section right after the hello world ("Configure timeouts, retries, and failure handling"?) with a TemporalModelOptions.activity example - the page never shows how to set timeouts/retries at all, and the default startToCloseTimeout is 1 minute (src/model.ts:87), which a thinking-mode model will blow through.
| - Model calls and MCP operations are not repeated during Workflow replay. A failed Activity attempt can be retried | |
| according to its retry policy. | |
| - Model calls and MCP operations are not repeated during Workflow replay. A model failure whose HTTP status is 408, 409, | |
| 429, or 5xx (or that has no status) is retried according to the Activity retry policy. Any other 4xx is non-retryable | |
| and fails the Workflow on the first attempt regardless of retry policy. To recover inside the agent instead, handle the | |
| error in an ADK `onModelErrorCallback`, call `markModelFailureHandled`, and return a substitute event. |
| according to its retry policy. | ||
| - Regular ADK function tools run inside the Workflow and must remain deterministic. Use `activityAsTool` for I/O. | ||
| - Live bidirectional streaming through `BaseLlm.connect` is not supported inside Workflows. | ||
| - Configure a heartbeat timeout for long model Activities when you need cancellation delivery and progress detection. |
There was a problem hiding this comment.
I think I'm partly responsible for this one - my suggested wording on sdk-typescript#2321 said a heartbeat would catch a stalled call, and the README you landed corrected it: the Activities heartbeat on a timer at half the timeout whether or not the call is progressing (src/activities.ts:216-228; streaming additionally heartbeats per chunk), so heartbeatTimeout detects a dead Worker and delivers cancellation, but not a stall - startToCloseTimeout (1 minute by default) is what bounds a hung call. Suggest matching the README:
| - Configure a heartbeat timeout for long model Activities when you need cancellation delivery and progress detection. | |
| - Set `heartbeatTimeout` on `TemporalModel` (or `TemporalMCPToolset`) so a dead Worker is detected and cancellation | |
| reaches a long model call. The Activities heartbeat on a timer, so a Heartbeat Timeout does not detect a stalled call; | |
| `startToCloseTimeout` (one minute by default) does. |
|
|
||
| ## Resources | ||
|
|
||
| - [Google ADK integration package](https://www.npmjs.com/package/@temporalio/google-adk-agents) |
There was a problem hiding this comment.
Three of the eight scenarios (multi-agent, human-in-the-loop, structured-output) never appear on the page, and agent-chat only shows up as a snippet path even though its Updates/Query/Continue-As-New pattern is the most Temporal-y thing in the samples. Cheapest fix is a ## Samples table like the one in the samples README (the Python and Go pages both close with one). Longer term I'd love short HITL and long-conversation sections once markers exist - happy to help with the samples-side PR.
| }, | ||
| { | ||
| "name": "Google ADK", | ||
| "description": "Run Google ADK agents as durable Temporal Workflows with the TypeScript SDK.", |
There was a problem hiding this comment.
(nit) The three Google ADK entries now have three different descriptions, whereas every other cross-SDK entry repeats one sentence and skips the SDK name (the card already shows the SDK pill). Suggest one shared string, e.g. "Run Google ADK agents as durable Temporal Workflows." - happy for the Python/Go edits to ride along here or in a follow-up.
This adds the public TypeScript guide for the Google ADK integration. The page explains what the plugin makes durable, how to install and configure it, and the high-level APIs for tools, MCP, streaming, testing, observability, and replay safety. It also adds the page to the TypeScript sidebar and integrations grid.
The synchronized code excerpts depend on temporalio/samples-typescript#515, so this PR is draft until that lands. Focused MDX compilation, CI-scoped Vale, sidebar and integration-data validation, and cross-repository snippet validation pass.