Spring AI

Spring AI Adapter

AgentRuntime implementation backed by Spring AI ChatClient. When this JAR is on the classpath, @AiEndpoint automatically uses Spring AI for streaming.

Maven Coordinates

<dependency>
    <groupId>org.atmosphere</groupId>
    <artifactId>atmosphere-spring-ai</artifactId>
    <version>${project.version}</version>
</dependency>

How It Works

Drop the dependency alongside atmosphere-ai and the framework auto-detects it via ServiceLoader:

@AiEndpoint(path = "/ai/chat", systemPrompt = "You are a helpful assistant")
public class MyChat {

    @Prompt
    public void onPrompt(String message, StreamingSession session) {
        session.stream(message);  // uses Spring AI ChatClient automatically
    }
}

No code changes needed — the SpringAiAgentRuntime implementation has priority 100, which takes precedence over the built-in client (priority 0).

Direct Usage

For full control, use SpringAiStreamingAdapter directly:

var session = StreamingSessions.start(resource);
springAiAdapter.stream(chatClient, prompt, session);

With advisors:

springAiAdapter.stream(chatClient, prompt, session, myAdvisor);

With a customizer:

springAiAdapter.stream(chatClient, prompt, session, spec -> {
    spec.system("Custom system prompt");
});

Spring Boot Auto-Configuration

AtmosphereSpringAiAutoConfiguration provides:

SpringAiStreamingAdapter bean
SpringAiAgentRuntime bridge bean (connects Spring-managed ChatClient to the SPI)

The ChatClient bean must be configured separately via Spring AI’s own starter.

Samples

Spring Boot AI Chat — drop atmosphere-spring-ai on the classpath and the same @AiEndpoint code switches to Spring AI

Native structured output

When an @AiEndpoint declares responseAs = SomeRecord.class, this runtime enforces the schema at the provider level on the OpenAI-backed path via OpenAiChatOptions.outputSchema(…) (Spring AI 2.0, which maps it to a strict json_schema response format) — the model cannot emit non-conforming JSON. Non-OpenAI chat models ignore the OpenAI-specific option and fall through to the prompt-injection path. This is the NATIVE_STRUCTURED_OUTPUT capability; activation is governed by NativeStructuredOutputMode (AUTO default), which falls back gracefully if the provider rejects the schema.