Add Google ADK Agents integration for Temporal workflows

.github/workflows/ci.yml

@@ -104,12 +104,13 @@ jobs:
         env:
           TEMPORAL_TEST_PROTO3: 1
         run: |
+          uv remove google-adk --optional google-adk
           uv add --python 3.10 "protobuf<4"
           uv sync --all-extras
           poe build-develop
           poe gen-protos
           [[ -z $(git status --porcelain temporalio) ]] || (git diff temporalio; echo "Protos changed"; exit 1)
-          poe test -s
+          poe test -s --ignore=tests/contrib/google_adk_agents/
         timeout-minutes: 10
 
       # Do docs stuff (only on one host)

pyproject.toml

@@ -29,6 +29,7 @@ grpc = ["grpcio>=1.48.2,<2"]
 opentelemetry = ["opentelemetry-api>=1.11.1,<2", "opentelemetry-sdk>=1.11.1,<2"]
 pydantic = ["pydantic>=2.0.0,<3"]
 openai-agents = ["openai-agents>=0.3,<0.7", "mcp>=1.9.4, <2"]
+google-adk = ["google-adk>=1.27.0,<2"]
 
 [project.urls]
 Homepage = "https://github.com/temporalio/sdk-python"
@@ -60,6 +61,7 @@ dev = [
   "pytest-pretty>=1.3.0",
   "openai-agents>=0.3,<0.7; python_version >= '3.14'",
   "openai-agents[litellm]>=0.3,<0.7; python_version < '3.14'",
+  "openinference-instrumentation-google-adk>=0.1.8",
   "googleapis-common-protos==1.70.0",
   "pytest-rerunfailures>=16.1",
 ]

temporalio/contrib/google_adk_agents/README.md

@@ -0,0 +1,165 @@
+# Google ADK Agents SDK Integration for Temporal
+
+This package provides the integration layer between the Google ADK and Temporal. It allows ADK Agents to run reliably within Temporal Workflows by ensuring determinism and correctly routing external calls (network I/O) through Temporal Activities.
+
+## Benefits of Temporal to the ADK
+
+Temporal provides a holistic, unified solution that centralizes your orchestration needs in one Workflow abstraction. Rather than cobbling together separate servers, task queues, gateways, and databases, you get:
+
+- **Recovering from crashes and stalls automatically**, rather than manually managing [sessions](https://google.github.io/adk-docs/sessions/session/#example-examining-session-properties) and [resuming](https://google.github.io/adk-docs/runtime/resume/#resume-a-stopped-workflow) them. (Google offers [Vertex Agent Engine](https://docs.cloud.google.com/agent-builder/agent-engine/sessions/manage-sessions-adk), which still leaves resumption to the user). No need to set up a separate [database](https://dev.to/greyisheepai/mastering-google-adk-databasesessionservice-and-events-complete-guide-to-event-injection-and-pdm#understanding-adk-databasesessionservice)
+    - Along with [Retries](https://docs.temporal.io/encyclopedia/retry-policies) and mechanisms for handling backpressure and rate limits.
+- **Support for [ambient](https://temporal.io/blog/orchestrating-ambient-agents-with-temporal)/long-running agent patterns** via blocking awaits and [worker versioning](https://docs.temporal.io/production-deployment/worker-deployments/worker-versioning).
+- **Automatic execution state [persistence](https://docs.temporal.io/temporal-service/persistence)**, not just for agent interactions but for any custom automations in your workflows, without setting up a separate [database](https://dev.to/greyisheepai/mastering-google-adk-databasesessionservice-and-events-complete-guide-to-event-injection-and-pdm#understanding-adk-databasesessionservice).
+- For **Human-in-the-Loop patterns,** an api gateway to scalably [route](https://docs.temporal.io/task-routing) incoming messages (such as user chats) to awaken the correct workflow on your worker pool.
+- [**Long-running tools](https://google.github.io/adk-docs/tools-custom/function-tools/#long-run-tool) support** using [Activities](https://docs.temporal.io/activities) — no need to set up and maintain microservices.
+- [Manage and debug your agent workflow](https://temporal.io/resources/on-demand/demo-ai-agent) execution and pinpoint problems using Temporal UI.
+
+## Benefits of the ADK to Temporal
+
+ADK provides: (from the [ADK overview](https://google.github.io/adk-docs/#learn-more)):
+
+- Improved Agent development velocity with a first-class Agentic abstraction and integration with LLMs and an ecosystem of tools.
+- Improved agent robustness using built-in evals
+- Build complex agents using its Multi-agent architecture.
+- [Safety and security](https://google.github.io/adk-docs/safety/), via guardrails and integrations with sandboxing solutions like Vertex Agent Runtime.
+
+## What's Included
+
+### Core ADK Integration
+- **`TemporalModel`**: Intercepts model calls and executes them as Temporal activities
+- **`GoogleAdkPlugin`**: Worker plugin that configures runtime determinism and Pydantic serialization
+- **`invoke_model`**: Activity for executing LLM model calls with proper error handling
+
+### MCP (Model Context Protocol) Integration  
+- **`TemporalMcpToolSet`**: Executes MCP tools as Temporal activities
+- **`TemporalMcpToolSetProvider`**: Manages toolset creation and activity registration
+- Full support for tool confirmation and event actions within workflows
+
+### OpenTelemetry Integration
+- Automatic instrumentation for ADK components when exporters are provided
+- Tracing integration that works within Temporal's execution context
+- Support for custom span exporters
+
+### Key Features
+
+#### 1. Deterministic Runtime
+- Replaces `time.time()` with `workflow.now()` when in workflow context
+- Replaces `uuid.uuid4()` with `workflow.uuid4()` for deterministic IDs
+- Automatic setup when using `GoogleAdkPlugin`
+
+#### 2. Activity-Based Model Execution
+Model calls are intercepted and executed as Temporal activities with configurable:
+- Timeouts (schedule-to-close, start-to-close, heartbeat)
+- Retry policies
+- Task queues
+- Cancellation behavior
+- Priority levels
+
+#### 3. Sandbox Compatibility
+- Automatic passthrough for `google.adk`, `google.genai`, and `mcp` modules
+- Works with both sandboxed and unsandboxed workflow runners
+
+#### 4. Advanced Serialization
+- Pydantic payload converter for ADK objects
+- Proper handling of complex ADK data types
+- Maintains type safety across workflow boundaries
+
+## Usage
+
+### Basic Setup
+
+**Agent (Workflow) Side:**
+```python
+from temporalio.contrib.google_adk_agents import TemporalModel
+from google.adk import Agent
+
+
+# Add to agent
+agent = Agent(
+    name="test_agent",
+    model=TemporalModel("gemini-2.5-pro"), 
+)
+```
+
+**Worker Side:**
+
+```python
+from temporalio.client import Client
+from temporalio.worker import Worker
+from temporalio.contrib.google_adk_agents import GoogleAdkPlugin
+
+client = await Client.connect(
+    "localhost:7233",
+    plugins=[
+        GoogleAdkPlugin(),
+    ],
+)
+
+worker = Worker(
+    client,
+    task_queue="my-queue",
+)
+```
+
+### Advanced Features
+
+**With MCP Tools:**
+
+```python
+import os
+from google.adk import Agent
+from google.adk.tools.mcp_tool import McpToolset
+from google.adk.tools.mcp_tool.mcp_session_manager import StdioConnectionParams
+from mcp import StdioServerParameters
+from temporalio.client import Client
+from temporalio.worker import Worker
+
+from temporalio.contrib.google_adk_agents import (
+    GoogleAdkPlugin,
+    TemporalMcpToolSetProvider,
+    TemporalMcpToolSet
+)
+
+# Create toolset provider
+provider = TemporalMcpToolSetProvider("my-tools",
+                                      lambda _: McpToolset(
+                                          connection_params=StdioConnectionParams(
+                                              server_params=StdioServerParameters(
+                                                  command="npx",
+                                                  args=[
+                                                      "-y",
+                                                      "@modelcontextprotocol/server-filesystem",
+                                                      os.path.dirname(os.path.abspath(__file__)),
+                                                  ],
+                                              ),
+                                          ),
+                                      ))
+
+# Use in agent workflow
+agent = Agent(
+    name="test_agent",
+    model="gemini-2.5-pro",
+    tools=[TemporalMcpToolSet("my-tools")]
+)
+
+client = await Client.connect(
+    "localhost:7233",
+    plugins=[
+        GoogleAdkPlugin(toolset_providers=[provider]),
+    ],
+)
+
+# Configure worker
+worker = Worker(
+    client,
+    task_queue="task-queue"
+)
+```
+
+## Integration Points
+
+This integration provides comprehensive support for running Google ADK Agents within Temporal workflows while maintaining:
+- **Determinism**: All non-deterministic operations are routed through Temporal
+- **Observability**: Full tracing and activity visibility
+- **Reliability**: Proper retry handling and error propagation  
+- **Extensibility**: Support for custom tools via MCP protocol

temporalio/contrib/google_adk_agents/__init__.py

@@ -0,0 +1,20 @@
+"""Temporal Integration for ADK.
+
+This module provides the necessary components to run ADK Agents within Temporal Workflows.
+"""
+
+from temporalio.contrib.google_adk_agents._mcp import (
+    TemporalMcpToolSet,
+    TemporalMcpToolSetProvider,
+)
+from temporalio.contrib.google_adk_agents._model import TemporalModel
+from temporalio.contrib.google_adk_agents._plugin import (
+    GoogleAdkPlugin,
+)
+
+__all__ = [
+    "GoogleAdkPlugin",
+    "TemporalMcpToolSet",
+    "TemporalMcpToolSetProvider",
+    "TemporalModel",
+]