Spring AI Agent Skill

<repositories>
    <repository>
        <id>spring-milestones</id>
        <url>https://repo.spring.io/milestone</url>
    </repository>
</repositories>

repositories {
    maven { url "https://repo.spring.io/milestone" }
}

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-bom</artifactId>
            <version>2.0.0-M4</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

dependencies {
    implementation platform("org.springframework.ai:spring-ai-bom:2.0.0-M4")
}

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-model-openai-sdk</artifactId>
</dependency>

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

mvn org.openrewrite.maven:rewrite-maven-plugin:6.32.0:run \
  -Drewrite.configLocation=https://raw.githubusercontent.com/spring-projects/spring-ai/refs/heads/main/src/rewrite/migrate-to-2-0-0-M3.yaml \
  -Drewrite.activeRecipes=org.springframework.ai.migration.MigrateToSpringAI200M3

// Inject the auto-configured builder
@RestController
public class AgentController {
    private final ChatClient chatClient;

    public AgentController(ChatClient.Builder chatClientBuilder) {
        this.chatClient = chatClientBuilder.build();
    }
}

// Or create from a ChatModel directly
ChatClient chatClient = ChatClient.create(chatModel);

// Or via static builder
ChatClient chatClient = ChatClient.builder(chatModel)
    .defaultSystem("You are a helpful assistant.")
    .build();

ChatClient chatClient = ChatClient.builder(chatModel)
    .defaultSystem("You are a helpful agent.")                    // system prompt
    .defaultAdvisors(new SimpleLoggerAdvisor())                   // advisors
    .defaultTools(new MyTools())                                  // tool objects
    .defaultToolNames("weatherTool")                              // tool bean names
    .defaultOptions(ChatOptions.builder().temperature(0.7).build())
    .build();

// Simple string response
String answer = chatClient.prompt()
    .system("You are a travel agent.")
    .user("Plan a trip to Paris")
    .call()
    .content();

// With template parameters
String answer = chatClient.prompt()
    .user(u -> u
        .text("Tell me about {topic} in {language}")
        .param("topic", "Spring AI")
        .param("language", "English"))
    .call()
    .content();

// Entity mapping (structured output)
record ActorFilms(String actor, List<String> movies) {}

ActorFilms result = chatClient.prompt()
    .user("Generate filmography for Tom Hanks")
    .call()
    .entity(ActorFilms.class);

// Parameterized type
List<ActorFilms> results = chatClient.prompt()
    .user("Generate 5 actors with filmographies")
    .call()
    .entity(new ParameterizedTypeReference<List<ActorFilms>>() {});

// Streaming
Flux<String> stream = chatClient.prompt()
    .user("Tell me a story")
    .stream()
    .content();

// Full response with metadata
ChatClientResponse ccr = chatClient.prompt()
    .user("Hello")
    .call()
    .chatClientResponse();
ChatResponse chatResponse = ccr.chatResponse();
Map<String, Object> advisorContext = ccr.context();

@Configuration
public class ChatClientConfig {

    @Bean
    public ChatClient openAiChatClient(
            @Qualifier("openAiChatModel") ChatModel chatModel) {
        return ChatClient.create(chatModel);
    }

    @Bean
    public ChatClient anthropicChatClient(
            @Qualifier("anthropicChatModel") ChatModel chatModel) {
        return ChatClient.create(chatModel);
    }
}

ChatMemory chatMemory = MessageWindowChatMemory.builder()
    .chatMemoryRepository(repository) // optional, defaults to InMemoryChatMemoryRepository
    .maxMessages(20)                  // default is 20
    .build();

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-model-chat-memory-repository-jdbc</artifactId>
</dependency>

spring.ai.chat.memory.repository.jdbc.initialize-schema=always

@Autowired
JdbcChatMemoryRepository chatMemoryRepository;

ChatMemory chatMemory = MessageWindowChatMemory.builder()
    .chatMemoryRepository(chatMemoryRepository)
    .maxMessages(10)
    .build();

ChatMemory chatMemory = MessageWindowChatMemory.builder().build();

ChatClient chatClient = ChatClient.builder(chatModel)
    .defaultAdvisors(
        MessageChatMemoryAdvisor.builder(chatMemory).build()
    )
    .build();

String conversationId = "session-123";
String response = chatClient.prompt()
    .user("What did I just say?")
    .advisors(a -> a.param(ChatMemory.CONVERSATION_ID, conversationId))
    .call()
    .content();

ChatClient chatClient = ChatClient.builder(chatModel)
    .defaultAdvisors(
        PromptChatMemoryAdvisor.builder(chatMemory).build()
    )
    .build();

ChatClient chatClient = ChatClient.builder(chatModel)
    .defaultAdvisors(
        VectorStoreChatMemoryAdvisor.builder(vectorStore).build()
    )
    .build();

ChatMemory chatMemory = MessageWindowChatMemory.builder().build();
String conversationId = "007";

// Turn 1
chatMemory.add(conversationId, new UserMessage("My name is James Bond"));
ChatResponse r1 = chatModel.call(new Prompt(chatMemory.get(conversationId)));
chatMemory.add(conversationId, r1.getResult().getOutput());

// Turn 2
chatMemory.add(conversationId, new UserMessage("What is my name?"));
ChatResponse r2 = chatModel.call(new Prompt(chatMemory.get(conversationId)));
chatMemory.add(conversationId, r2.getResult().getOutput());
// r2 contains "James Bond"

import org.springframework.ai.tool.annotation.Tool;
import org.springframework.ai.tool.annotation.ToolParam;

@Component
public class WeatherTools {

    @Tool(description = "Get the current weather for a location")
    public WeatherResponse getCurrentWeather(
            @ToolParam(description = "City name") String city,
            @ToolParam(description = "Temperature unit", required = false) String unit) {
        // implementation
        return new WeatherResponse(city, 22.0, "Celsius");
    }
}

public record WeatherResponse(String city, double temperature, String unit) {}

// Per-request tools
String response = chatClient.prompt()
    .user("What's the weather in Paris?")
    .tools(new WeatherTools())
    .call()
    .content();

// Default tools (all requests)
ChatClient chatClient = ChatClient.builder(chatModel)
    .defaultTools(new WeatherTools())
    .build();

// From Spring bean names
ChatClient chatClient = ChatClient.builder(chatModel)
    .defaultToolNames("currentWeather")
    .build();

@Configuration
public class ToolConfig {

    @Bean("currentWeather")
    @Description("Get the weather in a location")
    public Function<WeatherRequest, WeatherResponse> currentWeather() {
        return request -> new WeatherResponse(request.city(), 22.0, "C");
    }
}

// Use by bean name
chatClient.prompt()
    .user("Weather in Paris?")
    .toolNames("currentWeather")
    .call()
    .content();

import org.springframework.ai.tool.FunctionToolCallback;

ToolCallback toolCallback = FunctionToolCallback
    .builder("currentWeather", (WeatherRequest req) -> getWeather(req))
    .description("Get the weather in location")
    .inputType(WeatherRequest.class)
    .build();

chatClient.prompt()
    .user("Weather in Paris?")
    .toolCallbacks(toolCallback)
    .call()
    .content();

@Tool(description = "Get customer info")
public Customer getCustomer(Long id, ToolContext toolContext) {
    String tenantId = (String) toolContext.getContext().get("tenantId");
    return customerRepository.findById(id, tenantId);
}

// Pass context when calling
chatClient.prompt()
    .user("Tell me about customer 42")
    .tools(new CustomerTools())
    .toolContext(Map.of("tenantId", "acme"))
    .call()
    .content();

ChatOptions chatOptions = ToolCallingChatOptions.builder()
    .toolCallbacks(ToolCallbacks.from(new MyTools()))
    .internalToolExecutionEnabled(false) // disable auto-execution
    .build();

ToolCallingManager toolCallingManager = ToolCallingManager.builder().build();
Prompt prompt = new Prompt("Do the thing", chatOptions);
ChatResponse response = chatModel.call(prompt);

while (response.hasToolCalls()) {
    ToolExecutionResult result = toolCallingManager.executeToolCalls(prompt, response);
    prompt = new Prompt(result.conversationHistory(), chatOptions);
    response = chatModel.call(prompt);
}

String finalAnswer = response.getResult().getOutput().getText();

import org.springframework.ai.tool.augmentation.AugmentedToolCallbackProvider;

public record AgentThinking(
    @ToolParam(description = "Your reasoning for calling this tool", required = true)
    String innerThought,
    @ToolParam(description = "Confidence level (low, medium, high)", required = false)
    String confidence
) {}

AugmentedToolCallbackProvider<AgentThinking> provider = AugmentedToolCallbackProvider
    .<AgentThinking>builder()
    .toolObject(new MyTools())
    .argumentType(AgentThinking.class)
    .argumentConsumer(event -> {
        log.info("Tool: {} | Reasoning: {}", event.toolDefinition().name(),
            event.arguments().innerThought());
    })
    .removeExtraArgumentsAfterProcessing(true)
    .build();

ChatClient chatClient = ChatClient.builder(chatModel)
    .defaultToolCallbacks(provider)
    .build();

spring.ai.tools.throw-exception-on-error=false

public interface Advisor extends Ordered {
    String getName();
}

public interface CallAdvisor extends Advisor {
    ChatClientResponse adviseCall(
        ChatClientRequest chatClientRequest,
        CallAdvisorChain callAdvisorChain);
}

public interface StreamAdvisor extends Advisor {
    Flux<ChatClientResponse> adviseStream(
        ChatClientRequest chatClientRequest,
        StreamAdvisorChain streamAdvisorChain);
}

ChatClient chatClient = ChatClient.builder(chatModel)
    .defaultAdvisors(
        MessageChatMemoryAdvisor.builder(chatMemory).build(),
        QuestionAnswerAdvisor.builder(vectorStore).build(),
        new SimpleLoggerAdvisor()
    )
    .build();

// Per-request advisors
chatClient.prompt()
    .advisors(new SafeGuardAdvisor())
    .user("Potentially harmful input")
    .call()
    .content();

public class MyLoggingAdvisor implements CallAdvisor, StreamAdvisor {
    private static final Logger log = LoggerFactory.getLogger(MyLoggingAdvisor.class);

    @Override
    public String getName() {
        return this.getClass().getSimpleName();
    }

    @Override
    public int getOrder() {
        return 0;
    }

    @Override
    public ChatClientResponse adviseCall(ChatClientRequest request,
            CallAdvisorChain chain) {
        log.debug("Request: {}", request);
        ChatClientResponse response = chain.nextCall(request);
        log.debug("Response: {}", response);
        return response;
    }

    @Override
    public Flux<ChatClientResponse> adviseStream(ChatClientRequest request,
            StreamAdvisorChain chain) {
        log.debug("Stream request: {}", request);
        return chain.nextStream(request);
    }
}

ToolCallingManager toolCallingManager = ToolCallingManager.builder().build();

ToolCallAdvisor toolCallAdvisor = ToolCallAdvisor.builder()
    .toolCallingManager(toolCallingManager)
    .advisorOrder(BaseAdvisor.HIGHEST_PRECEDENCE + 300)
    .build();

ChatClient chatClient = ChatClient.builder(chatModel)
    .defaultAdvisors(toolCallAdvisor)
    .build();

<!-- Standard (STDIO + Servlet SSE/Streamable-HTTP) -->
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-mcp-client</artifactId>
</dependency>

<!-- WebFlux-based transports -->
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-mcp-client-webflux</artifactId>
</dependency>

<!-- STDIO server -->
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-mcp-server</artifactId>
</dependency>

<!-- WebMVC server (SSE/Streamable-HTTP/Stateless) -->
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-mcp-server-webmvc</artifactId>
</dependency>

<!-- WebFlux server -->
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-mcp-server-webflux</artifactId>
</dependency>

spring:
  ai:
    mcp:
      client:
        enabled: true
        name: my-mcp-client
        version: 1.0.0
        type: SYNC                    # SYNC or ASYNC
        request-timeout: 20s
        toolcallback:
          enabled: true               # register MCP tools as Spring AI ToolCallbacks
        # STDIO transport
        stdio:
          connections:
            my-server:
              command: npx
              args:
                - "-y"
                - "@modelcontextprotocol/server-filesystem"
                - "/Users/me/data"
              env:
                API_KEY: secret
          # Or reference Claude Desktop JSON format
          servers-configuration: classpath:mcp-servers.json
        # SSE transport
        sse:
          connections:
            remote-server:
              url: http://localhost:8080
              sse-endpoint: /sse     # default
        # Streamable-HTTP transport
        streamable-http:
          connections:
            server1:
              url: http://localhost:8083
              endpoint: /mcp         # default

@Autowired
private SyncMcpToolCallbackProvider toolCallbackProvider;

ChatClient chatClient = ChatClient.builder(chatModel)
    .defaultToolCallbacks(toolCallbackProvider)
    .build();

String response = chatClient.prompt()
    .user("List files in my data directory")
    .call()
    .content();

spring:
  ai:
    mcp:
      server:
        type: SYNC                   # SYNC or ASYNC
        stdio: false                 # true for STDIO protocol
        protocol: SSE                # SSE, STREAMABLE, or STATELESS

import org.springframework.ai.mcp.annotation.McpTool;
import org.springframework.ai.mcp.annotation.McpToolParam;

@Component
public class CalculatorServer {

    @McpTool(name = "add", description = "Add two numbers")
    public int add(
            @McpToolParam(description = "First number", required = true) int a,
            @McpToolParam(description = "Second number", required = true) int b) {
        return a + b;
    }
}

@McpResource(uri = "config://{key}", name = "Configuration")
public String getConfig(String key) { ... }

@McpPrompt(name = "analysis_prompt", description = "Data analysis prompt")
public String analysisPrompt() { ... }

@McpComplete(name = "region_completion")
public List<String> completeRegions(String partial) { ... }

@McpLogging(clients = "my-server")
public void handleLog(LoggingMessageNotification notification) { ... }

@McpSampling(clients = "my-server")
public CreateMessageResult handleSampling(CreateMessageRequest request) { ... }

@McpElicitation(clients = "my-server")
public ElicitResult handleElicitation(ElicitRequest request) { ... }

@McpProgress(clients = "my-server")
public void handleProgress(ProgressNotification notification) { ... }

@Component
public class MyToolFilter implements McpToolFilter {
    @Override
    public boolean test(McpConnectionInfo info, McpSchema.Tool tool) {
        return !tool.name().startsWith("experimental_");
    }
}

// In 2.0: McpSyncClientCustomizer and McpAsyncClientCustomizer are replaced
// by a single generic McpClientCustomizer<B> interface
@Component
public class MyMcpCustomizer implements McpClientCustomizer<McpClient.SyncSpec> {
    @Override
    public void customize(String serverName, McpClient.SyncSpec spec) {
        spec.requestTimeout(Duration.ofSeconds(30));
        spec.sampling(request -> { /* handle */ return result; });
    }
}

public class ChainWorkflow {
    private final ChatClient chatClient;
    private final String[] steps;

    public String chain(String userInput) {
        String response = userInput;
        for (String stepPrompt : steps) {
            String input = String.format("{%s}\n{%s}", stepPrompt, response);
            response = chatClient.prompt(input).call().content();
        }
        return response;
    }
}

Map<String, String> routes = Map.of(
    "billing", "You are a billing specialist...",
    "technical", "You are a technical support engineer...",
    "general", "You are a customer service rep..."
);

RoutingWorkflow workflow = new RoutingWorkflow(chatClient);
String response = workflow.route("My account was charged twice", routes);

List<String> results = new ParallelizationWorkflow(chatClient)
    .parallel(
        "Analyze market impact for this stakeholder group.",
        List.of("Customers: ...", "Employees: ...", "Investors: ..."),
        4 // parallelism
    );

OrchestratorWorkersWorkflow workflow = new OrchestratorWorkersWorkflow(chatClient);
WorkerResponse response = workflow.process(
    "Generate technical and user-friendly docs for a REST API endpoint"
);

EvaluatorOptimizerWorkflow workflow = new EvaluatorOptimizerWorkflow(chatClient);
RefinedResponse response = workflow.loop(
    "Create a Java class implementing a thread-safe counter"
);
// response.solution() -- final refined code
// response.chainOfThought() -- evolution across iterations

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

# ChatClient logging
spring.ai.chat.client.observations.log-prompt=false
spring.ai.chat.client.observations.log-completion=false

# ChatModel logging
spring.ai.chat.observations.log-prompt=false
spring.ai.chat.observations.log-completion=false
spring.ai.chat.observations.include-error-logging=false

# Tool calling
spring.ai.tools.observations.include-content=false

# Image model
spring.ai.image.observations.log-prompt=false

# Vector store
spring.ai.vectorstore.observations.log-query-response=false

gen_ai.operation.name      -- operation type
gen_ai.system              -- provider name (openai, anthropic, spring_ai)
gen_ai.request.model       -- requested model
gen_ai.response.model      -- actual model used
spring.ai.kind             -- chat_client, advisor, tool_call, vector_store

gen_ai_client_token_usage_total{gen_ai_token_type="input"}
gen_ai_client_token_usage_total{gen_ai_token_type="output"}
gen_ai_client_token_usage_total{gen_ai_token_type="total"}

logging.level.org.springframework.ai.chat.client.advisor=DEBUG

@SpringBootApplication
public class AgentApplication {
    public static void main(String[] args) {
        SpringApplication.run(AgentApplication.class, args);
    }

    @Bean
    ChatClient chatClient(ChatClient.Builder builder, ChatMemory chatMemory) {
        return builder
            .defaultSystem("You are a helpful travel assistant.")
            .defaultAdvisors(
                MessageChatMemoryAdvisor.builder(chatMemory).build(),
                new SimpleLoggerAdvisor()
            )
            .defaultTools(new TravelTools())
            .build();
    }

    @Bean
    ChatMemory chatMemory(ChatMemoryRepository repository) {
        return MessageWindowChatMemory.builder()
            .chatMemoryRepository(repository)
            .maxMessages(20)
            .build();
    }
}

@Component
class TravelTools {

    @Tool(description = "Search for flights between two cities on a given date")
    public List<Flight> searchFlights(
            @ToolParam(description = "Departure city") String from,
            @ToolParam(description = "Arrival city") String to,
            @ToolParam(description = "Date in YYYY-MM-DD format") String date) {
        return flightService.search(from, to, LocalDate.parse(date));
    }

    @Tool(description = "Book a flight by flight number")
    public BookingConfirmation bookFlight(
            @ToolParam(description = "Flight number") String flightNumber) {
        return bookingService.book(flightNumber);
    }
}

@RestController
@RequestMapping("/chat")
class ChatController {

    private final ChatClient chatClient;

    ChatController(ChatClient chatClient) {
        this.chatClient = chatClient;
    }

    @PostMapping
    String chat(@RequestParam String message,
                @RequestParam(defaultValue = "default") String sessionId) {
        return chatClient.prompt()
            .user(message)
            .advisors(a -> a.param(ChatMemory.CONVERSATION_ID, sessionId))
            .call()
            .content();
    }
}

# Model provider (OpenAI SDK starter)
spring.ai.openai-sdk.api-key=${OPENAI_API_KEY}
spring.ai.openai-sdk.chat.options.model=gpt-5-mini
spring.ai.openai-sdk.chat.options.temperature=0.7  # REQUIRED in 2.0 -- no implicit default

# Memory (JDBC)
spring.ai.chat.memory.repository.jdbc.initialize-schema=always
spring.datasource.url=jdbc:postgresql://localhost:5432/agentdb
spring.datasource.username=agent
spring.datasource.password=secret

# Observability
spring.ai.chat.client.observations.log-prompt=true
spring.ai.chat.client.observations.log-completion=true
spring.ai.chat.observations.log-prompt=true
spring.ai.tools.observations.include-content=true

# Actuator
management.endpoints.web.exposure.include=health,metrics,prometheus

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.ai</groupId>
        <artifactId>spring-ai-starter-model-openai-sdk</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.ai</groupId>
        <artifactId>spring-ai-starter-model-chat-memory-repository-jdbc</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-actuator</artifactId>
    </dependency>
    <dependency>
        <groupId>org.postgresql</groupId>
        <artifactId>postgresql</artifactId>
        <scope>runtime</scope>
    </dependency>
</dependencies>