Use Spring AI AgentCore Starter in our sample application to deploy and run our MCP client on AgentCore Runtime

Building AI Agents with Spring AI and Amazon Bedrock AgentCore

Building AI Agents with Spring AI and Amazon Bedrock AgentCore – Part 1 Introduction to the series

Building AI Agents with Spring AI and Amazon Bedrock AgentCore – Part 2 Deploy Conference Search application on AgentCore Runtime

Building AI Agents with Spring AI and Amazon Bedrock AgentCore – Part 3 Develop local MCP client for Conference application

Building AI Agents with Spring AI and Amazon Bedrock AgentCore – Part 4 Provide MCP tools for Conference application via AgentCore Gateway

Building AI Agents with Spring AI and Amazon Bedrock AgentCore – Part 5 Deploy MCP client for Conference application on AgentCore Runtime

Building AI Agents with Spring AI and Amazon Bedrock AgentCore – Part 6 Deploy MCP client on AgentCore Runtime using Spring AI AgentCore Starter

Introduction

In part 5, we looked at how to deploy and run our MCP client on AgentCore Runtime. Starting from this article, we’ll look at the Spring AI AgentCore functionality. In this article, we’ll use Spring AI AgentCore Starter in our sample application to deploy and run our MCP client on AgentCore Runtime. As Spring AI 2.0 and Spring Boot 4.1 have both already gone GA, I updated our application to use them; see pom.xml. For this, I created a new spring-ai-2.0-ac-conference-app-agent-bedrock-agentcore-runtime. It consists of the agent and Infrastructure as Code (IaC) subfolders.

Differences in the implementation of the MCP client for the Conference application between Spring AI 1.1 and 2.0

I have noticed 2 major differences in the implementation of the MCP client for the Conference application. We developed it mainly in part 3, and then adjusted it in part 4 and part 5. See SpringAIAgentController.java for the full version of the controller.

The first one is that ChatClient now requires passing the ChatOptions.Builder object to the defaultOptions method instead of the ChatOptions object itself :

var options = ToolCallingChatOptions.builder()
        .model("us.anthropic.claude-sonnet-4-6")
        .maxTokens(2000);
	
this.chatClient = builder.defaultOptions(options)
        ...
        .build();

Next, the biggest difference is that instead of using WebClient from the Spring Webflux dependency, Spring AI 2.0 now uses HttpRequest.Builder from the java.net.http module to create an MCP HTTP Streamable transport. Also, the implementation of this protocol is now in the HttpClientStreamableHttpTransport class, which was adjusted to use java.net.http module. In Spring AI 1.*, the class name was WebClientStreamableHttpTransport:

private McpClientTransport getMcpClientTransport(String token) {
		
 var mcpServerConfig= this.getMCPServerConfig();
 var headerValue = "Bearer " + token;
		
 var httpRequestBuilder = HttpRequest.newBuilder()
     .header("Authorization", headerValue);
		
 return HttpClientStreamableHttpTransport.builder(mcpServerConfig.baseUrl)
     .connectTimeout(Duration.ofMinutes(3))
     .endpoint(mcpServerConfig.endpoint)		
     .requestBuilder(httpRequestBuilder)
     .build();
}

It also requires splitting the MCP endpoint URL into 2 parts: base URL (domain) and endpoint itself (/mcp), which we did in the application.properties:

amazon.bedrock.agentcore.gateway.base.url=https://spring-ai-conference-search-agentcore-gateway-xizwpytsgm.gateway.bedrock-agentcore.us-east-1.amazonaws.com
amazon.bedrock.agentcore.gateway.endpoint=/mcp

Lastly, Spring AI 2.0 introduced some changes to how to use the MCP tools. This is how the code looked in the previous Spring AI 1.x versions:

return this.chatClient.prompt().user(prompt)
   .tools(new DateTimeTools())
   .toolCallbacks(asyncMcpToolCallbackProvider.getToolCallbacks())
   .stream().content();

The code in Spring AI 2.0 uses the tools method, capable of accepting the local tools as well as tool callbacks as its parameters:

return this.chatClient.prompt().user(prompt)
  .tools(new DateTimeTools(),syncMcpToolCallbackProvider.getToolCallbacks())
  .stream().content();

Everything else remains the same as described in parts 3-5.

Spring AI AgentCore SDK

Spring AI AgentCore SDK is an open-source library that brings Amazon Bedrock AgentCore capabilities into Spring AI through familiar patterns: annotations, auto-configuration, and composable advisors. We’ll start by using Spring AI AgentCore Starter in this article and then cover Spring AI AgentCore Memory in subsequent articles.

Spring AI AgentCore Starter

Spring AI AgentCore Starter is a Spring Boot starter that enables existing Spring Boot applications to conform to the Amazon Bedrock AgentCore Runtime contract with minimal configuration. Its features currently include:

Auto-configuration: Automatically sets up AgentCore endpoints when added as a dependency
Annotation-based: Simple @AgentCoreInvocation annotation to mark agent methods
SSE Streaming: Server-Sent Events support with Flux return types
Smart health checks: Built-in /ping endpoint with Spring Boot Actuator integration
Async task tracking: Convenient methods for background task tracking
Rate limiting: Built-in Bucket4j throttling for invocations and ping endpoints

Let’s add the relevant dependencies to pom.xml:

<dependencyManagement>
   <dependencies>
       <dependency>
            <groupId>org.springaicommunity</groupId>
            <artifactId>spring-ai-agentcore-bom</artifactId>
            <version>${spring-ai-agentcore-version}</version> 
            <type>pom</type>
            <scope>import</scope>
       </dependency>
   </dependencies>
</dependencyManagement>
...
<dependencies>
  <dependency>
     <groupId>org.springaicommunity</groupId>
     <artifactId>spring-ai-agentcore-runtime-starter</artifactId>
  </dependency>
  <dependency>
     <groupId>org.springframework.boot</groupId>
     <artifactId>spring-boot-starter-actuator</artifactId>
  </dependency>
</dependencies>

By adding the spring-ai-agentcore-runtime-starter dependency, we can now use org.springaicommunity.agentcore.annotation.AgentCoreInvocation annotation to annotate the method. Exactly this method we’ll expose as a /invocation POST endpoint on the Bedrock AgentCore Runtime. Please note that only one method per application can be annotated with this annotation. Next, we need to make a small adjustment to the SpringAIAgentController to use this annotation:

@AgentCoreInvocation
public Flux<String> invoceAsync(PromptRequest promptRequest, AgentCoreContext agentCoreContext) {
...
return this.chatClient.prompt()
         .user(promptRequest.prompt())
         .toolCallbacks(toolCallbacks).stream().content();
}

PromptRequest is a Java record representing a prompt:

public record PromptRequest(String prompt){};

Spring AI Starter also supports rate limiting. The starter includes built-in rate limiting using Bucket4j to protect against excessive requests. However, rate limiting is deactivated by default and will be active only if limits are defined in application.properties:

agentcore.throttle.invocations-limit=20
agentcore.throttle.ping-limit=250

The provided rate limit response is an HTTP response code 429: ({“error”:”Rate limit exceeded”}). Rate limits are also applied per client IP address and reset every minute.

Next, please comment out all application properties starting with agentcore.memory, as we’ll need them in the upcoming article where we’ll cover Bedrock AgentCore Memory.

By adding the dependency to the spring-boot-starter-actuator, we enabled intelligent health monitoring. With that, we no longer need to implement the /ping endpoint ourselves.

Without Spring Boot Actuator:

Returns static “Healthy” status
Always responds with HTTP 200

With Spring Boot Actuator:

Integrates with Actuator health checks
Maps Actuator status to AgentCore format: UP → “Healthy” (HTTP 200), DOWN → “Unhealthy” (HTTP 503), Other → “Unknown” (HTTP 503)
Tracks status change timestamps
Thread-safe concurrent access

Then, let’s briefly cover the IaC part with CDK for Java, which I implemented in the RuntimeWithMCPStack stack. It’s completely identical to the IaC that we described in part 5. I wanted to have a separate IaC stack (also including an IAM role and ECR repository) for this Spring AI 2.0 and Spring AI AgentCore application. Also, please comment out the ShortTermMemoryStack and LongTermMemoryStack execution in the CDKApp class. We’ll cover those later.

You can deploy the stack with the command:

cdk deploy spring-ai-ac-conference-application-agentcore-runtime-stack -c awsAccountId={YOUR_AWS_ACCOUNT_ID}`

Finally, please visit the above-mentioned part 5 for more details on how to deploy this application on AgentCore Runtime and send prompts to it. Also, all the prompts remain valid, as this is the same application, but using Spring AI AgentCore now.

Conclusion

In this article, we used Spring AI AgentCore Starter in our sample application to deploy and run our MCP client on AgentCore Runtime. We used several useful features of the Spring AI AgentCore Starter, like annotation-based auto-configuration, smart health checks, and rate limiting.

Until now, our agent deployed on AgentCore Runtime was stateless. If we apply for the conferences with some talks and then ask the agent in the next conversation about which talks we applied for which conferences, the agent won’t be able to answer. In the next article, we’ll add the AgentCore Memory to our application. We’ll start with the short-term memory and later add the long-term memory. Then, we’ll show how to use Spring AI AgentCore Memory, which provides the Spring AI ChatMemory integration with the Amazon Bedrock AgentCore Memory service.