feat: Add Temporal integration and deterministic runtime support

[marcusmotill]

Description

This PR introduces first-class support for Temporal workflows within the ADK. It addresses the two main challenges of running AI agents in durable workflows: determinism and I/O traceability.

1. Deterministic Runtime (google.adk.runtime)

Introduced a new runtime abstraction to decouple the ADK from system time and random state.

• Problem: Default python time.time() and uuid.uuid4() are non-deterministic, which breaks Temporal's replay mechanism.
• Solution: Added google.adk.runtime module.
  • runtime.get_time(): Defaults to system time, but can be overridden (e.g., by workflow.now().timestamp()).
  • runtime.new_uuid(): Defaults to uuid.uuid4(), but can be overridden (e.g., by workflow.uuid4()).
• Updated Components: Event, InvocationContext, and InMemorySessionService now use runtime instead of direct system calls.

2. Temporal Integration Helpers (google.adk.integrations.temporal)

Added helper classes to seamlessly bridge ADK Agents with Temporal Activities.

• TemporalModel: A BaseLlm implementation that wraps a Temporal Activity. This ensures all LLM calls are recorded in the Temporal Event History, providing visibility into the agent's "thinking" process.
• activity_as_tool: A wrapper that converts any Temporal Activity into an ADK Tool. This allows agents to call Activities as tools, ensuring robust retries and timeouts managed by Temporal.
• generate_content_activity: A generic activity implementation for Vertex AI / Google AI models, ready to be registered with a Worker.

3. Multi-Agent & Serialization Support

• Verified compatibility with Agent-as-a-Tool and Handoffs in Temporal workflows.
• Added pydantic serialization support for ADK objects passed between workflows and activities.

Verification

Added a comprehensive manual integration test: tests/integration/manual_test_temporal_integration.py.

To Run:

1. Start a local Temporal server (temporal server start-dev).
2. Set GCP credentials (GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATION).
3. Run: uv run pytest tests/integration/manual_test_temporal_integration.py

Test Scenarios Covered:

• Single Agent: Verifies TemporalModel and activity_as_tool (Weather Tool).
• Multi-Agent: Verifies Coordinator delegating to AgentTool (Sub-agent) and performing transfer_to_agent (Handoff), with each agent's actions clearly visible in the Temporal Trace via aliased activities (coordinator_think, tool_agent_think).

[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.