temporalio · donald-pinckney · Apr 17, 2026 · Apr 6, 2026 · Apr 6, 2026 · Apr 6, 2026
@@ -6,6 +6,7 @@ include 'temporal-testing'
 include 'temporal-test-server'
 include 'temporal-opentracing'
 include 'temporal-kotlin'
+include 'temporal-spring-ai'
 include 'temporal-spring-boot-autoconfigure'
 include 'temporal-spring-boot-starter'
 include 'temporal-remote-data-encoder'

@@ -12,6 +12,7 @@ dependencies {
         api project(':temporal-sdk')
         api project(':temporal-serviceclient')
         api project(':temporal-shaded')
+        api project(':temporal-spring-ai')
         api project(':temporal-spring-boot-autoconfigure')
         api project(':temporal-spring-boot-starter')
         api project(':temporal-test-server')

@@ -0,0 +1,111 @@
+# temporal-spring-ai
+
+Integrates [Spring AI](https://docs.spring.io/spring-ai/reference/) with [Temporal](https://temporal.io/) workflows, making AI model calls, tool execution, vector store operations, embeddings, and MCP tool calls durable Temporal primitives.
+
+## Compatibility
+
+| Dependency        | Minimum Version |
+|-------------------|-----------------|
+| Java              | 17              |
+| Spring Boot       | 3.x             |
+| Spring AI         | 1.1.0           |
+| Temporal Java SDK | 1.33.0          |
+
+## Quick Start
+
+Add the dependency (Maven):
+
+```xml
+<dependency>
+    <groupId>io.temporal</groupId>
+    <artifactId>temporal-spring-ai</artifactId>
+    <version>${temporal-sdk.version}</version>
+</dependency>
+```
+
+You also need `temporal-spring-boot-starter` and a Spring AI model starter (e.g. `spring-ai-starter-model-openai`).
+
+The plugin auto-registers `ChatModelActivity` with all Temporal workers. In your workflow:
+
+```java
+@WorkflowInit
+public MyWorkflowImpl(String goal) {
+    ActivityChatModel chatModel = ActivityChatModel.forDefault();
+
+    WeatherActivity weather = Workflow.newActivityStub(WeatherActivity.class, opts);
+
+    this.chatClient = TemporalChatClient.builder(chatModel)
+            .defaultSystem("You are a helpful assistant.")
+            .defaultTools(weather, new MyTools())
+            .build();
+}
+
+@Override
+public String run(String goal) {
+    return chatClient.prompt().user(goal).call().content();
+}
+```
+
+## Tool Types
+
+Tools passed to `defaultTools()` are handled based on their type:
+
+### Activity stubs
+
+Interfaces annotated with both `@ActivityInterface` and `@Tool` methods. Auto-detected and executed as durable Temporal activities with retries and timeouts.
+
+```java
+@ActivityInterface
+public interface WeatherActivity {
+    @Tool(description = "Get weather for a city") @ActivityMethod
+    String getWeather(String city);
+}
+```
+
+### `@SideEffectTool`
+
+Classes annotated with `@SideEffectTool`. Each `@Tool` method is wrapped in `Workflow.sideEffect()` — the result is recorded in history on first execution and replayed from history on subsequent replays. Use for cheap non-deterministic operations (timestamps, UUIDs).
+
+```java
+@SideEffectTool
+public class TimestampTools {
+    @Tool(description = "Get current time")
+    public String now() { return Instant.now().toString(); }
+}
+```
+
+### Plain tools
+
+Any class with `@Tool` methods that isn't a stub or `@SideEffectTool`. Executes directly in the workflow thread. The user is responsible for determinism — call activities, `Workflow.sideEffect()`, child workflows, etc. as needed.
+
+```java
+public class MyTools {
+    @Tool(description = "Process data")
+    public String process(String input) {
+        SomeActivity act = Workflow.newActivityStub(SomeActivity.class, opts);
+        return act.doWork(input);
+    }
+}
+```
+
+### Nexus service stubs
+
+Auto-detected and executed as Nexus operations, similar to activity stubs.
+
+## Optional Integrations
+
+Auto-configured when their dependencies are on the classpath:
+
+| Feature      | Dependency      | What it registers        |
+|--------------|-----------------|--------------------------|
+| Vector Store | `spring-ai-rag` | `VectorStoreActivity`    |
+| Embeddings   | `spring-ai-rag` | `EmbeddingModelActivity` |
+| MCP          | `spring-ai-mcp` | `McpClientActivity`      |
+
+These can also be set up programmatically without auto-configuration:
+
+```java
+new VectorStorePlugin(vectorStore)
+new EmbeddingModelPlugin(embeddingModel)
+new McpPlugin()
+```
@@ -0,0 +1,63 @@
+description = '''Temporal Java SDK Spring AI Plugin'''
+
+ext {
+    springAiVersion = '1.1.0'
+    // Spring AI requires Spring Boot 3.x / Java 17+
+    springBootVersionForSpringAi = "$springBoot3Version"
+}
+
+// Spring AI requires Java 17+, override the default Java 8 target from java.gradle.
+// When edgeDepsTest is set, use 21 to match other modules.
+ext {
+    springAiReleaseInt = project.hasProperty("edgeDepsTest") ? 21 : 17
+}
+
+compileJava {
+    options.compilerArgs.removeAll(['--release', '8'])
+    options.release = springAiReleaseInt
+}
+
+compileTestJava {
+    options.compilerArgs.removeAll(['--release', '8'])
+    options.release = springAiReleaseInt
+}
+
+dependencies {
+    api(platform("org.springframework.boot:spring-boot-dependencies:$springBootVersionForSpringAi"))
+    api(platform("org.springframework.ai:spring-ai-bom:$springAiVersion"))
+
+    // this module shouldn't carry temporal-sdk with it, especially for situations when users may be using a shaded artifact
+    compileOnly project(':temporal-sdk')
+    compileOnly project(':temporal-spring-boot-autoconfigure')
+
+    api 'org.springframework.boot:spring-boot-autoconfigure'
+    api 'org.springframework.ai:spring-ai-client-chat'
+
+    implementation 'org.springframework.boot:spring-boot-starter'
+
+    // Optional: Vector store support
+    compileOnly 'org.springframework.ai:spring-ai-rag'
+
+    // Optional: MCP (Model Context Protocol) support
+    compileOnly 'org.springframework.ai:spring-ai-mcp'
+
+    testImplementation project(':temporal-sdk')
+    testImplementation project(':temporal-testing')
+    testImplementation "org.mockito:mockito-core:${mockitoVersion}"
+    testImplementation 'org.springframework.boot:spring-boot-starter-test'
+    testImplementation 'org.springframework.ai:spring-ai-rag'
+
+    testRuntimeOnly group: 'ch.qos.logback', name: 'logback-classic', version: "${logbackVersion}"
+    testRuntimeOnly "org.junit.platform:junit-platform-launcher"
+}
+
+tasks.test {
+    useJUnitPlatform()
+    // This module's bytecode targets Java 17+, so it can't run on older JVMs.
+    // The unit_test_jdk8 CI job sets -PtestJavaVersion=11 to verify Java 8 bytecode
+    // works on JDK 11 — skip our tests there since the classes won't even load.
+    if (project.hasProperty("testJavaVersion")
+            && (project.property("testJavaVersion") as int) < springAiReleaseInt) {
+        enabled = false
+    }
+}
@@ -0,0 +1,25 @@
+package io.temporal.springai.activity;
+
+import io.temporal.activity.ActivityInterface;
+import io.temporal.activity.ActivityMethod;
+import io.temporal.springai.model.ChatModelTypes;
+
+/**
+ * Temporal activity interface for calling Spring AI chat models.
+ *
+ * <p>This activity wraps a Spring AI {@link org.springframework.ai.chat.model.ChatModel} and makes
+ * it callable from within Temporal workflows. The activity handles serialization of prompts and
+ * responses, enabling durable AI conversations with automatic retries and timeout handling.
+ */
+@ActivityInterface
+public interface ChatModelActivity {
+
+  /**
+   * Calls the chat model with the given input.
+   *
+   * @param input the chat model input containing messages, options, and tool definitions
+   * @return the chat model output containing generated responses and metadata
+   */
+  @ActivityMethod
+  ChatModelTypes.ChatModelActivityOutput callChatModel(ChatModelTypes.ChatModelActivityInput input);
+}