Add temporal-spring-ai module

[donald-pinckney]

Summary

Adds temporal-spring-ai, a new module that integrates Spring AI with Temporal workflows. AI model calls become durable activities; tools can be activity stubs, @SideEffectTool-wrapped, or plain workflow code.

Quick Start

@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 with @ActivityInterface + @Tool. Auto-detected, executed as durable activities.
• @SideEffectTool — wrapped in Workflow.sideEffect(). Use for timestamps, UUIDs, etc.
• Plain tools — any class with @Tool methods. Executes directly in workflow context; user is responsible for determinism.
• Nexus service stubs — auto-detected, executed as Nexus operations.

Optional Integrations

Auto-configured when their dependencies are on the classpath. Can also be created programmatically.

Feature	Dependency	What it registers
Vector Store	spring-ai-rag	VectorStoreActivity
Embeddings	spring-ai-rag	EmbeddingModelActivity
MCP	spring-ai-mcp	McpClientActivity

Compatibility

Dependency	Minimum Version
Java	17
Spring Boot	3.x
Spring AI	1.1.0
Temporal Java SDK	1.33.0

Related

• Samples: Add Spring AI samples samples-java#775
• Workshop demos: Migrate demos 2-4 to new temporal-spring-ai plugin temporal-community/springio-agents-springai-temporal#1

🤖 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

[donald-pinckney]

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.

[donald-pinckney]

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

[DABH]

Would a bounded size or TTL-based eviction strategy for the hash map make more sense, as opposed to just giving users a method to monitor the count? Even some (imo very high) limit like 10,000? Or maybe log a warning in case a user hits some huge number like that? Wdyt?

[donald-pinckney]

most likely not going ahead with SandboxingAdvisor, which would also kill this.

[donald-pinckney]

Found an additional bug during testing.

[donald-pinckney]

Obviously will delete this prior to merging ;)

[tconley1428]

Is the primary reason for these being separate plugins because of spring configuration interaction? Otherwise I would think it makes more sense to have one with configurations.

[donald-pinckney]

it's not just Spring config interaction, it's about not forcing transitive dependencies on users. A single plugin would either need all deps as implementation or use reflection/Object types to avoid class references (fragile/yucky). Given that normal (non-Temporal) Spring AI already ships things as separate artifacts, this seemed like the most natural spring-ai-native design.

Other option is to have implementation dependencies on Spring AI's various artifacts (for MCP, RAG, etc.), which is simpler but aligns less with Spring from what I've seen. Others could weigh in here though.

To be clear, you can't just have compileOnly deps on those optional dependencies, because Spring needs to load and introspect the plugin class at startup, so any field types that don't exist at runtime cause a ClassNotFoundException.

[tconley1428]

Is there a good reason we are making local activities so primary?

[donald-pinckney]

would be resolved following other discussion below