From 2eb9dbe0448a6264dacf8b521415d1e5ed2672ac Mon Sep 17 00:00:00 2001 From: maplexu Date: Mon, 31 Aug 2026 12:47:44 -0400 Subject: [PATCH 1/4] docs: document Google ADK integration (AI-282) --- .../integrations/google-adk-agents.mdx | 156 ++++++++++++++++++ sidebars.js | 1 + .../IntegrationsGrid/integrations-data.json | 9 + 3 files changed, 166 insertions(+) create mode 100644 docs/develop/typescript/integrations/google-adk-agents.mdx diff --git a/docs/develop/typescript/integrations/google-adk-agents.mdx b/docs/develop/typescript/integrations/google-adk-agents.mdx new file mode 100644 index 0000000000..5d6c5e4d33 --- /dev/null +++ b/docs/develop/typescript/integrations/google-adk-agents.mdx @@ -0,0 +1,156 @@ +--- +id: google-adk-agents +title: Google ADK integration +sidebar_label: Google ADK +toc_max_heading_level: 2 +tags: + - 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. +--- + +import { ReleaseNoteHeader } from '@site/src/components'; + +Temporal's integration with the [Google Agent Development Kit (ADK)](https://google.github.io/adk-docs/) lets you run +ADK agents as durable Temporal Workflows. The agent graph, including its orchestration, tool selection, and state, runs +inside the Workflow. Model inference and Model Context Protocol (MCP) calls run as Activities. + +This separation keeps the ADK programming model while adding Temporal's failure recovery. A Worker can stop while an +agent is running, then another Worker can replay the Workflow and continue from the last completed model or MCP call. +Temporal records each Activity result in Event History, so those calls aren't repeated during replay. + +The `GoogleAdkPlugin` configures the Worker for ADK, and `TemporalModel` replaces a standard ADK model inside Workflow +code. The integration also provides Workflow-safe APIs for Activity-backed tools, MCP servers, and streaming model +responses. + + + +The code excerpts in this guide come from the +[Google ADK samples](https://github.com/temporalio/samples-typescript/tree/main/google-adk-agents). Refer to the samples +for complete applications that run with a real model or an API-key-free test model. + +## Prerequisites + +- This guide assumes you are familiar with Google ADK. If you aren't, refer to the + [Google ADK documentation](https://google.github.io/adk-docs/) for an introduction to agents, runners, and tools. +- If you are new to Temporal, read [Understanding Temporal](/evaluate/understanding-temporal) or take the + [Temporal 101](https://learn.temporal.io/courses/temporal_101/) course. +- Set up your local development environment by following + [Set up your local with the TypeScript SDK](/develop/typescript/set-up-your-local-typescript). Leave the Temporal + development server running if you want to run the samples locally. + +## Install the Google ADK integration + +Install the Temporal integration and its Google ADK peer dependencies. Keep all `@temporalio/*` packages in your +application on the same version. + +```bash +npm install @temporalio/google-adk-agents @google/adk @google/genai +``` + +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. + +## Run an ADK agent in a Workflow + +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. + + +[google-adk-agents/src/agent-chat/workflows.ts](https://github.com/temporalio/samples-typescript/blob/main/google-adk-agents/src/agent-chat/workflows.ts) +```ts +const agent = new LlmAgent({ + name: 'assistant', + model: new TemporalModel('gemini-2.5-flash'), + instruction: 'Continue the conversation using its prior context. Respond in one sentence.', +}); +const runner = new InMemoryRunner({ agent, appName: 'agent-chat' }); +``` + + +Register `GoogleAdkPlugin` on the Worker that executes the Workflow. The plugin installs the model Activities and the +Workflow bundler configuration required by Google ADK. + + +[google-adk-agents/src/agent-chat/worker.ts](https://github.com/temporalio/samples-typescript/blob/main/google-adk-agents/src/agent-chat/worker.ts) +```ts +const worker = await Worker.create({ + connection, + taskQueue: 'google-adk-agent-chat', + workflowsPath: require.resolve('./workflows'), + plugins: [ + new GoogleAdkPlugin(process.env.MODEL_PROVIDER === 'fake' ? { modelProvider: offlineModelProvider() } : {}), + ], +}); +await worker.run(); +``` + + +The default model provider uses Google ADK's model registry. You can pass a custom `modelProvider` to +`GoogleAdkPlugin` to configure another provider, route model names through a proxy, or supply a test double. Register +the plugin on the Worker; a Client plugin is not required. + +## Add tools and MCP servers + +Google ADK function tools run as part of the agent graph inside the Workflow. Use them for deterministic operations, +such as transforming values or updating agent state. A tool that reads a file, calls an API, queries a database, or +performs other I/O must run outside the Workflow. + +Use `activityAsTool` from `@temporalio/google-adk-agents/workflow` to expose an existing Activity to an agent. The tool +name identifies the registered Activity, and its Activity options control timeouts and retries. The +[tools sample](https://github.com/temporalio/samples-typescript/tree/main/google-adk-agents/src/tools) shows a +deterministic function tool and an Activity-backed weather tool in the same agent. + +For MCP, register a named toolset factory in `GoogleAdkPlugin` on the Worker, then use a `TemporalMCPToolset` with the +same name in Workflow code. Listing tools and calling them execute as Activities. The +[MCP sample](https://github.com/temporalio/samples-typescript/tree/main/google-adk-agents/src/mcp) shows this pairing +with a stateless filesystem server and an API-key-free test implementation. + +## Stream model responses + +Set `streamingTopic` in `TemporalModel` options to publish model response chunks through +[`@temporalio/workflow-streams`](https://www.npmjs.com/package/@temporalio/workflow-streams). Stream delivery is +at-least-once. The complete model response returned by the Activity is the deterministic value used by the Workflow. + +The [streaming sample](https://github.com/temporalio/samples-typescript/tree/main/google-adk-agents/src/streaming) +shows how a Workflow publishes chunks and waits for a stream consumer to finish. + +## Test your agents + +The `@temporalio/google-adk-agents/testing` entry point provides `fakeModelProvider` and `mockMCPToolset`. Pass these +helpers to `GoogleAdkPlugin` to test an agent without model credentials or a live MCP server. This keeps model and tool +behavior controlled while exercising the real Worker plugin, Workflow bundle, and Activities. + +The Google ADK samples use the same testing APIs for their API-key-free execution path. For Workflow changes, also use +[replay testing](/develop/typescript/best-practices/testing-suite#replay) to verify that the current code +remains compatible with recorded Event Histories. + +## 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. +The [observability sample](https://github.com/temporalio/samples-typescript/tree/main/google-adk-agents/src/observability) +shows the plugin order and an OpenTelemetry span processor that records model usage. + +Model and MCP calls appear as Activities in Temporal Event History even when OpenTelemetry is not configured. ADK span +attributes can contain prompts and model responses, so send them only to an approved destination or remove sensitive +attributes in your span processor. + +## Understand replay safety and operational behavior + +- `TemporalModel` disables nested model SDK retries so Temporal Activity retry policies control retries and backoff. +- Model calls and MCP operations are not repeated during Workflow replay. A failed Activity attempt can be retried + 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. + +## Resources + +- [Google ADK integration package](https://www.npmjs.com/package/@temporalio/google-adk-agents) +- [Google ADK integration source](https://github.com/temporalio/sdk-typescript/tree/main/contrib/google-adk-agents) +- [Google ADK samples](https://github.com/temporalio/samples-typescript/tree/main/google-adk-agents) +- [Google ADK documentation](https://google.github.io/adk-docs/) +- [Temporal TypeScript SDK documentation](/develop/typescript) diff --git a/sidebars.js b/sidebars.js index ba42163641..481b4f8010 100644 --- a/sidebars.js +++ b/sidebars.js @@ -1131,6 +1131,7 @@ const developTypeScriptCategory = { }, items: [ 'develop/typescript/integrations/ai-sdk', + 'develop/typescript/integrations/google-adk-agents', 'develop/typescript/integrations/langsmith', 'develop/typescript/integrations/openai-agents', 'develop/typescript/integrations/strands-agents', diff --git a/src/components/IntegrationsGrid/integrations-data.json b/src/components/IntegrationsGrid/integrations-data.json index 081cb5624e..715f2312a5 100644 --- a/src/components/IntegrationsGrid/integrations-data.json +++ b/src/components/IntegrationsGrid/integrations-data.json @@ -89,6 +89,15 @@ "sdk": "Go", "href": "/develop/go/integrations/google-adk" }, + { + "name": "Google ADK", + "description": "Run Google ADK agents as durable Temporal Workflows with the TypeScript SDK.", + "tags": [ + "Agent framework" + ], + "sdk": "TypeScript", + "href": "/develop/typescript/integrations/google-adk-agents" + }, { "name": "Google GenAI", "description": "Call Google Gemini models durably from Temporal Workflows with the Google Gen AI SDK.", From 02db63236f7f7258bbd53a55bf62e6d61e03a24e Mon Sep 17 00:00:00 2001 From: maplexu Date: Wed, 2 Sep 2026 18:23:57 -0400 Subject: [PATCH 2/4] AI-282 Add Google ADK to TypeScript integrations --- docs/develop/typescript/index.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/develop/typescript/index.mdx b/docs/develop/typescript/index.mdx index 4cf2e9edcc..eba8a0c866 100644 --- a/docs/develop/typescript/index.mdx +++ b/docs/develop/typescript/index.mdx @@ -85,6 +85,7 @@ Once your local Temporal Service is set up, continue building with the following ## [Integrations](/develop/typescript/integrations) - [Braintrust integration](https://www.braintrust.dev/docs/integrations/sdk-integrations/temporal#typescript) +- [Google ADK integration](/develop/typescript/integrations/google-adk-agents) - [LangSmith integration](/develop/typescript/integrations/langsmith) - [Mastra integration](https://mastra.ai/guides/deployment/temporal) - [OpenAI Agents SDK integration](/develop/typescript/integrations/openai-agents) From 67e49d1ede174651af1c5de6087f9f2c51f7aef2 Mon Sep 17 00:00:00 2001 From: maplexu Date: Thu, 3 Sep 2026 14:51:16 -0400 Subject: [PATCH 3/4] AI-282: Revise Google ADK integration guide --- .../integrations/google-adk-agents.mdx | 259 ++++++++++++------ .../IntegrationsGrid/integrations-data.json | 6 +- 2 files changed, 181 insertions(+), 84 deletions(-) diff --git a/docs/develop/typescript/integrations/google-adk-agents.mdx b/docs/develop/typescript/integrations/google-adk-agents.mdx index 5d6c5e4d33..365a426be3 100644 --- a/docs/develop/typescript/integrations/google-adk-agents.mdx +++ b/docs/develop/typescript/integrations/google-adk-agents.mdx @@ -7,29 +7,21 @@ tags: - 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. +description: Run Google ADK agents as durable Temporal Workflows in TypeScript, with model and MCP calls running as retryable Activities. --- import { ReleaseNoteHeader } from '@site/src/components'; -Temporal's integration with the [Google Agent Development Kit (ADK)](https://google.github.io/adk-docs/) lets you run -ADK agents as durable Temporal Workflows. The agent graph, including its orchestration, tool selection, and state, runs -inside the Workflow. Model inference and Model Context Protocol (MCP) calls run as Activities. +The Temporal Google Agent Development Kit (ADK) integration runs an ADK agent graph as a durable Temporal Workflow. +The agent loop, tool selection, and state run in the Workflow, while model inference and Model Context Protocol (MCP) +operations run as Activities. Completed calls are recorded in Event History and aren't repeated during replay. -This separation keeps the ADK programming model while adding Temporal's failure recovery. A Worker can stop while an -agent is running, then another Worker can replay the Workflow and continue from the last completed model or MCP call. -Temporal records each Activity result in Event History, so those calls aren't repeated during replay. - -The `GoogleAdkPlugin` configures the Worker for ADK, and `TemporalModel` replaces a standard ADK model inside Workflow -code. The integration also provides Workflow-safe APIs for Activity-backed tools, MCP servers, and streaming model -responses. +`GoogleAdkPlugin` configures the Worker and Workflow bundle. In Workflow code, `TemporalModel` replaces a standard ADK +model and routes each model call to an Activity. The integration also provides Workflow-safe APIs for Activity-backed +tools, MCP servers, and streamed model responses. -The code excerpts in this guide come from the -[Google ADK samples](https://github.com/temporalio/samples-typescript/tree/main/google-adk-agents). Refer to the samples -for complete applications that run with a real model or an API-key-free test model. - ## Prerequisites - This guide assumes you are familiar with Google ADK. If you aren't, refer to the @@ -38,59 +30,68 @@ for complete applications that run with a real model or an API-key-free test mod [Temporal 101](https://learn.temporal.io/courses/temporal_101/) course. - Set up your local development environment by following [Set up your local with the TypeScript SDK](/develop/typescript/set-up-your-local-typescript). Leave the Temporal - development server running if you want to run the samples locally. + development server running to run the samples locally. +- Install Node.js 22 or later to run the samples. ## Install the Google ADK integration -Install the Temporal integration and its Google ADK peer dependencies. Keep all `@temporalio/*` packages in your -application on the same version. +Install the integration and its Google ADK peer dependencies. Keep all `@temporalio/*` packages in your application on +the same version. ```bash -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" ``` -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. +Version 1.23.0 of the integration supports `@google/adk` 1.5.x. The upper bound is required because the Workflow bundle +uses compatibility shims for that ADK line. Newer ADK versions can fail while bundling the Workflow. + +The Worker reads Gemini credentials from `GOOGLE_API_KEY` or `GEMINI_API_KEY`. Credentials remain in the Worker +process. Model requests and responses are Activity inputs and results, so they are stored in Event History. Use a +[Payload Codec to encrypt sensitive data](/develop/typescript/best-practices/data-handling/data-encryption), and account +for the [programming model limits](/cloud/limits#programming-model-level), including the 2 MB limit on a single payload. ## Run an ADK agent in a Workflow -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. +The [basic Google ADK sample](https://github.com/temporalio/samples-typescript/tree/main/google-adk-agents/src/basic) +contains a complete Workflow, Worker, and Client. It uses the standard ADK `LlmAgent` and `InMemoryRunner` APIs in the +Workflow, with `TemporalModel` as the agent's model. The runner iterates over ADK events and returns the final response. - -[google-adk-agents/src/agent-chat/workflows.ts](https://github.com/temporalio/samples-typescript/blob/main/google-adk-agents/src/agent-chat/workflows.ts) -```ts -const agent = new LlmAgent({ - name: 'assistant', - model: new TemporalModel('gemini-2.5-flash'), - instruction: 'Continue the conversation using its prior context. Respond in one sentence.', -}); -const runner = new InMemoryRunner({ agent, appName: 'agent-chat' }); +The Worker registers `GoogleAdkPlugin`, which installs the model Activities and the Workflow bundler configuration. +The Client starts the Workflow normally and doesn't need the plugin. + +Use each API from its package entry point: + +| Entry point | APIs | +| --- | --- | +| `@temporalio/google-adk-agents` | `GoogleAdkPlugin` for Worker code | +| `@temporalio/google-adk-agents/workflow` | `TemporalModel`, `TemporalMCPToolset`, and `activityAsTool` for Workflow code | +| `@temporalio/google-adk-agents/testing` | `fakeModelProvider` and `mockMCPToolset` for tests | + +Start the Worker, then run the Client from the sample directory: + +```bash +npx tsx src/basic/worker.ts +npx tsx src/basic/client.ts ``` - -Register `GoogleAdkPlugin` on the Worker that executes the Workflow. The plugin installs the model Activities and the -Workflow bundler configuration required by Google ADK. +## Configure model calls + +Pass Activity options to `TemporalModel` to set timeouts, retries, a Task Queue, or an Activity summary. The default +`startToCloseTimeout` is one minute. - -[google-adk-agents/src/agent-chat/worker.ts](https://github.com/temporalio/samples-typescript/blob/main/google-adk-agents/src/agent-chat/worker.ts) ```ts -const worker = await Worker.create({ - connection, - taskQueue: 'google-adk-agent-chat', - workflowsPath: require.resolve('./workflows'), - plugins: [ - new GoogleAdkPlugin(process.env.MODEL_PROVIDER === 'fake' ? { modelProvider: offlineModelProvider() } : {}), - ], +const model = new TemporalModel('gemini-2.5-flash', { + activity: { + startToCloseTimeout: '5 minutes', + heartbeatTimeout: '30 seconds', + retry: { maximumAttempts: 3 }, + }, }); -await worker.run(); ``` - -The default model provider uses Google ADK's model registry. You can pass a custom `modelProvider` to -`GoogleAdkPlugin` to configure another provider, route model names through a proxy, or supply a test double. Register -the plugin on the Worker; a Client plugin is not required. +The plugin disables retries in the underlying model SDK so that the Activity retry policy controls retries and backoff. +Set `heartbeatTimeout` to detect a dead Worker and deliver cancellation to a long model call. The Activity heartbeats on +a timer, so a Heartbeat Timeout doesn't detect a stalled call; `startToCloseTimeout` bounds a stalled call. ## Add tools and MCP servers @@ -98,57 +99,153 @@ Google ADK function tools run as part of the agent graph inside the Workflow. Us such as transforming values or updating agent state. A tool that reads a file, calls an API, queries a database, or performs other I/O must run outside the Workflow. -Use `activityAsTool` from `@temporalio/google-adk-agents/workflow` to expose an existing Activity to an agent. The tool -name identifies the registered Activity, and its Activity options control timeouts and retries. The -[tools sample](https://github.com/temporalio/samples-typescript/tree/main/google-adk-agents/src/tools) shows a -deterministic function tool and an Activity-backed weather tool in the same agent. +Use `activityAsTool` to expose an existing Activity to an agent. Its `name` must match an Activity registered in the +Worker's `activities` option. The model's arguments object becomes the Activity's single argument, and the `activity` +option controls its timeouts and retries. The [tools sample](https://github.com/temporalio/samples-typescript/tree/main/google-adk-agents/src/tools) +shows the Workflow and Worker configuration together. -For MCP, register a named toolset factory in `GoogleAdkPlugin` on the Worker, then use a `TemporalMCPToolset` with the -same name in Workflow code. Listing tools and calling them execute as Activities. The -[MCP sample](https://github.com/temporalio/samples-typescript/tree/main/google-adk-agents/src/mcp) shows this pairing -with a stateless filesystem server and an API-key-free test implementation. +For MCP, register a named factory with `mcpToolsets: { : factory }` in the Worker plugin, then create a +`TemporalMCPToolset` with the same name in Workflow code. Listing tools and calling them execute as Activities. Each +operation opens a new MCP session, so session state doesn't carry between operations unless the factory returns a +long-lived toolset. MCP failures often have no status and are retryable, so set `activity.retry.maximumAttempts` on the +`TemporalMCPToolset` when retries must be bounded. See the complete Worker and Workflow pair in the +[MCP sample](https://github.com/temporalio/samples-typescript/tree/main/google-adk-agents/src/mcp). ## Stream model responses -Set `streamingTopic` in `TemporalModel` options to publish model response chunks through -[`@temporalio/workflow-streams`](https://www.npmjs.com/package/@temporalio/workflow-streams). Stream delivery is -at-least-once. The complete model response returned by the Activity is the deterministic value used by the Workflow. +Install `@temporalio/workflow-streams`, host a `WorkflowStream` at the top of the Workflow, and set `streamingTopic` in +the `TemporalModel` options. The model call must also request streaming, either through ADK runner configuration with +`StreamingMode.SSE` or by calling `generateContentAsync(request, true)`. A streaming call without a topic fails. + +The model Activity publishes chunks to the topic and returns the complete response to the Workflow. The Activity result +is the deterministic value used during replay. Stream delivery is at-least-once, and a retried Activity publishes its +chunks again from the beginning. The [streaming sample](https://github.com/temporalio/samples-typescript/tree/main/google-adk-agents/src/streaming) shows how a Workflow publishes chunks and waits for a stream consumer to finish. -## Test your agents - -The `@temporalio/google-adk-agents/testing` entry point provides `fakeModelProvider` and `mockMCPToolset`. Pass these -helpers to `GoogleAdkPlugin` to test an agent without model credentials or a live MCP server. This keeps model and tool -behavior controlled while exercising the real Worker plugin, Workflow bundle, and Activities. +## Test and observe your agents -The Google ADK samples use the same testing APIs for their API-key-free execution path. For Workflow changes, also use -[replay testing](/develop/typescript/best-practices/testing-suite#replay) to verify that the current code -remains compatible with recorded Event Histories. +The testing entry point provides `fakeModelProvider` and `mockMCPToolset`. Pass them to `GoogleAdkPlugin` to test without +model credentials or a live MCP server while exercising the Worker plugin, Workflow bundle, and Activities. -## Add observability +Use [replay testing](/develop/typescript/best-practices/testing-suite#replay) for Workflow changes. Pass +`plugins: [new GoogleAdkPlugin()]` to `Worker.runReplayHistory` because the plugin's bundler configuration is required +to load Google ADK in the replay sandbox. 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. +agent, model, and tool spans from the Workflow sandbox. + +```ts +plugins: [new OpenTelemetryPlugin({ resource, spanProcessor }), new GoogleAdkPlugin()] +``` + +The OpenTelemetry plugin's Worker sink suppresses span export during replay. Export is at-least-once because a failed or +timed-out Workflow Task can execute again without being a replay. The [observability sample](https://github.com/temporalio/samples-typescript/tree/main/google-adk-agents/src/observability) shows the plugin order and an OpenTelemetry span processor that records model usage. -Model and MCP calls appear as Activities in Temporal Event History even when OpenTelemetry is not configured. ADK span -attributes can contain prompts and model responses, so send them only to an approved destination or remove sensitive -attributes in your span processor. +ADK span attributes can contain prompts and model responses. Send them only to an approved destination or remove +sensitive attributes in the span processor. `ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS` doesn't control this behavior in a +Workflow because the Workflow sandbox doesn't expose Worker environment variables. + +## Reference and troubleshooting + +### Feature support + +The integration supports ADK agent graphs, sequential and delegated multi-agent patterns, function tools, Activities as +tools, MCP toolsets, human approval through Signals or Updates, structured model output, SSE response streaming, and +OpenTelemetry tracing. Live bidirectional streaming through `BaseLlm.connect` isn't supported in Workflows. + +### Composing with other plugins + +Register observability and governance plugins before `GoogleAdkPlugin`. In particular, place `OpenTelemetryPlugin` +first so that ADK's Workflow-side spans bind to its tracer provider. Register `GoogleAdkPlugin` only on the Worker; a +Client plugin isn't required. + +Custom payload and failure converter modules load before the plugin's polyfills. If either module imports `@google/adk` +or `@google/genai`, import `@temporalio/google-adk-agents/workflow` first in that module. + +### Replay safety + +The ADK runner, agent graph, regular function tools, and callbacks execute inside the Workflow and must remain +deterministic. `TemporalModel`, `TemporalMCPToolset`, and `activityAsTool` move model calls, MCP operations, and other I/O +into Activities. Completed Activity results are read from Event History during replay. + +The full model request and response cross the Activity boundary and are recorded in Event History. For long-running +conversations, use [Continue-As-New](/develop/typescript/workflows/continue-as-new) before Event History approaches its +limits. + +### Configuration + +Options under `activity` accept the standard TypeScript SDK `ActivityOptions` fields. + +| API | Option | Default | Behavior | +| --- | --- | --- | --- | +| `GoogleAdkPlugin` | `modelProvider` | ADK `LLMRegistry` | Resolves model names in model Activities. Use it for another provider, proxy, or test double. | +| `GoogleAdkPlugin` | `mcpToolsets` | `{}` | Maps names to MCP factories and registers `-listTools` and `-callTool` Activities. | +| `TemporalModel` | `activity` | `startToCloseTimeout: '1 minute'` | Configures every model Activity. | +| `TemporalModel` | `summary` | ADK agent name, then `adk.invokeModel ` | Sets the Activity summary. A function receives the request and must be deterministic. This takes precedence over `activity.summary`. | +| `TemporalModel` | `streamingTopic` | None | Publishes SSE response chunks to this Workflow streams topic when streaming is requested. | +| `TemporalModel` | `streamingBatchInterval` | `'100 milliseconds'` | Sets how frequently response chunks are batched for publication. | + +| API | Option | Default | Behavior | +| --- | --- | --- | --- | +| `TemporalMCPToolset` | `name` | Required | Selects the Worker-registered factory and names its Activity pair. | +| `TemporalMCPToolset` | `toolFilter` | All tools | Advertises only listed tool names, matched after applying `prefix`. ADK `ToolPredicate` filters aren't supported. | +| `TemporalMCPToolset` | `prefix` | None | Advertises each tool as `_` without changing its MCP server name. | +| `TemporalMCPToolset` | `activity` | `startToCloseTimeout: '1 minute'` | Configures tool discovery and tool-call Activities. | +| `TemporalMCPToolset` | `connectionParams` | None | Creates a real MCP toolset only outside a Workflow. Worker-side configuration belongs in `mcpToolsets`. | +| `activityAsTool` | `name` | Required | Names the tool and the registered Activity it calls. | +| `activityAsTool` | `description` | Required | Describes the tool to the model. | +| `activityAsTool` | `parameters` | Empty object schema | Defines the arguments passed to the Activity as its single input. | +| `activityAsTool` | `activity` | `startToCloseTimeout: '1 minute'` | Configures the Activity call. | +| `FakeLlm` | `model` | `'fake-model'` | Sets the test double's model name. | +| `FakeLlm` | `responses` | One canned text response | Sets the responses yielded in order. | +| `fakeModelProvider` | `responses` | One canned text response | Returns a `FakeLlm` for every model name. | +| `mockMCPToolset` | `definitions` | Required | Creates an MCP factory from tool declarations and handlers. | + +An MCP factory can return connection parameters or a `BaseToolset`. Connection parameters create and close one MCP +session per Activity. A `BaseToolset` remains owned by the factory, isn't closed by the plugin, and can maintain state. + +### Failure behavior + +The plugin exports constants for its public `ApplicationFailure.type` values. Model and MCP failures originate in +Activities, so catch the surrounding `ActivityFailure` and inspect its cause chain for these types. + +| Failure type | Meaning | +| --- | --- | +| `GoogleAdkModelError[.]` | A model call failed. Statuses 408, 409, 429, and 5xx are retryable; other HTTP statuses are non-retryable. A failure without a status is retryable. `x-should-retry` overrides this classification, and `retry-after` or `retry-after-ms` sets the next retry delay. | +| `GoogleAdkMCPError[.]` | MCP discovery or a tool call failed. It uses the same status classification as model errors. Failures without a status are retryable, so set `activity.retry.maximumAttempts` to bound retries. | +| `GoogleAdkMCPToolNotFound` | A factory-provided `BaseToolset` didn't contain the requested tool. This failure is non-retryable. | +| `GoogleAdkStreamingTopicRequired` | SSE streaming was requested without `streamingTopic`. This failure is non-retryable and is thrown directly in the Workflow. | +| `GoogleAdkUnsupported` | `BaseLlm.connect` was called in a Workflow. This failure is non-retryable and is thrown directly in the Workflow. | -## Understand replay safety and operational behavior +ADK converts an error from an agent's model call into an event. The integration records that failure and re-raises it +after the Workflow or handler frame returns. To recover in an ADK `onModelErrorCallback`, pass the error to +`markModelFailureHandled` and return a substitute event created with ADK's `createEvent`. Cancellation can't be handled +this way. -- `TemporalModel` disables nested model SDK retries so Temporal Activity retry policies control retries and backoff. -- Model calls and MCP operations are not repeated during Workflow replay. A failed Activity attempt can be retried - 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. +If a model call fails with a sandbox error such as `fetch is not defined`, check that the agent uses +`new TemporalModel(...)` instead of a raw model string. A raw model makes ADK attempt the network call inside the +Workflow instead of routing it to an Activity. ## Resources +- The [basic sample](https://github.com/temporalio/samples-typescript/tree/main/google-adk-agents/src/basic) runs one + durable model call. +- The [tools sample](https://github.com/temporalio/samples-typescript/tree/main/google-adk-agents/src/tools) exposes an + Activity as an ADK tool. +- The [agent patterns sample](https://github.com/temporalio/samples-typescript/tree/main/google-adk-agents/src/agent-patterns) + delegates work across multiple agents. +- The [MCP sample](https://github.com/temporalio/samples-typescript/tree/main/google-adk-agents/src/mcp) connects an MCP + server through Activities. +- The [streaming sample](https://github.com/temporalio/samples-typescript/tree/main/google-adk-agents/src/streaming) + publishes model response chunks through Workflow streams. +- The [human approval sample](https://github.com/temporalio/samples-typescript/tree/main/google-adk-agents/src/human-approval) + gates a long-running tool with a Signal or Update. +- The [observability sample](https://github.com/temporalio/samples-typescript/tree/main/google-adk-agents/src/observability) + exports ADK spans and records model usage. - [Google ADK integration package](https://www.npmjs.com/package/@temporalio/google-adk-agents) - [Google ADK integration source](https://github.com/temporalio/sdk-typescript/tree/main/contrib/google-adk-agents) - [Google ADK samples](https://github.com/temporalio/samples-typescript/tree/main/google-adk-agents) diff --git a/src/components/IntegrationsGrid/integrations-data.json b/src/components/IntegrationsGrid/integrations-data.json index 715f2312a5..7ab5c7880b 100644 --- a/src/components/IntegrationsGrid/integrations-data.json +++ b/src/components/IntegrationsGrid/integrations-data.json @@ -73,7 +73,7 @@ }, { "name": "Google ADK", - "description": "Orchestrate Google ADK agents with durable Temporal Workflows.", + "description": "Run Google ADK agents as durable Temporal Workflows.", "tags": [ "Agent framework" ], @@ -82,7 +82,7 @@ }, { "name": "Google ADK", - "description": "Run Google ADK agents with durable execution using the Temporal Go SDK.", + "description": "Run Google ADK agents as durable Temporal Workflows.", "tags": [ "Agent framework" ], @@ -91,7 +91,7 @@ }, { "name": "Google ADK", - "description": "Run Google ADK agents as durable Temporal Workflows with the TypeScript SDK.", + "description": "Run Google ADK agents as durable Temporal Workflows.", "tags": [ "Agent framework" ], From dac617704d1fa756195f65e6c6338453e05c895c Mon Sep 17 00:00:00 2001 From: maplexu Date: Thu, 3 Sep 2026 16:44:34 -0400 Subject: [PATCH 4/4] AI-282 Fix Google ADK credential docs and feature support --- .../typescript/integrations/google-adk-agents.mdx | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/docs/develop/typescript/integrations/google-adk-agents.mdx b/docs/develop/typescript/integrations/google-adk-agents.mdx index 365a426be3..7d97a390c1 100644 --- a/docs/develop/typescript/integrations/google-adk-agents.mdx +++ b/docs/develop/typescript/integrations/google-adk-agents.mdx @@ -45,7 +45,7 @@ npm install @temporalio/google-adk-agents "@google/adk@>=1.5.0 <1.6.0" "@google/ Version 1.23.0 of the integration supports `@google/adk` 1.5.x. The upper bound is required because the Workflow bundle uses compatibility shims for that ADK line. Newer ADK versions can fail while bundling the Workflow. -The Worker reads Gemini credentials from `GOOGLE_API_KEY` or `GEMINI_API_KEY`. Credentials remain in the Worker +The Worker reads Gemini credentials from `GOOGLE_GENAI_API_KEY` or `GEMINI_API_KEY`. Credentials remain in the Worker process. Model requests and responses are Activity inputs and results, so they are stored in Event History. Use a [Payload Codec to encrypt sensitive data](/develop/typescript/best-practices/data-handling/data-encryption), and account for the [programming model limits](/cloud/limits#programming-model-level), including the 2 MB limit on a single payload. @@ -153,9 +153,16 @@ Workflow because the Workflow sandbox doesn't expose Worker environment variable ### Feature support -The integration supports ADK agent graphs, sequential and delegated multi-agent patterns, function tools, Activities as -tools, MCP toolsets, human approval through Signals or Updates, structured model output, SSE response streaming, and -OpenTelemetry tracing. Live bidirectional streaming through `BaseLlm.connect` isn't supported in Workflows. +| Feature | Support | Notes | +| --- | --- | --- | +| ADK agent graphs, including sequential and delegated multi-agent patterns | Supported | Compose agents normally; delegated agents remain part of the durable Workflow graph. | +| Function tools and Activities as tools | Supported | Regular function tools run in the Workflow and must be deterministic; `activityAsTool` moves I/O to Activities. | +| MCP toolsets | Supported | `toolFilter` accepts only string arrays, not ADK `ToolPredicate`, and filters advertised names after prefixing. Connection-parameter factories open one session per Activity; factory-returned `BaseToolset`s may remain long-lived. | +| Human approval through Signals or Updates | Supported | Use Signals for asynchronous input or Updates when the caller needs an accepted result. | +| Structured model output | Supported | ADK output schemas work with durable agent execution. | +| SSE response streaming | Supported | Requires `streamingTopic`; delivery is at-least-once, and retries may republish from the beginning. | +| OpenTelemetry tracing | Supported | Register `OpenTelemetryPlugin` before `GoogleAdkPlugin`. | +| Live bidirectional streaming through `BaseLlm.connect` | Not supported in Workflows | Use SSE response streaming for supported streaming behavior. | ### Composing with other plugins