{"id":36592534,"url":"https://github.com/spring-ai-community/spring-ai-bedrock-agentcore","last_synced_at":"2026-01-12T08:20:31.949Z","repository":{"id":326991844,"uuid":"1106719413","full_name":"spring-ai-community/spring-ai-bedrock-agentcore","owner":"spring-ai-community","description":"Spring Boot integrations for Amazon Bedrock AgentCore","archived":false,"fork":false,"pushed_at":"2026-01-09T09:12:34.000Z","size":193,"stargazers_count":14,"open_issues_count":6,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-09T10:53:32.127Z","etag":null,"topics":["agentcore","ai","aws","bedrock","spring"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/spring-ai-community.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-29T20:01:24.000Z","updated_at":"2026-01-08T15:00:28.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/spring-ai-community/spring-ai-bedrock-agentcore","commit_stats":null,"previous_names":["spring-ai-community/spring-ai-bedrock-agentcore"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/spring-ai-community/spring-ai-bedrock-agentcore","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spring-ai-community%2Fspring-ai-bedrock-agentcore","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spring-ai-community%2Fspring-ai-bedrock-agentcore/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spring-ai-community%2Fspring-ai-bedrock-agentcore/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spring-ai-community%2Fspring-ai-bedrock-agentcore/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/spring-ai-community","download_url":"https://codeload.github.com/spring-ai-community/spring-ai-bedrock-agentcore/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spring-ai-community%2Fspring-ai-bedrock-agentcore/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28337590,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-12T06:09:07.588Z","status":"ssl_error","status_checked_at":"2026-01-12T06:05:18.301Z","response_time":98,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentcore","ai","aws","bedrock","spring"],"created_at":"2026-01-12T08:20:29.705Z","updated_at":"2026-01-12T08:20:31.944Z","avatar_url":"https://github.com/spring-ai-community.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Spring AI Bedrock AgentCore\n\nA Spring Boot starter that enables existing Spring Boot applications to conform to the AWS Bedrock AgentCore Runtime contract with minimal configuration.\n\n## Features\n\n- **Auto-configuration**: Automatically sets up AgentCore endpoints when added as dependency\n- **Annotation-based**: Simple `@AgentCoreInvocation` annotation to mark agent methods\n- **SSE Streaming**: Server-Sent Events support with `Flux\u003cString\u003e` return types\n- **Smart health checks**: Built-in `/ping` endpoint with Spring Boot Actuator integration\n- **Async task tracking**: Convenient methods for background task tracking\n- **Rate limiting**: Built-in Bucket4j throttling for invocations and ping endpoints\n\n## Quick Start\n\n### 1. Add Dependency\n\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003eorg.springaicommunity\u003c/groupId\u003e\n    \u003cartifactId\u003espring-ai-bedrock-agentcore-starter\u003c/artifactId\u003e\n    \u003cversion\u003e1.0.0-RC2\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n### 2. Create Agent Method\n\n```java\n@Service\npublic class MyAgentService {\n    \n    @AgentCoreInvocation\n    public String handleUserPrompt(MyRequest request) {\n        return \"You said: \" + request.prompt;\n    }\n}\n```\n\n### 3. Run Application\n\nThe application will automatically expose:\n- `POST /invocations` - Agent processing endpoint\n- `GET /ping` - Health check endpoint\n\n## Supported Method Signatures\n\n### Basic POJO Method\n```java\n@AgentCoreInvocation\npublic MyResponse processRequest(MyRequest request) {\n    return new MyResponse(\"Processed: \" + request.prompt());\n}\n\nrecord MyRequest(String prompt) {}\nrecord MyResponse(String message) {}\n```\n\n### With AgentCore Context\n```java\n@AgentCoreInvocation\npublic MyResponse processWithContext(MyRequest request, AgentCoreContext context) {\n    var sessionId = context.getHeader(AgentCoreHeaders.SESSION_ID);\n    return new MyResponse(\"Session \" + sessionId + \": \" + request.prompt());\n}\n```\n\n### Map Method (Flexible)\n```java\n@AgentCoreInvocation\npublic Map\u003cString, Object\u003e processData(Map\u003cString, Object\u003e data) {\n    return Map.of(\n        \"input\", data,\n        \"response\", \"Processed: \" + data.get(\"message\"),\n        \"timestamp\", System.currentTimeMillis()\n    );\n}\n```\n\n### String Method (text/plain support)\n```java\n@AgentCoreInvocation\npublic String handlePrompt(String prompt) {\n    return \"Response: \" + prompt;\n}\n```\n\n### SSE Streaming with Spring AI\n```java\n@AgentCoreInvocation\npublic Flux\u003cString\u003e streamingAgent(String prompt) {\n    return chatClient.prompt().user(prompt).stream().content();\n}\n```\n\n## Configuration\n\nThe starter uses fixed configuration per AgentCore contract:\n- **Port**: 8080 (required by AgentCore)\n- **Endpoints**: `/invocations`, `/ping` (fixed paths)\n- **Health Integration**: Automatically integrates with Spring Boot Actuator when available\n\n### Health Monitoring\n\nThe `/ping` endpoint provides intelligent health monitoring:\n\n**Without Spring Boot Actuator:**\n- Returns static \"Healthy\" status\n- Always responds with HTTP 200\n\n**With Spring Boot Actuator:**\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003eorg.springframework.boot\u003c/groupId\u003e\n    \u003cartifactId\u003espring-boot-starter-actuator\u003c/artifactId\u003e\n\u003c/dependency\u003e\n```\n- Integrates with Actuator health checks\n- Maps Actuator status to AgentCore format:\n    - `UP` → \"Healthy\" (HTTP 200)\n    - `DOWN` → \"Unhealthy\" (HTTP 503)\n    - Other → \"Unknown\" (HTTP 503)\n- Tracks status change timestamps\n- Thread-safe concurrent access\n\n### Background Task Tracking\n\nAWS Bedrock AgentCore Runtime monitors agent health and may shut down agents that appear idle. When your agent starts long-running background tasks (like file processing, data analysis, or calling other long-running agents), the runtime needs to know the agent is still actively working to avoid premature termination.\n\nThe starter includes `AgentCoreTaskTracker` to communicate this state to the runtime:\n\n```java\n@AgentCoreInvocation\npublic String asyncTaskHandling(MyRequest request, AgentCoreContext context) {\n    agentCoreTaskTracker.increment();  // Tell runtime: \"I'm starting background work\"\n    \n    CompletableFuture.runAsync(() -\u003e {\n        // Long-running background work\n    }).thenRun(agentCoreTaskTracker::decrement);  // Tell runtime: \"Background work completed\"\n    \n    return \"Task started\";\n}\n```\n\nThe '/ping' endpoint will return **HealthyBusy** while the AgentCoreTaskTracker is greater than 0.\n\n**How the Runtime Uses This Information:**\n- **\"Healthy\"**: Agent is ready, no background tasks → Runtime may scale down if idle\n- **\"HealthyBusy\"**: Agent is healthy but actively processing → Runtime keeps agent alive\n- **\"Unhealthy\"**: Agent has issues → Runtime may restart or replace agent\n\nThis prevents the runtime from shutting down your agent while it's processing important background work.\n\nNo additional configuration is required.\n\n### Rate Limiting\n\nThe starter includes built-in rate limiting using Bucket4j to protect against excessive requests. Rate limiting is deactivated by default and will be active only if limits are defined in properties.\n\n**Configuration:**\n```properties\n# Customize rate limits in requests per minute (optional)\nagentcore.throttle.invocations-limit=50\nagentcore.throttle.ping-limit=200\n```\n\n**Rate Limit Response (429):**\n```json\n{\"error\":\"Rate limit exceeded\"}\n```\n\nRate limits are applied per client IP address and reset every minute.\n\n## API Reference\n\n### POST /invocations\n\n**Request (defined by user):**\n```json\n{\n  \"prompt\": \"Your prompt here\"\n}\n```\n\n**Success Response (200) (defined by user):**\n```json\n{\n  \"response\": \"Agent response\",\n  \"status\": \"success\"\n}\n```\n\n### GET /ping\n\n**Response (200):**\n```json\n{\n  \"status\": \"Healthy\",\n  \"time_of_last_update\": 1697123456\n}\n```\n\n**Response (503) - When Actuator detects issues:**\n```json\n{\n  \"status\": \"Unhealthy\", \n  \"time_of_last_update\": 1697123456\n}\n```\n\n## Custom Controller Override\n\nThe starter provides marker interfaces to override the default auto-configured controllers with custom implementations:\n\n### Override Invocations Controller\n\nImplement `AgentCoreInvocationsHandler` to provide custom `/invocations` endpoint handling:\n\n```java\n@RestController\npublic class CustomInvocationsController implements AgentCoreInvocationsHandler {\n    \n    @PostMapping(\"/invocations\")\n    public ResponseEntity\u003c?\u003e handleInvocations(@RequestBody String request) {\n        // Custom invocation logic\n        return ResponseEntity.ok(\"Custom response\");\n    }\n}\n```\n\n### Override Ping Controller\n\nImplement `AgentCorePingHandler` to provide custom `/ping` endpoint handling:\n\n```java\n@RestController\npublic class CustomPingController implements AgentCorePingHandler {\n    \n    @GetMapping(\"/ping\")\n    public ResponseEntity\u003c?\u003e ping() {\n        // Custom health check logic\n        return ResponseEntity.ok(Map.of(\"status\", \"Custom Healthy\"));\n    }\n}\n```\n\nWhen these marker interfaces are implemented, the corresponding auto-configured controllers are automatically disabled.\n\nSee `examples/spring-ai-override-invocations/` for a complete working example.\n\n## Examples\n\nSee the `examples/` directory for complete working examples:\n\n- **`simple-spring-boot-app/`** - Minimal AgentCore agent with async task tracking\n- **`spring-ai-sse-chat-client/`** - SSE streaming with Spring AI and Amazon Bedrock\n- **`spring-ai-simple-chat-client/`** - Traditional Spring AI integration (without AgentCore starter)\n- **`spring-ai-override-invocations/`** - Custom controller override using marker interfaces\n\n## Requirements\n\n- Java 17+\n- Spring Boot 3.x\n- Maven or Gradle\n\n## License\n\nThis project is licensed under the Apache License 2.0.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspring-ai-community%2Fspring-ai-bedrock-agentcore","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fspring-ai-community%2Fspring-ai-bedrock-agentcore","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspring-ai-community%2Fspring-ai-bedrock-agentcore/lists"}