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, making AI model calls, tool execution, vector store operations, embeddings, and MCP tool calls durable Temporal primitives.

Design

The core problem

Spring AI's ChatModel.call() does two things in one method: it calls the LLM and executes any tools the LLM requests, looping until the model returns a final text response. In a Temporal workflow, these need to happen in different execution contexts:

LLM calls must run as activities (network I/O, retryable, durable)
Tool execution must run in the workflow (so tools can themselves be activities, sideEffects, or other Temporal primitives)

How ActivityChatModel solves this

ActivityChatModel implements Spring AI's ChatModel interface with the same recursive call() → internalCall() pattern used by OpenAiChatModel and other Spring AI implementations. The difference is what happens inside:

Model call: converts the prompt to serializable ChatModelTypes, sends it to ChatModelActivity (a Temporal activity), gets back the response
Tool check: if the model requested tool calls, ToolCallingManager.executeToolCalls() runs the tools — these are our ActivityToolCallback, SideEffectToolCallback, etc. which execute as Temporal activities or Workflow.sideEffect()
Loop: sends tool results back to the model (recursive internalCall()) until the model returns a final response

The activity-side ChatModelActivityImpl sets internalToolExecutionEnabled(false) so the actual LLM provider (OpenAI, Anthropic, etc.) only returns tool call requests without executing them — execution happens back in the workflow.

Tool classification

Tools passed to TemporalChatClient.builder().defaultTools() are automatically classified:

Type	Detection	Execution	Use case
Activity stub	`instanceof ActivityInvocationHandler`	Temporal activity	Network I/O, external APIs
Local activity stub	`instanceof LocalActivityInvocationHandler`	Temporal local activity	Fast local operations
`@DeterministicTool`	Annotation	Direct call in workflow	Pure functions (string ops, math)
`@SideEffectTool`	Annotation	`Workflow.sideEffect()`	Timestamps, UUIDs, random values
Nexus service stub	`instanceof NexusServiceInvocationHandler`	Nexus operation	Cross-namespace calls

Conditional auto-configuration

Optional integrations only load when their dependencies are on the classpath, matching Spring AI's own approach (where RAG, MCP, etc. are separate opt-in starters):

Auto-config class	Condition	Plugin	Registers
`SpringAiTemporalAutoConfiguration`	`ChatModel` + `Worker`	`SpringAiPlugin`	`ChatModelActivity`, `ExecuteToolLocalActivity`
`SpringAiVectorStoreAutoConfiguration`	`VectorStore` bean	`VectorStorePlugin`	`VectorStoreActivity`
`SpringAiEmbeddingAutoConfiguration`	`EmbeddingModel` bean	`EmbeddingModelPlugin`	`EmbeddingModelActivity`
`SpringAiMcpAutoConfiguration`	`McpSyncClient` class	`McpPlugin`	`McpClientActivity`

Test plan

Unit tests: type conversion — ChatModelActivityImplTest (10 tests)
Unit tests: tool detection — TemporalToolUtilTest (22 tests)
Unit tests: plugin registration — SpringAiPluginTest (9 tests)
Replay tests: workflow determinism via WorkflowReplayer — WorkflowDeterminismTest (2 tests)
Verify all 5 samples boot against Temporal dev server

🤖 Generated with Claude Code

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

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

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

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.

Reverted — removed the iteration limit and switched back to recursive internalCall() matching Spring AI's OpenAiChatModel pattern. Temporal's activity timeouts and workflow execution timeout already bound runaway tool loops.

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

temporal-spring-ai/build.gradle

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

donald-pinckney

Found an additional bug during testing.

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

donald-pinckney · 2026-04-07T20:13:21Z

TASK_QUEUE.json

Obviously will delete this prior to merging ;)

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>

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>