Add temporal-spring-ai module by donald-pinckney · Pull Request #2829 · temporalio/sdk-java

donald-pinckney · 2026-04-06T20:49:20Z

Summary

Adds temporal-spring-ai module that integrates Spring AI with Temporal workflows
AI model calls, vector store operations, embeddings, and MCP tool execution run as durable Temporal activities
Three-tier tool system: @DeterministicTool (pure functions), @SideEffectTool (cheap non-determinism via Workflow.sideEffect()), and activity-backed tools (durable I/O)
Auto-configuration via SpringAiPlugin that registers activities with all workers
Requires Java 17+ and Spring Boot 3.x / Spring AI 1.1.0

Known issues to address

UUID.randomUUID() used in workflow context (LocalActivityToolCallbackWrapper)
TemporalStubUtil uses fragile string matching on internal handler class names
compileOnly deps (VectorStore, EmbeddingModel, MCP) cause ClassNotFoundException at runtime when not present — need to split plugin class or change dep scope
No depth limit on recursive tool call loop in ActivityChatModel.call()
No streaming support (expected, but should throw UnsupportedOperationException)
No tests yet

Test plan

Run chat sample end-to-end with Temporal dev server
Run RAG sample with vector store
Run MCP sample with filesystem MCP server
Add unit tests for type conversion (ChatModelTypes ↔ Spring AI types)
Add replay test to verify determinism
Test with multiple chat models (multi-model sample)

🤖 Generated with Claude Code

Adds a new module that integrates Spring AI with Temporal workflows, enabling durable AI model calls, vector store operations, embeddings, and MCP tool execution as Temporal activities. Key components: - ActivityChatModel: ChatModel implementation backed by activities - TemporalChatClient: Temporal-aware ChatClient with tool detection - SpringAiPlugin: Auto-registers Spring AI activities with workers - Tool system: @DeterministicTool, @SideEffectTool, activity-backed tools - MCP integration: ActivityMcpClient for durable MCP tool calls Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

donald-pinckney

Self-review: temporal-spring-ai plugin

What's done well

Determinism architecture is sound. The core design — routing all non-deterministic operations (LLM calls, vector store ops, embeddings, MCP tools) through Temporal activities — is exactly right. The three-tier tool system (@DeterministicTool for pure functions, @SideEffectTool for cheap non-determinism, activity stubs for durable I/O) maps cleanly onto Temporal's primitives.

Tool execution stays in the workflow. ChatModelActivityImpl sets internalToolExecutionEnabled(false) and only passes tool definitions to the model. The actual tool dispatch happens back in the workflow via ToolCallingManager, which means tool calls respect their Temporal wrapping (activity, sideEffect, etc.).

SideEffectToolCallback correctly wraps each call in Workflow.sideEffect(), recording the result in history on first execution and replaying the stored value.

ActivityChatModel.call() handles the tool loop correctly — it recursively calls itself when the model requests tools that don't returnDirect, maintaining proper conversation history.

Issues flagged inline below

donald-pinckney · 2026-04-06T20:54:02Z

...oral-spring-ai/src/main/java/io/temporal/springai/tool/LocalActivityToolCallbackWrapper.java

+
+  @Override
+  public String call(String toolInput) {
+    String callbackId = UUID.randomUUID().toString();


High severity — non-deterministic call in workflow context.

UUID.randomUUID() is called from the call() method, which runs on the workflow thread. This violates Temporal's replay constraints — on replay a different UUID is generated.

In practice this may work because the local activity replays from markers rather than re-executing, but the intent is unclear and it depends on local activity replay semantics. Use Workflow.randomUUID() instead.

Test coverage added (WorkflowDeterminismTest). Ready to fix — next up.

Done — replaced with Workflow.randomUUID().

donald-pinckney · 2026-04-06T20:54:02Z

...oral-spring-ai/src/main/java/io/temporal/springai/tool/LocalActivityToolCallbackWrapper.java

+ */
+public class LocalActivityToolCallbackWrapper implements ToolCallback {
+
+  private static final Map<String, ToolCallback> CALLBACK_REGISTRY = new ConcurrentHashMap<>();


Medium severity — static registry lifecycle risk.

This static ConcurrentHashMap holds live ToolCallback references. Callbacks are removed in a finally block after the local activity completes, but if the workflow is evicted from the worker cache mid-execution (before finally runs), callbacks leak. Worth documenting or adding periodic cleanup.

Done — added javadoc documenting the eviction leak risk and pointing to getRegisteredCallbackCount() for monitoring.

donald-pinckney · 2026-04-06T20:54:02Z

temporal-spring-ai/src/main/java/io/temporal/springai/util/TemporalStubUtil.java

+        && Proxy.getInvocationHandler(object)
+            .getClass()
+            .getName()
+            .contains("ActivityInvocationHandler")


Medium severity — fragile string matching.

Checking getInvocationHandler().getClass().getName().contains("ActivityInvocationHandler") is brittle. If the SDK renames or refactors these internal handler classes, detection silently breaks and tools fall through to the "unknown type" error. Since this plugin now lives in the SDK repo, consider using internal SDK APIs directly, or at minimum add a comment acknowledging the coupling.

Test coverage added (TemporalToolUtilTest, 22 tests). Ready to refactor — next up.

donald-pinckney · 2026-04-06T20:54:02Z

temporal-spring-ai/src/main/java/io/temporal/springai/model/ActivityChatModel.java

+            .build();
+      } else {
+        // Send tool results back to the model (recursive call)
+        return call(new Prompt(toolExecutionResult.conversationHistory(), prompt.getOptions()));


Medium severity — unbounded recursive tool loop.

This recursively calls call() when the model keeps requesting tools. A misbehaving model could cause infinite recursion / stack overflow. Consider adding a max iteration count. Spring AI's default ToolCallingManager has one internally, but since the loop is driven manually here, that limit is bypassed.

Test coverage added (ChatModelActivityImplTest, 10 tests). Ready to add loop limit — next up.

Done — converted recursive call to iterative loop with MAX_TOOL_CALL_ITERATIONS = 10 limit.

donald-pinckney · 2026-04-06T20:54:02Z

temporal-spring-ai/src/main/java/io/temporal/springai/plugin/SpringAiPlugin.java

+      Worker worker, List<?> clients, List<String> registeredActivities) {
+    try {
+      // Use reflection to avoid loading MCP classes when not on classpath
+      Class<?> mcpActivityClass = Class.forName("io.temporal.springai.mcp.McpClientActivityImpl");


Low severity — unnecessary reflection.

Class.forName("io.temporal.springai.mcp.McpClientActivityImpl") uses reflection to avoid a compile-time dependency, but McpClientActivityImpl is in the same module. This reflection is avoiding a dependency that already exists. If MCP is truly optional, consider moving it to a separate module. If not, just use direct references.

Test coverage added (SpringAiPluginTest, 10 tests). Ready for the conditional auto-config split (T6) — next up.

Done — resolved by T6. McpPlugin directly references McpClientActivityImpl, no more reflection.

donald-pinckney · 2026-04-06T20:54:02Z

temporal-spring-ai/build.gradle

+    compileOnly project(':temporal-spring-boot-autoconfigure')
+
+    api 'org.springframework.boot:spring-boot-autoconfigure'
+    api 'org.springframework.ai:spring-ai-client-chat'


High severity — compileOnly deps needed at runtime.

VectorStore, EmbeddingModel, and MCP are compileOnly here, but SpringAiPlugin directly references these classes in field declarations and method signatures. When they're not on the runtime classpath, Spring fails to introspect the class at all (ClassNotFoundException: org.springframework.ai.vectorstore.VectorStore).

Either:

Change to implementation (simplest, but makes them transitive)

Split SpringAiPlugin so VectorStore/Embedding/MCP handling is in separate classes loaded conditionally

Use runtimeOnly in consumer builds (what we had to do in the samples)

TODO: go with option 2 (split into conditional auto-configuration classes).

Confirmed that Spring AI itself does NOT transitively pull in RAG, vector store, embeddings, or MCP — those are separate opt-in starters. We shouldn't be heavier than the framework we're integrating with.

Plan: keep SpringAiPlugin with only ChatModel (required). Add separate @ConditionalOnClass-guarded config classes for VectorStore, EmbeddingModel, and MCP that register their own activities. The compileOnly scope then stays correct — Spring skips the conditional classes entirely when the dep isn't present.

Done — split into 4 auto-config classes: SpringAiTemporalAutoConfiguration (core), SpringAiVectorStoreAutoConfiguration, SpringAiEmbeddingAutoConfiguration, SpringAiMcpAutoConfiguration. Each guarded by @ConditionalOnClass. compileOnly scopes now work correctly.

donald-pinckney · 2026-04-06T20:54:02Z

temporal-spring-ai/src/main/java/io/temporal/springai/model/ActivityChatModel.java

+ * @see #forDefault()
+ * @see #forModel(String)
+ */
+public class ActivityChatModel implements ChatModel {


Low severity — no streaming support.

ActivityChatModel only implements synchronous call(). Streaming through activities doesn't make sense, but the class should override stream() to throw a clear UnsupportedOperationException rather than silently inheriting a default that may behave unexpectedly.

Done — stream(Prompt) now throws UnsupportedOperationException with a clear message explaining that Temporal activities are request/response based.

T9: Add javadoc to LocalActivityToolCallbackWrapper explaining the leak risk when workflows are evicted from worker cache mid-execution. T11: Override stream() in ActivityChatModel to throw UnsupportedOperationException with a clear message, since streaming through Temporal activities is not supported. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

T1: ChatModelActivityImplTest (10 tests) - type conversion between ChatModelTypes and Spring AI types, multi-model resolution, tool definition passthrough, model options mapping. T2: TemporalToolUtilTest (22 tests) - tool detection and conversion for @DeterministicTool, @SideEffectTool, stub type detection, error cases for unknown/null types. T3: WorkflowDeterminismTest (2 tests) - verifies workflows using ActivityChatModel with tools complete without non-determinism errors in the Temporal test environment. T4: SpringAiPluginTest (10 tests) - plugin registration with various bean combinations, multi-model support, default model resolution. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

donald-pinckney

Found an additional bug during testing.

donald-pinckney · 2026-04-06T21:27:02Z

temporal-spring-ai/src/main/java/io/temporal/springai/model/ActivityChatModel.java

+      metadata = ChatResponseMetadata.builder().model(output.metadata().model()).build();
+    }
+
+    return ChatResponse.builder().generations(generations).metadata(metadata).build();


Bug: NPE when metadata is null.

When output.metadata() is null, metadata stays null and .metadata(null) is passed to ChatResponse.builder(). Spring AI's builder throws an NPE on null metadata.

Fix: only call .metadata() on the builder when metadata is non-null, or pass an empty ChatResponseMetadata.builder().build().

Done — builder now only calls .metadata() when metadata is non-null.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

T5: Replace UUID.randomUUID() with Workflow.randomUUID() in LocalActivityToolCallbackWrapper to ensure deterministic replay. T7: Convert recursive tool call loop in ActivityChatModel.call() to iterative loop with MAX_TOOL_CALL_ITERATIONS (10) limit to prevent infinite recursion from misbehaving models. T14: Fix NPE when ChatResponse metadata is null by only calling .metadata() on the builder when metadata is non-null. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Split the monolithic SpringAiPlugin into one core plugin + three optional plugins, each with its own @ConditionalOnClass-guarded auto-configuration: - SpringAiPlugin: core chat + ExecuteToolLocalActivity (always) - VectorStorePlugin: VectorStore activity (when spring-ai-rag present) - EmbeddingModelPlugin: EmbeddingModel activity (when spring-ai-rag present) - McpPlugin: MCP activity (when spring-ai-mcp present) This fixes ClassNotFoundException when optional deps aren't on the runtime classpath. compileOnly scopes now work correctly because Spring skips loading the conditional classes entirely when the @ConditionalOnClass check fails. Also resolves T10 (unnecessary MCP reflection) — McpPlugin directly references McpClientActivityImpl instead of using Class.forName(). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

donald-pinckney mentioned this pull request Apr 6, 2026

Add Spring AI samples temporalio/samples-java#775

Draft

3 tasks

donald-pinckney commented Apr 6, 2026

View reviewed changes

donald-pinckney and others added 3 commits April 6, 2026 17:09

Update TASK_QUEUE.json: T1-T4, T9, T11 completed

35e9b29

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

donald-pinckney force-pushed the d/20260406-164203 branch from f210b63 to 35e9b29 Compare April 6, 2026 21:25

donald-pinckney commented Apr 6, 2026

View reviewed changes

donald-pinckney and others added 4 commits April 6, 2026 17:27

Add T14 (NPE bug) to TASK_QUEUE.json

bd50654

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Update TASK_QUEUE.json: T5, T6, T7, T10, T14 completed

f868866

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Conversation

donald-pinckney commented Apr 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Related

Known issues to address

Test plan

Uh oh!

donald-pinckney left a comment

Choose a reason for hiding this comment

Self-review: temporal-spring-ai plugin

What's done well

Issues flagged inline below

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

donald-pinckney left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

donald-pinckney commented Apr 6, 2026 •

edited

Loading