Skip to content

README.md

Latest commit

 

History

History
111 lines (81 loc) · 3.25 KB

README.md

File metadata and controls

111 lines (81 loc) · 3.25 KB

temporal-spring-ai

Integrates Spring AI with Temporal 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):

<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:

@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.

@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).

@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.

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:

new VectorStorePlugin(vectorStore)
new EmbeddingModelPlugin(embeddingModel)
new McpPlugin()