Skip to content
Merged
2 changes: 1 addition & 1 deletion docs/develop/go/integrations/google-adk.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -56,7 +56,7 @@ go get go.temporal.io/googleadk@latest
import "go.temporal.io/googleadk"
```

The source and releases are maintained in
The module is versioned separately from the Temporal Go SDK. Its source and releases are maintained in
[`temporalio/ai-integrations`](https://github.com/temporalio/ai-integrations/tree/main/go/googleadk).

## Run an agent with Durable Execution
Expand Down
73 changes: 46 additions & 27 deletions docs/develop/java/integrations/spring-ai.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -8,60 +8,67 @@ tags:
- Spring AI
- Integrations
- AI Frameworks
description: Build durable AI agents in Java with the Temporal Spring AI integration.
description: Run Spring AI agents on Temporal with durable model calls, Activity tools, and replay-safe orchestration using Spring Boot.
---

import { ReleaseNoteHeader } from '@site/src/components';

[Spring AI](https://docs.spring.io/spring-ai/reference/) is an agent framework for Java applications — chat clients, tool calling, vector stores, embeddings, and MCP servers, all wired through Spring Boot.

The [Temporal Spring AI integration](https://central.sonatype.com/artifact/io.temporal/temporal-spring-ai) makes Spring AI agents durable: model calls run through Temporal Activities recorded in Event history, and tools are dispatched per their type so each kind lands in the right place in Workflow execution — Activity stubs and Nexus stubs as durable operations, `@SideEffectTool` classes wrapped in `Workflow.sideEffect`, and plain tools running directly in Workflow code. Agents retry on failure and replay deterministically without changing how you write Spring AI code.
The [Temporal Spring AI integration](https://central.sonatype.com/artifact/io.temporal/spring-ai) makes Spring AI agents durable: model calls run through Temporal Activities recorded in Event history, and tools are dispatched per their type so each kind lands in the right place in Workflow execution — Activity stubs and Nexus stubs as durable operations, `@SideEffectTool` classes wrapped in `Workflow.sideEffect`, and plain tools running directly in Workflow code. Agents retry on failure and replay deterministically without changing how you write Spring AI code.

The integration is built on the Temporal Java SDK's [Plugin system](/develop/plugins-guide) and is distributed as the `io.temporal:temporal-spring-ai` module alongside the existing [Spring Boot integration](/develop/java/integrations/spring-boot-integration).
The integration is built on the Temporal Java SDK's [Plugin system](/develop/plugins-guide) and is distributed as the standalone `io.temporal:spring-ai` module alongside the existing [Spring Boot integration](/develop/java/integrations/spring-boot-integration).

<ReleaseNoteHeader type="publicPreview" />

## Prerequisites

The integration requires all of the following on your application's classpath. The plugin won't auto-configure if any of these are missing or below the listed minimum:
Your application needs a Java runtime, with Spring Boot, Spring AI, and the Temporal Java SDK on its classpath. Refer to the [integration's compatibility requirements](https://github.com/temporalio/ai-integrations/tree/main/java/spring-ai#requirements-and-installation) for supported versions.

| Dependency | Minimum version |
| ----------------- | --------------- |
| Java | 17 |
| Spring Boot | 3.x |
| Spring AI | 1.1.0 |
| Temporal Java SDK | 1.35.0 |

You also need the [`temporal-spring-boot-starter`](/develop/java/integrations/spring-boot-integration) and a Spring AI model starter (for example, `spring-ai-starter-model-openai`) — `temporal-spring-ai` does not pull in a model provider on its own.
You also need the [`temporal-spring-boot-starter`](/develop/java/integrations/spring-boot-integration) and a Spring AI model starter (for example, `spring-ai-starter-model-openai`). The integration does not pull in a model provider on its own.

## Add the dependency

Add `temporal-spring-ai` alongside `temporal-spring-boot-starter` and a Spring AI model starter (for example, `spring-ai-starter-model-openai`).
Add `io.temporal:spring-ai` alongside `temporal-spring-boot-starter` and a Spring AI model starter (for example, `spring-ai-starter-model-openai`). The Spring AI integration is versioned separately from the Temporal Java SDK.

Choose a compatible [release from Maven Central](https://central.sonatype.com/artifact/io.temporal/spring-ai).
Set `temporal-spring-ai.version` in Maven or `temporalSpringAiVersion` in Gradle to that version.

**[Apache Maven](https://maven.apache.org/):**

```xml
<dependency>
<groupId>io.temporal</groupId>
<artifactId>temporal-spring-ai</artifactId>
<version>${temporal-sdk.version}</version>
<artifactId>spring-ai</artifactId>
<version>${temporal-spring-ai.version}</version>
</dependency>
```

**[Gradle Groovy DSL](https://gradle.org/):**

```groovy
implementation "io.temporal:temporal-spring-ai:${temporalSdkVersion}"
implementation "io.temporal:spring-ai:${temporalSpringAiVersion}"
```

When `temporal-spring-ai` is on the classpath, the `SpringAiPlugin` auto-registers `ChatModelActivity` with all Temporal Workers created by the Spring Boot integration. Optional Activities are auto-configured when their dependencies are present:
When `io.temporal:spring-ai` is on the classpath, the `SpringAiPlugin` auto-registers `ChatModelActivity` with all Temporal Workers created by the Spring Boot integration. Optional Activities are auto-configured when their dependencies are present:

| Feature | Dependency | Registered Activity |
| ------------ | --------------- | ------------------------ |
| Vector store | `spring-ai-rag` | `VectorStoreActivity` |
| Embeddings | `spring-ai-rag` | `EmbeddingModelActivity` |
| MCP | `spring-ai-mcp` | `McpClientActivity` |

### Migrate from the previous package

When moving from `io.temporal:temporal-spring-ai`, follow the
[migration guide](https://github.com/temporalio/ai-integrations/tree/main/java/spring-ai#moving-from-spring-ai-1)
to align your application's Spring AI and Spring Boot BOMs.

Pass option builders to `ChatClient`, such as `.defaultOptions(OpenAiChatOptions.builder().reasoningEffort("high"))`, or call `.mutate()` on existing options.

Complete existing Workflow Executions before switching, or keep them on separate Worker deployments. Workflow histories
created with `io.temporal:temporal-spring-ai` are incompatible with `io.temporal:spring-ai`.

## Call a chat model from a Workflow

Use `ActivityChatModel` as a Spring AI `ChatModel` inside a Workflow. Every call goes through a Temporal Activity, so model responses are durable and retried per your Activity options.
Expand Down Expand Up @@ -104,12 +111,16 @@ public ChatWorkflowImpl(String systemPrompt) {
// - Activity stubs (weatherTool) become durable AI tools
// - plain workflow tool classes (stringTools) execute directly in workflow
// - @SideEffectTool classes (timestampTools) are wrapped in sideEffect()
// - PromptChatMemoryAdvisor maintains conversation history
// - MessageChatMemoryAdvisor maintains conversation history
this.chatClient =
TemporalChatClient.builder(activityChatModel)
.defaultSystem(systemPrompt)
.defaultTools(weatherTool, stringTools, timestampTools)
.defaultAdvisors(PromptChatMemoryAdvisor.builder(chatMemory).build())
.defaultAdvisors(
advisors ->
advisors
.advisors(MessageChatMemoryAdvisor.builder(chatMemory).build())
.param(ChatMemory.CONVERSATION_ID, Workflow.getInfo().getWorkflowId()))
.build();
}

Expand Down Expand Up @@ -333,19 +344,27 @@ Keys that neither match a registered `ChatModel` bean nor equal `"default"` caus

`ActivityMcpClient.create()` and `create(ActivityOptions)` work the same way for MCP tool calls, with a 30-second default timeout.

### Disable provider retries

Disable the provider SDK's retries so each Temporal Activity attempt makes one provider request. For the Spring Boot OpenAI chat model, set:

```properties
spring.ai.openai.chat.max-retries=0
```

For manually constructed OpenAI or Anthropic models, set `.maxRetries(0)` on the provider options before building the Worker's model. Setting retries on a Workflow prompt does not reconfigure an existing provider client.

OpenAI HTTP failures retain their native exception types. The integration classifies retryable failures and honors provider retry delays; see the [provider retry reference](https://github.com/temporalio/ai-integrations/tree/main/java/spring-ai#provider-retries) for details.

## Provider-specific chat options

Provider-specific `ChatOptions` subclasses — for example, `AnthropicChatOptions` to enable extended thinking, or `OpenAiChatOptions` to set `reasoning_effort` — pass through the Activity boundary unchanged. Attach them via `ChatClient.defaultOptions(...)` and the plugin re-applies them on the Activity side before calling the underlying model:

<!--SNIPSTART samples-java-spring-ai-provider-options-->
[springai/multimodel/src/main/java/io/temporal/samples/springai/multimodel/MultiModelWorkflowImpl.java](https://github.com/temporalio/samples-java/blob/main/springai/multimodel/src/main/java/io/temporal/samples/springai/multimodel/MultiModelWorkflowImpl.java)
```java
AnthropicChatOptions thinkingOptions =
AnthropicChatOptions.builder()
.thinking(AnthropicApi.ThinkingType.ENABLED, 1024)
.temperature(1.0)
.maxTokens(4096)
.build();
AnthropicChatOptions.Builder thinkingOptions =
AnthropicChatOptions.builder().thinkingEnabled(1024).temperature(1.0).maxTokens(4096);
chatClients.put(
"think",
TemporalChatClient.builder(anthropicModel)
Expand All @@ -358,7 +377,7 @@ chatClients.put(
```
<!--SNIPEND-->

The pass-through relies on the `ChatOptions` subclass overriding `copy()` to return its own type — every provider class shipped with Spring AI does.
Spring AI options are immutable. Pass their builder to `defaultOptions(...)`, or call `.mutate()` on an existing options object. The integration preserves provider-specific fields across the Activity boundary.

## Media in messages

Expand Down Expand Up @@ -387,6 +406,6 @@ new McpPlugin();

## Resources

- [`temporal-spring-ai` README](https://github.com/temporalio/sdk-java/blob/main/contrib/temporal-spring-ai/README.md) — full reference for the module
- [Temporal Spring AI README](https://github.com/temporalio/ai-integrations/tree/main/java/spring-ai) — full reference for the standalone module
- [Spring Boot integration](/develop/java/integrations/spring-boot-integration) — required companion module
- [Plugin system](/develop/plugins-guide) — how integrations are registered with Workers and Clients
4 changes: 2 additions & 2 deletions docs/develop/plugins-guide.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -38,8 +38,8 @@ If you prefer to learn by getting hands-on with code, check out some existing pl

- Temporal maintains an
[OpenAI Agents SDK](https://github.com/temporalio/ai-integrations/tree/main/python/openai_agents) plugin for Python
- Temporal's Python SDK ships with a
[LangGraph](https://github.com/temporalio/sdk-python/tree/main/temporalio/contrib/langgraph) plugin
- Temporal maintains a
[LangGraph](https://github.com/temporalio/ai-integrations/tree/main/python/langgraph) plugin for Python
- [Temporal client and Worker plugin for Pydantic AI](https://github.com/pydantic/pydantic-ai/blob/d9b4b2540183a4426669b2824c87cdfc36144780/pydantic_ai_slim/pydantic_ai/durable_exec/temporal/__init__.py#L142)
- Temporal's TypeScript SDK ships with an
[OpenTelemetry Plugin](https://github.com/temporalio/sdk-typescript/blob/main/contrib/interceptors-opentelemetry/src/plugin.ts)
Expand Down
15 changes: 9 additions & 6 deletions docs/develop/python/integrations/deepagents.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,6 @@ samples for the complete code.

## Prerequisites

- Python 3.11 or newer.
- This guide assumes you are already familiar with Deep Agents. If you aren't, refer to the
[Deep Agents documentation](https://github.com/langchain-ai/deepagents) for more details.
- If you are new to Temporal, we recommend reading [Understanding Temporal](/evaluate/understanding-temporal) or taking
Expand All @@ -42,19 +41,23 @@ samples for the complete code.

## Install the plugin

Install the Temporal Python SDK with Deep Agents support:
Install the standalone `temporalio-deepagents` package:

```bash
uv add "temporalio[deepagents]>=1.32.0"
uv add temporalio-deepagents
```

or with pip:

```bash
pip install "temporalio[deepagents]>=1.32.0"
pip install temporalio-deepagents
```

Requires Python 3.11 or newer, the same floor that `deepagents` sets.
The package installs the Temporal Python SDK and Deep Agents dependencies. Refer to the
[package requirements](https://github.com/temporalio/ai-integrations/blob/main/python/deepagents/pyproject.toml)
for supported Python and dependency versions.

Import `DeepAgentsPlugin`, `TemporalBackend`, and other integration helpers from `temporalio.deepagents`.

## Hello world

Expand Down Expand Up @@ -525,7 +528,7 @@ class StreamingWorkflow:
## Compose with an observability plugin

This plugin carries no tracing context of its own. For observability, compose it with an observability plugin such as
[`temporalio.contrib.langsmith`](https://github.com/temporalio/sdk-python/tree/main/temporalio/contrib/langsmith) or
[`temporalio.langsmith`](/develop/python/integrations/langsmith) or
`temporalio.contrib.opentelemetry`. Registration order of the two plugins does not matter; the observability plugin
captures the LLM calls that `DeepAgentsPlugin` runs as Activities. The Workflow itself is an ordinary Deep Agent — the tracing
comes entirely from composing the plugins on the Client.
Expand Down
19 changes: 16 additions & 3 deletions docs/develop/python/integrations/google-adk.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -40,18 +40,25 @@ import { ReleaseNoteHeader } from '@site/src/components';

## Install

Make sure you have the Temporal Python SDK (requires version 1.28.0 or later). Then install the `google-adk`:
Install the standalone `temporalio-google-adk` package:

```bash
uv add "temporalio[google-adk]>=1.28.0"
uv add temporalio-google-adk
```

If you use pip:

```bash
pip install "temporalio[google-adk]>=1.28.0"
pip install temporalio-google-adk
```

The package installs the Temporal Python SDK and Google ADK dependencies. Refer to the
[package requirements](https://github.com/temporalio/ai-integrations/blob/main/python/google_adk/pyproject.toml)
for supported Python and dependency versions.

Import `GoogleAdkPlugin` and `TemporalModel` from `temporalio.google_adk`. Import Workflow helpers such as `activity_as_tool`
from `temporalio.google_adk.workflow`.

## Define an agent in a Workflow

Write your agent the way you normally would with the ADK. The one Temporal-specific piece is `TemporalModel`, which you
Expand Down Expand Up @@ -266,6 +273,12 @@ which agent ran and when.

## Use MCP tool servers

Install the package's `mcp` extra:

```bash
uv add "temporalio-google-adk[mcp]"
```

To give an agent tools from an [MCP](https://modelcontextprotocol.io/) server, use `TemporalMcpToolSet`. It runs the
server's list-tools and call-tool operations as Activities because connecting to an MCP server is external I/O. You define a factory function for the toolset and register it with the plugin
through a `TemporalMcpToolSetProvider`.
Expand Down
21 changes: 16 additions & 5 deletions docs/develop/python/integrations/google-genai.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -46,19 +46,24 @@ samples for the complete code.

## Install the plugin

Install the Temporal Python SDK with Google GenAI support (requires `temporalio` 1.31.0 or later):
Install the standalone `temporalio-google-genai` package:

```bash
uv add "temporalio[google-genai]>=1.31.0"
uv add temporalio-google-genai
```

If you use pip:

```bash
pip install "temporalio[google-genai]>=1.31.0"
pip install temporalio-google-genai
```

The [MCP](#use-mcp-tool-servers) path also needs the `mcp` package, which the extra does not install.
The package installs the Temporal Python SDK and Google GenAI dependencies. Refer to the
[package requirements](https://github.com/temporalio/ai-integrations/blob/main/python/google_genai/pyproject.toml)
for supported Python and dependency versions.

Import `GoogleGenAIPlugin`, `TemporalAsyncClient`, and `TemporalMcpClientSession` from `temporalio.google_genai`.
For [MCP tool servers](#use-mcp-tool-servers), install the package's `mcp` extra.

## Call a model from a Workflow

Expand Down Expand Up @@ -302,6 +307,12 @@ class StructuredOutputWorkflow:

## Use MCP tool servers

Install the package's `mcp` extra:

```bash
uv add "temporalio-google-genai[mcp]"
```

To give a model tools from an [MCP](https://modelcontextprotocol.io/) server, register the server on the Worker and
reference it by name in the Workflow. Connecting to an MCP server is external I/O, so the plugin holds the connection on
the Worker and runs `list_tools` and `call_tool` as Activities against it.
Expand Down Expand Up @@ -570,7 +581,7 @@ all of a client's calls with `activity_config`:
from datetime import timedelta

from temporalio.common import RetryPolicy
from temporalio.contrib.google_genai import TemporalAsyncClient
from temporalio.google_genai import TemporalAsyncClient
from temporalio.workflow import ActivityConfig

client = TemporalAsyncClient(
Expand Down
3 changes: 3 additions & 0 deletions docs/develop/python/integrations/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -17,4 +17,7 @@ Most of these integrations are built on the Temporal Python SDK's [Plugin system
can also use to build your own integrations. A few, such as OpenRouter, are sample patterns that need nothing inside
Workflow code.

Temporal-maintained AI integrations are distributed as [standalone packages](https://github.com/temporalio/ai-integrations),
such as `temporalio-strands-agents`. Each integration guide lists its package and import paths.

<IntegrationsGrid defaultSdks={["Python"]} />
Loading
Loading