Add Spring AI samples

.github/CODEOWNERS

@@ -1,3 +1,10 @@
 # Primary owners
 
-* @tsurdilo @temporalio/sdk @antmendoza
+* @tsurdilo @temporalio/sdk @antmendoza
+
+# Below are owners for samples for modules
+# that are owned by teams other than the SDK team.
+# For each one, we add the owning team, as well as
+# @temporalio/sdk, so the SDK team can continue to
+# manage repo-wide concerns
+/springai/ @temporalio/ai-sdk @temporalio/sdk

.gitignore

@@ -5,14 +5,8 @@ target
 .DS_Store
 .idea
 .gradle
-/build
-/core/build
-/springboot/build
-/springboot-basic/build
-/out
-/core/out
-/springboot/out
-/springboot-basic/out
+**/build/
+**/out/
 .classpath
 .project
 .settings/

README.md

@@ -3,10 +3,11 @@
 This repository contains samples that demonstrate various capabilities of 
 Temporal using the [Java SDK](https://github.com/temporalio/sdk-java).
 
-It contains two modules:
+It contains the following modules:
 * [Core](/core): showcases many different SDK features.
 * [SpringBoot](/springboot): showcases SpringBoot autoconfig integration.
 * [SpringBoot Basic](/springboot-basic): Minimal sample showing SpringBoot autoconfig integration without any extra external dependencies.
+* [Spring AI](/springai): demonstrates the Temporal Spring AI integration — durable AI agents with chat models, tools, MCP servers, vector stores, and embeddings.
 
 ## Learn more about Temporal and Java SDK
 
@@ -16,9 +17,7 @@ It contains two modules:
 
 ## Requirements
 
-- Java 1.8+ for build and runtime of core samples
-- Java 1.8+ for build and runtime of SpringBoot samples when using SpringBoot 2
-- Java 1.17+ for build and runtime of Spring Boot samples when using SpringBoot 3
+- Java 17+
 - Local Temporal Server, easiest to get started would be using [Temporal CLI](https://github.com/temporalio/cli).
 For more options see docs [here](https://docs.temporal.io/kb/all-the-ways-to-run-a-cluster).
 
@@ -213,3 +212,22 @@ To run any of the SpringBoot samples in your Temporal Cloud namespace:
        ./gradlew bootRun --args='--spring.profiles.active=tc'
 
 3. Follow the previous section from step 2
+
+### Running Spring AI Samples
+
+The Spring AI samples demonstrate the [Temporal Spring AI integration](https://github.com/temporalio/sdk-java/tree/master/temporal-spring-ai), which makes Spring AI agents durable on Temporal — model calls run as Temporal Activities recorded in Workflow history, and tools are dispatched per their type so they fit Workflow execution.
+
+Each sample is its own Spring Boot application with an interactive CLI. Run from the main repo dir:
+
+       ./gradlew :springai:basic:bootRun
+       ./gradlew :springai:mcp:bootRun
+       ./gradlew :springai:multimodel:bootRun
+       ./gradlew :springai:rag:bootRun
+
+All samples need an `OPENAI_API_KEY` environment variable; some need additional setup (see each sample's source for details).
+
+More info on each sample:
+- [**Basic**](/springai/basic): Chat workflow with three tool flavors — activity-backed (`WeatherActivity`), plain workflow tools (`StringTools`), and `@SideEffectTool` (`TimestampTools`) — plus a `PromptChatMemoryAdvisor` for conversation history.
+- [**MCP**](/springai/mcp): Connects to a Model Context Protocol server and exposes its tools to the AI through Temporal activities. Defaults to the filesystem MCP server.
+- [**Multi-Model**](/springai/multimodel): Two providers in one workflow (OpenAI and Anthropic), per-model `ActivityOptions` overrides via a Spring bean, plus a route that exercises Anthropic's extended-thinking mode through provider-specific `ChatOptions` pass-through. Requires `ANTHROPIC_API_KEY` in addition to `OPENAI_API_KEY`.
+- [**RAG**](/springai/rag): Vector store + embeddings for retrieval-augmented generation. Add documents, then ask questions; the workflow searches the vector store and grounds the answer in the retrieved context.

gradle/springai.gradle

@@ -0,0 +1,61 @@
+// Shared configuration for all Spring AI sample modules.
+// Applied via: apply from: "$rootDir/gradle/springai.gradle"
+//
+// Note on Spring Boot version skew: the root build.gradle pins the
+// org.springframework.boot Gradle plugin at $springBootPluginVersion (currently
+// 2.7.13) for the legacy springboot/ samples. Spring AI 1.1.0 requires Spring
+// Boot 3.5.x, which we get by importing the spring-boot-dependencies BOM at
+// $springBootVersionForSpringAi below. The plugin and the BOM are independent —
+// the plugin contributes bootJar/bootRun task wiring, the BOM dictates
+// dependency versions — so this works in practice even though the two version
+// numbers don't match. Long-term fix is to either move the plugin declaration
+// out of the root plugins block (so each module applies its own version) or
+// migrate the legacy springboot/ samples to Spring Boot 3.x; until one of those
+// happens, this skew is intentional.
+
+apply plugin: 'org.springframework.boot'
+apply plugin: 'io.spring.dependency-management'
+
+ext {
+    springBootVersionForSpringAi = '3.5.3'
+    springAiVersion = '1.1.0'
+}
+
+java {
+    sourceCompatibility = JavaVersion.VERSION_17
+    targetCompatibility = JavaVersion.VERSION_17
+}
+
+dependencyManagement {
+    imports {
+        mavenBom "org.springframework.boot:spring-boot-dependencies:$springBootVersionForSpringAi"
+        mavenBom "org.springframework.ai:spring-ai-bom:$springAiVersion"
+    }
+}
+
+dependencies {
+    implementation "io.temporal:temporal-spring-boot-starter:$javaSDKVersion"
+    implementation "io.temporal:temporal-spring-ai:$javaSDKVersion"
+    // temporal-spring-ai declares temporal-sdk as compileOnly, so bring it in explicitly.
+    implementation "io.temporal:temporal-sdk:$javaSDKVersion"
+
+    // Spring Boot
+    implementation 'org.springframework.boot:spring-boot-starter'
+
+    dependencies {
+        errorproneJavac('com.google.errorprone:javac:9+181-r4173-1')
+        errorprone('com.google.errorprone:error_prone_core:2.28.0')
+    }
+}
+
+bootJar {
+    enabled = false
+}
+
+jar {
+    enabled = true
+}
+
+bootRun {
+    standardInput = System.in
+}

settings.gradle

@@ -1,4 +1,9 @@
 rootProject.name = 'temporal-java-samples'
 include 'core'
+include 'springai:basic'
+include 'springai:mcp'
+include 'springai:multimodel'
+include 'springai:rag'
 include 'springboot'
 include 'springboot-basic'
+

springai/basic/build.gradle

@@ -0,0 +1,5 @@
+apply from: "$rootDir/gradle/springai.gradle"
+
+dependencies {
+    implementation 'org.springframework.ai:spring-ai-starter-model-openai'
+}

springai/basic/src/main/java/io/temporal/samples/springai/chat/ChatExampleApplication.java

@@ -0,0 +1,87 @@
+package io.temporal.samples.springai.chat;
+
+import io.temporal.client.WorkflowClient;
+import io.temporal.client.WorkflowOptions;
+import java.util.Scanner;
+import java.util.UUID;
+import org.springframework.boot.SpringApplication;
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+import org.springframework.boot.context.event.ApplicationReadyEvent;
+import org.springframework.context.event.EventListener;
+import org.springframework.stereotype.Component;
+
+/**
+ * Example application demonstrating the Spring AI Temporal plugin.
+ *
+ * <p>Starts an interactive chat workflow where each AI call is a durable Temporal activity with
+ * automatic retries and timeout handling.
+ */
+@SpringBootApplication
+public class ChatExampleApplication {
+
+  public static void main(String[] args) {
+    SpringApplication.run(ChatExampleApplication.class, args);
+  }
+}
+
+@Component
+class ChatRunner {
+
+  private final WorkflowClient workflowClient;
+
+  ChatRunner(WorkflowClient workflowClient) {
+    this.workflowClient = workflowClient;
+  }
+
+  @EventListener(ApplicationReadyEvent.class)
+  public void run() {
+    String workflowId = "chat-" + UUID.randomUUID().toString().substring(0, 8);
+
+    System.out.println("\n===========================================");
+    System.out.println("  Spring AI + Temporal Chat Demo");
+    System.out.println("===========================================");
+    System.out.println("Workflow ID: " + workflowId);
+    System.out.println("Type messages, or 'quit' to exit.\n");
+
+    // Start the chat workflow
+    ChatWorkflow workflow =
+        workflowClient.newWorkflowStub(
+            ChatWorkflow.class,
+            WorkflowOptions.newBuilder()
+                .setWorkflowId(workflowId)
+                .setTaskQueue("spring-ai-example")
+                .build());
+
+    WorkflowClient.start(workflow::run, "You are a helpful assistant. Be concise.");
+
+    // Get stub for the running workflow
+    ChatWorkflow chat = workflowClient.newWorkflowStub(ChatWorkflow.class, workflowId);
+
+    // Interactive loop
+    try (Scanner scanner = new Scanner(System.in, java.nio.charset.StandardCharsets.UTF_8)) {
+      while (true) {
+        System.out.print("You: ");
+        String input = scanner.nextLine().trim();
+
+        if (input.equalsIgnoreCase("quit") || input.equalsIgnoreCase("exit")) {
+          chat.end();
+          break;
+        }
+
+        if (input.isEmpty()) {
+          continue;
+        }
+
+        try {
+          String response = chat.chat(input);
+          System.out.println("Assistant: " + response + "\n");
+        } catch (Exception e) {
+          System.err.println("Error: " + e.getMessage() + "\n");
+        }
+      }
+    }
+
+    System.out.println("Goodbye!");
+    System.exit(0);
+  }
+}

springai/basic/src/main/java/io/temporal/samples/springai/chat/ChatWorkflow.java

@@ -0,0 +1,38 @@
+package io.temporal.samples.springai.chat;
+
+import io.temporal.workflow.SignalMethod;
+import io.temporal.workflow.UpdateMethod;
+import io.temporal.workflow.WorkflowInterface;
+import io.temporal.workflow.WorkflowMethod;
+
+/**
+ * A chat workflow that maintains a conversation with an AI model.
+ *
+ * <p>The workflow runs until explicitly ended via the {@link #end()} signal. Messages can be sent
+ * via the {@link #chat(String)} update method, which returns the AI's response synchronously.
+ */
+@WorkflowInterface
+public interface ChatWorkflow {
+
+  /**
+   * Starts the chat workflow and waits until ended.
+   *
+   * @param systemPrompt the system prompt that defines the AI's behavior
+   * @return a summary when the chat ends
+   */
+  @WorkflowMethod
+  String run(String systemPrompt);
+
+  /**
+   * Sends a message to the AI and returns its response.
+   *
+   * @param message the user's message
+   * @return the AI's response
+   */
+  @UpdateMethod
+  String chat(String message);
+
+  /** Ends the chat session. */
+  @SignalMethod
+  void end();
+}

springai/basic/src/main/java/io/temporal/samples/springai/chat/ChatWorkflowImpl.java

@@ -0,0 +1,111 @@
+package io.temporal.samples.springai.chat;
+
+import io.temporal.activity.ActivityOptions;
+import io.temporal.common.RetryOptions;
+import io.temporal.springai.chat.TemporalChatClient;
+import io.temporal.springai.model.ActivityChatModel;
+import io.temporal.workflow.Workflow;
+import io.temporal.workflow.WorkflowInit;
+import java.time.Duration;
+import org.springframework.ai.chat.client.ChatClient;
+import org.springframework.ai.chat.client.advisor.PromptChatMemoryAdvisor;
+import org.springframework.ai.chat.memory.ChatMemory;
+import org.springframework.ai.chat.memory.InMemoryChatMemoryRepository;
+import org.springframework.ai.chat.memory.MessageWindowChatMemory;
+
+/**
+ * Implementation of the chat workflow using Spring AI's ChatClient with Temporal tools.
+ *
+ * <p>This demonstrates how to use the Spring AI plugin within a Temporal workflow:
+ *
+ * <ol>
+ *   <li>Build an {@link ActivityChatModel} via its factory to get a standard Spring AI ChatModel
+ *       backed by a durable Temporal activity
+ *   <li>Create activity stubs for tools (e.g., {@link WeatherActivity})
+ *   <li>Create deterministic tools (e.g., {@link StringTools})
+ *   <li>Create side-effect tools (e.g., {@link TimestampTools})
+ *   <li>Use {@link TemporalChatClient} to build a tool-aware chat client
+ * </ol>
+ *
+ * <p>The AI model can call:
+ *
+ * <ul>
+ *   <li>{@code getWeather(city)} - Executes as a durable Temporal activity
+ *   <li>{@code getForecast(city, days)} - Executes as a durable Temporal activity
+ *   <li>{@code reverse(text)}, {@code countWords(text)}, etc. - Execute directly in workflow (plain
+ *       workflow tool)
+ *   <li>{@code getCurrentDateTime()}, {@code generateUuid()}, etc. - Wrapped in sideEffect
+ *       (@SideEffectTool)
+ * </ul>
+ */
+public class ChatWorkflowImpl implements ChatWorkflow {
+
+  private final ChatClient chatClient;
+  private boolean ended = false;
+  private int messageCount = 0;
+
+  // @@@SNIPSTART samples-java-spring-ai-chat-workflow-init
+  @WorkflowInit
+  public ChatWorkflowImpl(String systemPrompt) {
+    // Build an activity-backed chat model. The factory creates the activity stub
+    // internally and registers per-call Summaries on the Temporal UI.
+    ActivityChatModel activityChatModel = ActivityChatModel.forDefault();
+
+    // Create an activity stub for weather tools - these execute as durable activities
+    WeatherActivity weatherTool =
+        Workflow.newActivityStub(
+            WeatherActivity.class,
+            ActivityOptions.newBuilder()
+                .setStartToCloseTimeout(Duration.ofSeconds(30))
+                .setRetryOptions(RetryOptions.newBuilder().setMaximumAttempts(3).build())
+                .build());
+
+    // Create deterministic tools - these execute directly in the workflow
+    StringTools stringTools = new StringTools();
+
+    // Create side-effect tools - these are wrapped in Workflow.sideEffect()
+    // The result is recorded in history, making replay deterministic
+    TimestampTools timestampTools = new TimestampTools();
+
+    // Create chat memory - uses in-memory storage that gets rebuilt on replay
+    ChatMemory chatMemory =
+        MessageWindowChatMemory.builder()
+            .chatMemoryRepository(new InMemoryChatMemoryRepository())
+            .maxMessages(20)
+            .build();
+
+    // Build a TemporalChatClient with tools and memory
+    // - 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
+    this.chatClient =
+        TemporalChatClient.builder(activityChatModel)
+            .defaultSystem(systemPrompt)
+            .defaultTools(weatherTool, stringTools, timestampTools)
+            .defaultAdvisors(PromptChatMemoryAdvisor.builder(chatMemory).build())
+            .build();
+  }
+
+  // @@@SNIPEND
+
+  @Override
+  public String run(String systemPrompt) {
+    // systemPrompt is unused here on purpose — @WorkflowInit requires the constructor
+    // and the @WorkflowMethod to share a parameter list, and the constructor above
+    // already consumed it to build the chat client.
+    Workflow.await(() -> ended);
+    return "Chat ended after " + messageCount + " messages.";
+  }
+
+  @Override
+  public String chat(String message) {
+    messageCount++;
+    return chatClient.prompt().user(message).call().content();
+  }
+
+  @Override
+  public void end() {
+    ended = true;
+  }
+}