feat: Add Temporal integration and deterministic runtime support

[marcusmotill]

ADK Temporal Integration Internals

⚠️ Note: This is a Proof of Concept. Do not attempt to merge this as is. All temporal specific code must be moved to temporal sdk

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.

Core Concepts

1. Interception Flow (AgentPlugin )

The AgentPlugin acts as a middleware that intercepts model calls (e.g., agent.generate_content) before they execute.

Workflow Interception:

1. Intercept: The ADK invokes before_model_callback when an agent attempts to call a model.
2. Delegate: The plugin calls workflow.execute_activity(), routing the request to Temporal for execution.
3. Return: The plugin awaits the activity result and returns it immediately. The ADK stops its own request processing, using the activity result as the final response.

This ensures that all model interactions are recorded in the Temporal Workflow history, enabling reliable replay and determinism.

2. Dynamic Activity Registration

To provide visibility in the Temporal UI, activities are dynamically named after the calling agent (e.g., MyAgent.generate_content). Since agent names are not known at startup, the integration uses Temporal's dynamic activity registration.

@activity.defn(dynamic=True)
async def dynamic_activity(args: Sequence[RawValue]) -> Any:
    ...

When the workflow executes an activity with an unknown name (e.g., MyAgent.generate_content), the worker routes the call to dynamic_activity. This handler inspects the activity_type and delegates execution to the appropriate internal logic (_handle_generate_content), enabling arbitrary activity names without explicit registration.

3. Usage & Configuration

The integration requires setup on both the Agent (Workflow) side and the Worker side.

Agent Setup (Workflow Side)

Attach the AgentPlugin to your ADK agent. This safely routes model calls through Temporal activities. You must provide activity options (e.g., timeouts) as there are no defaults.

from datetime import timedelta
from temporalio.common import RetryPolicy
from google.adk.integrations.temporal import AgentPlugin

# 1. Define Temporal Activity Options
activity_options = {
    "start_to_close_timeout": timedelta(minutes=1),
    "retry_policy": RetryPolicy(maximum_attempts=3)
}

# 2. Add Plugin to Agent
agent = Agent(
    model="gemini-2.5-pro",
    plugins=[
        # Routes model calls to Temporal Activities
        AgentPlugin(activity_options=activity_options)  
    ]
)

# 3. Use Agent in Workflow
# When agent.generate_content() is called, it will execute as a Temporal Activity.

Worker Setup

Install the WorkerPlugin on your Temporal Worker. This handles serialization and runtime determinism.

from temporalio.worker import Worker
from google.adk.integrations.temporal import WorkerPlugin

async def main():
    worker = Worker(
        client,
        task_queue="my-queue",
        # Configures ADK Runtime & Pydantic Support
        plugins=[WorkerPlugin()]
    )
    await worker.run()

What WorkerPlugin Does:

• Data Converter: Enables Pydantic serialization for ADK objects.
• Interceptors: Sets up specific ADK runtime hooks for determinism (replacing time.time, uuid.uuid4) before workflow execution.
• TODO: is this enough . Unsandboxed Workflow Runner: Configures the worker to use the UnsandboxedWorkflowRunner, allowing standard imports in ADK agents.

[gemini-code-assist]

Summary of Changes

Hello @marcusmotill, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the ADK by integrating with Temporal workflows, thereby addressing critical challenges related to determinism and I/O traceability in AI agent execution. It achieves this by introducing a new runtime abstraction that provides deterministic time and UUID generation, alongside a suite of helper classes that seamlessly bridge ADK agents and tools with Temporal activities. This ensures that all agent actions, including LLM calls and tool executions, are durably recorded and replayable within the Temporal Event History, facilitating robust and observable AI applications.

Highlights

• Temporal Integration: Introduces first-class support for Temporal workflows within the ADK, enabling durable and traceable AI agent executions.
• Deterministic Runtime: Adds a new google.adk.runtime module to abstract system time and random state, ensuring determinism for Temporal's replay mechanism.
• Temporal Integration Helpers: Provides TemporalModel to wrap LLM calls as Temporal Activities and activity_as_tool to convert Temporal Activities into ADK Tools.
• Multi-Agent & Serialization Support: Verifies compatibility with Agent-as-a-Tool and Handoffs in Temporal workflows, and adds Pydantic serialization for ADK objects.
• Integration Tests: Includes a new manual integration test (manual_test_temporal_integration.py) to verify Temporal functionality across single and multi-agent scenarios.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[adk-bot]

Response from ADK Triaging Agent

Hello @marcusmotill, thank you for creating this PR!

Your PR is missing unit tests. Could you please add unit tests for your change? You can add or update tests under tests/unittests/, following existing naming conventions (e.g., test_<module>_<feature>.py).

This information will help reviewers to review your PR more efficiently. Thanks!

[gemini-code-assist]

Code Review

This pull request introduces a significant and well-designed integration with Temporal to support deterministic execution of AI agents in workflows. The core of the change is the new runtime module, which correctly abstracts non-deterministic system calls like getting the time and generating UUIDs. The integration helpers in google.adk.integrations.temporal, such as TemporalModel and activity_as_tool, are powerful additions that make it much easier to run ADK agents within Temporal. The accompanying integration test is comprehensive and covers both single and multi-agent scenarios effectively.

My review includes a critical fix for argument handling when wrapping activities as tools to prevent potential bugs with keyword arguments, a suggestion to adhere to Python's import conventions, and a minor cleanup in the test code to remove an unused variable. Overall, this is an excellent contribution that greatly enhances the capabilities of the ADK.

[marcusmotill]

does the function ned to have @activity.defn like above? is the the best place for options?