Spring AI Bedrock AgentCore

Spring Boot starter for AWS Bedrock AgentCore Runtime integration

GitHub • Maven Central

Overview

A Spring Boot starter that enables existing Spring Boot applications to conform to the AWS Bedrock AgentCore Runtime contract with minimal configuration. Simply add the dependency and annotate your agent methods.

Version: 1.0.0-RC3

Modules

Module	Description
spring-ai-bedrock-agentcore-starter	Core starter for AgentCore Runtime integration
spring-ai-memory-bedrock-agentcore	Spring AI ChatMemoryRepository using AgentCore Memory

Key Features

Auto-configuration

Automatically sets up AgentCore endpoints when added as dependency

Annotation-based

Simple @AgentCoreInvocation annotation to mark agent methods

SSE Streaming

Server-Sent Events support with Flux<String> return types

Health Checks

Built-in /ping endpoint with Spring Boot Actuator integration

Async Task Tracking

Prevents premature shutdown during background work

Rate Limiting

Built-in Bucket4j throttling for invocations and ping endpoints

Quick Start

1. Add Dependency

<dependency>
    <groupId>org.springaicommunity</groupId>
    <artifactId>spring-ai-bedrock-agentcore-starter</artifactId>
    <version>1.0.0-RC3</version>
</dependency>

2. Create Agent Method

@Service
public class MyAgentService {

    @AgentCoreInvocation
    public String handleUserPrompt(MyRequest request) {
        return "You said: " + request.prompt;
    }
}

3. Run Application

The application will automatically expose:

• POST /invocations - Agent processing endpoint
• GET /ping - Health check endpoint

Supported Method Signatures

Basic POJO Method

@AgentCoreInvocation
public MyResponse processRequest(MyRequest request) {
    return new MyResponse("Processed: " + request.prompt());
}

record MyRequest(String prompt) {}
record MyResponse(String message) {}

With AgentCore Context

@AgentCoreInvocation
public MyResponse processWithContext(MyRequest request, AgentCoreContext context) {
    var sessionId = context.getHeader(AgentCoreHeaders.SESSION_ID);
    return new MyResponse("Session " + sessionId + ": " + request.prompt());
}

Map Method (Flexible)

@AgentCoreInvocation
public Map<String, Object> processData(Map<String, Object> data) {
    return Map.of(
        "input", data,
        "response", "Processed: " + data.get("message"),
        "timestamp", System.currentTimeMillis()
    );
}

String Method (text/plain)

@AgentCoreInvocation
public String handlePrompt(String prompt) {
    return "Response: " + prompt;
}

SSE Streaming with Spring AI

@AgentCoreInvocation
public Flux<String> streamingAgent(String prompt) {
    return chatClient.prompt().user(prompt).stream().content();
}

Background Task Tracking

AWS Bedrock AgentCore Runtime monitors agent health and may shut down agents that appear idle. Use AgentCoreTaskTracker to communicate active work:

@AgentCoreInvocation
public String asyncTaskHandling(MyRequest request, AgentCoreContext context) {
    agentCoreTaskTracker.increment();  // Starting background work

    CompletableFuture.runAsync(() -> {
        // Long-running background work
    }).thenRun(agentCoreTaskTracker::decrement);  // Work completed

    return "Task started";
}

The /ping endpoint returns:

• “Healthy” - Agent is ready, no background tasks
• “HealthyBusy” - Agent is healthy but actively processing (prevents shutdown)
• “Unhealthy” - Agent has issues (with Actuator integration)

Health Monitoring

Without Spring Boot Actuator:

• Returns static “Healthy” status
• Always responds with HTTP 200

With Spring Boot Actuator:

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

• Integrates with Actuator health checks
• Maps Actuator status: UP → “Healthy”, DOWN → “Unhealthy”
• Tracks status change timestamps

Custom Controller Override

Override default controllers with custom implementations using marker interfaces:

// Override /invocations
@RestController
public class CustomInvocationsController implements AgentCoreInvocationsHandler {

    @PostMapping("/invocations")
    public ResponseEntity<?> handleInvocations(@RequestBody String request) {
        return ResponseEntity.ok("Custom response");
    }
}

// Override /ping
@RestController
public class CustomPingController implements AgentCorePingHandler {

    @GetMapping("/ping")
    public ResponseEntity<?> ping() {
        return ResponseEntity.ok(Map.of("status", "Custom Healthy"));
    }
}

Configuration

# Rate limits in requests per minute (optional, disabled by default)
agentcore.throttle.invocations-limit=50
agentcore.throttle.ping-limit=200

---

Memory Module

The spring-ai-memory-bedrock-agentcore module provides Spring AI ChatMemoryRepository integration with AWS Bedrock AgentCore Memory for persistent conversation storage.

Add Dependency

<dependency>
    <groupId>org.springaicommunity</groupId>
    <artifactId>spring-ai-memory-bedrock-agentcore</artifactId>
    <version>1.0.0-RC3</version>
</dependency>

Configure Memory

agentcore:
  memory:
    memory-id: your-agentcore-memory-id    # Required
    total-events-limit: 100                # Max events to retrieve
    default-session: default-session       # Default session name
    page-size: 50                          # API pagination size
    ignore-unknown-roles: false            # Handle unknown roles

Use with Spring AI

@Service
public class ChatService {

    private final ChatClient chatClient;
    private final ChatMemory chatMemory;

    public ChatService(ChatClient.Builder chatClientBuilder, ChatMemoryRepository memoryRepository) {
        this.chatClient = chatClientBuilder.build();
        this.chatMemory = MessageWindowChatMemory.builder()
            .chatMemoryRepository(memoryRepository)
            .maxMessages(10)
            .build();
    }

    public String chat(String conversationId, String message) {
        return chatClient.prompt()
            .user(message)
            .advisors(chatMemory.getChatMemoryAdvisor(conversationId))
            .call()
            .content();
    }
}

Conversation ID Format

• Simple: user123 → actor: user123, session: default-session
• With Session: user123:session456 → actor: user123, session: session456

Message Type Mapping

Spring AI Message	AgentCore Role	Supported
UserMessage	USER	Yes
AssistantMessage	ASSISTANT	Yes
SystemMessage	N/A	Filtered
ToolResponseMessage	N/A	Filtered

AWS Permissions

{
  "Effect": "Allow",
  "Action": [
    "bedrock-agentcore:ListEvents",
    "bedrock-agentcore:CreateEvent",
    "bedrock-agentcore:DeleteEvent"
  ],
  "Resource": "arn:aws:bedrock-agentcore:*:*:memory/*"
}

Examples

See the examples/ directory in the repository:

Example	Description
simple-spring-boot-app/	Minimal AgentCore agent with async task tracking
spring-ai-sse-chat-client/	SSE streaming with Spring AI and Amazon Bedrock
spring-ai-simple-chat-client/	Traditional Spring AI integration
spring-ai-override-invocations/	Custom controller override using marker interfaces
spring-ai-extended-chat-client/	Extended chat client with JWT and Terraform deployment
spring-ai-memory-integration/	Memory module integration example

Requirements

• Java 17+
• Spring Boot 3.x
• Spring AI 1.1.1+ (for memory module)

Resources

GitHub Repository

Source code and contribution guidelines

AWS Bedrock AgentCore

AWS Bedrock AgentCore documentation

License

This project is licensed under the Apache License 2.0.