Forem: Yuriy Bezsonov

AI Agent Memory Made Easy - Amazon Bedrock AgentCore Memory with Spring AI

Yuriy Bezsonov — Tue, 03 Feb 2026 08:38:10 +0000

What if your AI agent could remember not just the current conversation, but facts about users across sessions? A few months ago, I built a custom three-tier memory system with PostgreSQL, Testcontainers, and AI-powered summarization. It worked, but required significant code and infrastructure.

Now there's a simpler way. The Spring AI Amazon Bedrock AgentCore starter I've been contributing to integrates with Amazon Bedrock AgentCore Memory - a fully managed service that handles both short-term conversation history and long-term knowledge extraction for you.

In this post, I'll show you how to build an AI agent with persistent memory in under 50 lines of Java using JBang - no Maven project setup required. Your agent will remember previous messages and automatically extract facts from conversations - all without managing a database.

Why Amazon Bedrock AgentCore Memory?

AI models are stateless - ask "What's my name?" after introducing yourself, and the model has no idea. AgentCore Memory solves this with:

Fully Managed: AWS handles storage, extraction, and retention. No Redis or PostgreSQL to configure for memory.
Two Memory Types: Short-term for conversation context, long-term for extracted facts and preferences.
Auto-Extraction: Long-term memory runs asynchronously - it automatically extracts semantic facts, user preferences, and summaries from conversations.

Short-Term Memory (STM):

Stores raw conversation events within sessions
Maintains context for multi-turn conversations
Enables conversation continuation even after service restarts

Long-Term Memory (LTM) Strategies:

Strategy	Purpose	Example
Semantic	Extracts factual information	"User lives in Berlin"
UserPreference	Identifies preferences and choices	"Prefers eco-friendly travel"
Summary	Generates conversation summaries	"Discussed trip planning to Vegas"
Episodic	Captures meaningful interaction slices	"User booked flight on March 15"

Custom vs Managed: A Comparison

Here's what I had to build for custom memory vs what Amazon Bedrock AgentCore Memory provides out of the box:

Aspect	Custom Implementation	AgentCore Memory
Infrastructure	PostgreSQL + Testcontainers setup	None - fully managed
Session Memory	`MessageWindowChatMemory` + JDBC repository	Auto-configured from environment
Long-Term Extraction	Custom `ConversationSummaryService` with AI prompts	Automatic - runs asynchronously
Preferences Storage	Custom tier with manual extraction logic	Built-in UserPreference strategy
Summarization	Custom prompts parsing `===PREFERENCES===` sections	Built-in Summary strategy
Code Required	~300 lines across multiple services	~50 lines total
Database Management	Schema migrations, connection pooling	None
Scaling	Manual PostgreSQL scaling	Managed by AWS

The custom approach gives you full control and works without AWS dependencies. But if you're already on AWS and want to move fast, Amazon Bedrock AgentCore Memory handles the infrastructure so you can focus on what your agent actually does.

Prerequisites

You'll need:

Java 21+ (Amazon Corretto 21)
AWS CLI configured with Amazon Bedrock AgentCore access
JBang installed

AWS Credentials

Configure AWS CLI with credentials that have Amazon Bedrock AgentCore access:

aws configure

Verify access:

aws bedrock-agentcore-control list-memories --no-cli-pager --query 'memories[0].id' --output text

Create the Memory Resource

Let's create an Amazon Bedrock AgentCore Memory resource with LTM strategies. Copy and run in terminal:

# Create memory resource
MEMORY_ID=$(aws bedrock-agentcore-control create-memory \
  --name "memory_demo" --description "Memory for AI Agent demo" \
  --event-expiry-duration 90 --no-cli-pager \
  --query "memory.id" --output text) && echo "Memory ID: ${MEMORY_ID}"

# Wait for memory to become active
echo -n "Waiting for memory to become active..."
while [ "$(aws bedrock-agentcore-control get-memory --memory-id ${MEMORY_ID} \
  --no-cli-pager --query 'memory.status' --output text)" != "ACTIVE" ]
do echo -n "."; sleep 5; done && echo " ACTIVE"

# Add LTM strategies
aws bedrock-agentcore-control update-memory \
  --memory-id "${MEMORY_ID}" --no-cli-pager \
  --memory-strategies '{
    "addMemoryStrategies": [
      {"semanticMemoryStrategy": {"name": "SemanticFacts", "description": "Extracts factual information", "namespaces": ["/strategies/{memoryStrategyId}/actors/{actorId}"]}},
      {"userPreferenceMemoryStrategy": {"name": "UserPreferences", "description": "Extracts user preferences", "namespaces": ["/strategies/{memoryStrategyId}/actors/{actorId}"]}}
    ]
  }'

# Wait for strategies to become active
echo -n "Waiting for strategies to become active..."
while aws bedrock-agentcore-control get-memory --memory-id ${MEMORY_ID} \
  --no-cli-pager --query 'memory.strategies[].status' --output text | grep -q "CREATING"
do echo -n "."; sleep 5; done && echo " ACTIVE"

# Get strategy IDs
SEMANTIC_ID=$(aws bedrock-agentcore-control get-memory \
  --memory-id "${MEMORY_ID}" --no-cli-pager \
  --query "memory.strategies[?name=='SemanticFacts'].strategyId | [0]" --output text)

PREFS_ID=$(aws bedrock-agentcore-control get-memory \
  --memory-id "${MEMORY_ID}" --no-cli-pager \
  --query "memory.strategies[?name=='UserPreferences'].strategyId | [0]" --output text)

echo "Memory ID: ${MEMORY_ID}"
echo "Semantic Strategy ID: ${SEMANTIC_ID}"
echo "Preferences Strategy ID: ${PREFS_ID}"

This creates:

Amazon Bedrock AgentCore Memory resource with 90-day event retention
Semantic strategy for extracting facts from conversations
UserPreference strategy for identifying user preferences

The memory resource takes 2-5 minutes to become active.

The Application

Here's the complete AI agent with memory - under 50 lines of Java:

cat <<'EOF' > MemoryAgent.java
///usr/bin/env jbang "$0" "$@" ; exit $?
//DEPS org.springframework.boot:spring-boot-starter-web:3.5.9
//DEPS org.springframework.ai:spring-ai-starter-model-bedrock-converse:1.1.2
//DEPS org.springaicommunity:spring-ai-memory-bedrock-agentcore:1.0.0-RC5

//JAVA_OPTIONS -Dspring.ai.bedrock.aws.region=us-east-1
//JAVA_OPTIONS -Dspring.ai.bedrock.converse.chat.options.model=global.anthropic.claude-sonnet-4-20250514-v1:0

package com.example;

import org.springframework.ai.chat.client.ChatClient;
import org.springframework.ai.chat.client.advisor.MessageChatMemoryAdvisor;
import org.springframework.ai.chat.client.advisor.api.Advisor;
import org.springframework.ai.chat.memory.*;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.bind.annotation.*;
import java.util.*;

@SpringBootApplication
@RestController
public class MemoryAgent {

    private final ChatClient chatClient;

    public MemoryAgent(ChatClient.Builder builder,
                       @Autowired(required = false) ChatMemoryRepository memoryRepository,
                       @Autowired(required = false) List<Advisor> ltmAdvisors) {
        List<Advisor> advisors = new ArrayList<>();
        if (memoryRepository != null) {
            advisors.add(MessageChatMemoryAdvisor.builder(
                MessageWindowChatMemory.builder().chatMemoryRepository(memoryRepository).build()
            ).build());
        }
        if (ltmAdvisors != null) advisors.addAll(ltmAdvisors);
        this.chatClient = builder.defaultAdvisors(advisors.toArray(new Advisor[0])).build();
    }

    @PostMapping("/chat")
    public String chat(@RequestBody String prompt,
                       @RequestHeader(value = "X-Session-Id", defaultValue = "default") String sessionId) {
        return chatClient.prompt().user(prompt)
            .advisors(a -> a.param(ChatMemory.CONVERSATION_ID, sessionId))
            .call().content();
    }

    public static void main(String[] args) { SpringApplication.run(MemoryAgent.class, args); }
}
EOF

The JBang header declares dependencies, Spring AI auto-configures memory beans from environment variables, and the advisors handle both STM and LTM automatically.

Run the Application

Export the environment variables from the setup step, then run:

export AGENTCORE_MEMORY_MEMORY_ID=${MEMORY_ID}
export AGENTCORE_MEMORY_LONG_TERM_SEMANTIC_STRATEGY_ID=${SEMANTIC_ID}
export AGENTCORE_MEMORY_LONG_TERM_USER_PREFERENCE_STRATEGY_ID=${PREFS_ID}

jbang MemoryAgent.java

JBang downloads dependencies on first run, then starts the Spring Boot application.

Test the Application

In another terminal, test conversation memory:

# First message - introduce yourself
echo "User: Hi, my name is Alex and I live in Berlin"
echo -n "Assistant: "; curl -s -X POST http://localhost:8080/chat \
  -H "Content-Type: text/plain" \
  -H "X-Session-Id: user123" \
  -d "Hi, my name is Alex and I live in Berlin"; echo -e "\n"

# Second message - ask about yourself
echo "User: What's my name and where do I live?"
echo -n "Assistant: "; curl -s -X POST http://localhost:8080/chat \
  -H "Content-Type: text/plain" \
  -H "X-Session-Id: user123" \
  -d "What's my name and where do I live?"; echo

Expected output:

User: Hi, my name is Alex and I live in Berlin
Assistant: Hello Alex! Nice to meet you. Berlin is a wonderful city...

User: What's my name and where do I live?
Assistant: Your name is Alex and you live in Berlin.

The agent remembers your name and location from the previous message. Long-term memory will extract "User's name is Alex" and "User lives in Berlin" as semantic facts for future sessions.

Test Long-Term Memory

Wait a few minutes for LTM extraction, then start a new session:

# New session - agent should remember facts from LTM
echo "User: Do you know anything about me?"
echo -n "Assistant: "; curl -s -X POST http://localhost:8080/chat \
  -H "Content-Type: text/plain" \
  -H "X-Session-Id: user123" \
  -d "Do you know anything about me?"; echo

The agent retrieves extracted facts from long-term memory.

Cleanup

MEMORY_ID=$(aws bedrock-agentcore-control list-memories \
  --query "memories[?starts_with(id, 'memory_demo')].id | [0]" \
  --output text --no-cli-pager) && echo "MEMORY_ID: ${MEMORY_ID}"

[ "${MEMORY_ID}" != "None" ] && aws bedrock-agentcore-control delete-memory \
  --memory-id ${MEMORY_ID} --no-cli-pager

Going Further

This demo uses semantic and preference strategies. AgentCore Memory also supports Summary and Episodic strategies, custom namespaces, and retention policies.

Memory pairs well with RAG - memory handles personal context while RAG provides domain knowledge. Check out my post on Amazon Bedrock Knowledge Base to add RAG to the same agent.

Conclusion

One Java file, a few shell commands, and you have persistent memory with automatic fact extraction. No database to manage, no extraction pipelines to build. The same code works in any Maven or Gradle project - JBang just keeps the demo simple.

I'm excited to contribute to the Spring AI Amazon Bedrock AgentCore starter that makes this integration possible. The source is on GitHub if you want to see how it works.

Learn More

Spring AI Amazon Bedrock AgentCore Starter
Amazon Bedrock AgentCore Memory Documentation
Custom Memory Implementation with PostgreSQL - My previous post on building memory from scratch

RAG Made Serverless - Amazon Bedrock Knowledge Base with Spring AI

Yuriy Bezsonov — Tue, 27 Jan 2026 07:32:46 +0000

What if you could build an AI assistant with access to your own data in under 40 lines of Java? That's now possible with my contribution to the just-released Spring AI 2.0.0 M2 - Amazon Bedrock Knowledge Base support. It's a fully managed RAG (Retrieval-Augmented Generation) service that handles document ingestion, embeddings, and vector storage for you - and now you can use it with Spring AI!
RAG lets AI models answer questions using your own documents instead of relying solely on their training data.

In this post, I'll show you how to build a working AI agent with RAG in minutes using JBang - no Maven project setup required. You'll have an AI assistant answering questions from your company documents with minimal code.

Why Bedrock Knowledge Base?

Three things make this integration compelling:

Fully Managed: AWS handles document chunking, embeddings, and vector storage. No PGVector or OpenSearch to manage.
Read-Only from Spring AI: Documents sync via AWS - your app just queries. Simple.
Fast Setup: Connect S3, Confluence, or SharePoint as data sources. Sync and go.

Key features:

Search Types: SEMANTIC uses vector similarity; HYBRID combines semantic with keyword search for better recall
Reranking: Re-scores results using Bedrock reranking models to surface the most relevant documents
Metadata Filtering: Narrows results by document attributes (e.g., department == 'HR' && year >= 2024)
Similarity Threshold: Filters out low-relevance matches below a minimum score

For full configuration options, see the Spring AI Bedrock Knowledge Base documentation.

Prerequisites

You'll need:

Java 21+ (Amazon Corretto 21)
AWS CLI configured with Bedrock access
JBang installed

What is JBang?

JBang lets you run Java files directly - no pom.xml, no project structure. Perfect for quick experiments and demos. Dependencies are declared as comments in the source file.

Install JBang:

# macOS
brew install jbang

# Linux/Windows
curl -Ls https://sh.jbang.dev | bash -s - app setup

AWS Credentials

Configure AWS CLI with credentials that have Bedrock access:

aws configure

Verify access:

aws bedrock list-foundation-models --query 'modelSummaries[0].modelId' --output text

The Knowledge Base

Let's create a Knowledge Base with sample company policies. Copy and run in terminal:

ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text --no-cli-pager)
BUCKET="kb-demo-${ACCOUNT_ID}"
VECTOR_BUCKET="kb-demo-vectors-${ACCOUNT_ID}"

# Buckets
aws s3 mb s3://${BUCKET} --no-cli-pager 2>/dev/null || true
aws s3vectors create-vector-bucket --vector-bucket-name ${VECTOR_BUCKET} --no-cli-pager 2>/dev/null || true
aws s3vectors create-index --vector-bucket-name ${VECTOR_BUCKET} --index-name kb-demo-index \
  --data-type float32 --dimension 1024 --distance-metric cosine --no-cli-pager 2>/dev/null || true

# Sample policies
echo "Travel: Europe accommodation €130/night. Manager approval required." | aws s3 cp - s3://${BUCKET}/travel.txt --no-cli-pager
echo "IT: Home office budget \$500/year. VPN required for remote work." | aws s3 cp - s3://${BUCKET}/it.txt --no-cli-pager

# IAM role
aws iam create-role --role-name kb-demo-role --no-cli-pager \
  --assume-role-policy-document '{"Version":"2012-10-17","Statement":[{"Effect":"Allow","Principal":{"Service":"bedrock.amazonaws.com"},"Action":"sts:AssumeRole"}]}' 2>/dev/null || true
aws iam attach-role-policy --role-name kb-demo-role --policy-arn arn:aws:iam::aws:policy/AmazonS3ReadOnlyAccess --no-cli-pager 2>/dev/null || true
aws iam attach-role-policy --role-name kb-demo-role --policy-arn arn:aws:iam::aws:policy/AmazonBedrockFullAccess --no-cli-pager 2>/dev/null || true
aws iam put-role-policy --role-name kb-demo-role --policy-name s3vectors \
  --policy-document "{\"Version\":\"2012-10-17\",\"Statement\":[{\"Effect\":\"Allow\",\"Action\":\"s3vectors:*\",\"Resource\":\"arn:aws:s3vectors:us-east-1:${ACCOUNT_ID}:bucket/${VECTOR_BUCKET}/*\"}]}" --no-cli-pager
sleep 10

# Knowledge Base
KB_ID=$(aws bedrock-agent create-knowledge-base --name kb-demo --role-arn arn:aws:iam::${ACCOUNT_ID}:role/kb-demo-role \
  --knowledge-base-configuration '{"type":"VECTOR","vectorKnowledgeBaseConfiguration":{"embeddingModelArn":"arn:aws:bedrock:us-east-1::foundation-model/amazon.titan-embed-text-v2:0"}}' \
  --storage-configuration "{\"type\":\"S3_VECTORS\",\"s3VectorsConfiguration\":{\"vectorBucketArn\":\"arn:aws:s3vectors:us-east-1:${ACCOUNT_ID}:bucket/${VECTOR_BUCKET}\",\"indexName\":\"kb-demo-index\"}}" \
  --no-cli-pager --query 'knowledgeBase.knowledgeBaseId' --output text)

sleep 30
DS_ID=$(aws bedrock-agent create-data-source --knowledge-base-id ${KB_ID} --name policies \
  --data-source-configuration "{\"type\":\"S3\",\"s3Configuration\":{\"bucketArn\":\"arn:aws:s3:::${BUCKET}\"}}" \
  --no-cli-pager --query 'dataSource.dataSourceId' --output text)

aws bedrock-agent start-ingestion-job --knowledge-base-id ${KB_ID} --data-source-id ${DS_ID} --no-cli-pager >/dev/null
echo "KB: ${KB_ID}"

This creates:

S3 bucket with two policy documents
S3 Vectors bucket for vector storage
IAM role for Bedrock to access your data
Knowledge Base with Titan embeddings
Data source pointing to your S3 bucket

The script uses S3 Vectors - a cost-effective serverless vector storage option. You can also use OpenSearch Serverless or Aurora PostgreSQL.

The Application

Here's the complete AI agent - 40 lines of Java. Save as KbAgent.java:

///usr/bin/env jbang "$0" "$@" ; exit $?
//DEPS org.springframework.boot:spring-boot-starter-web:4.0.1
//DEPS org.springframework.ai:spring-ai-starter-model-bedrock-converse:2.0.0-M2
//DEPS org.springframework.ai:spring-ai-starter-vector-store-bedrock-knowledgebase:2.0.0-M2
//DEPS org.springframework.ai:spring-ai-advisors-vector-store:2.0.0-M2

//JAVA_OPTIONS -Dspring.ai.bedrock.aws.region=us-east-1
//JAVA_OPTIONS -Dspring.ai.bedrock.converse.chat.options.model=global.anthropic.claude-sonnet-4-20250514-v1:0

package com.example;

import org.springframework.ai.chat.client.ChatClient;
import org.springframework.ai.chat.client.advisor.vectorstore.QuestionAnswerAdvisor;
import org.springframework.ai.vectorstore.VectorStore;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.bind.annotation.*;

@SpringBootApplication
@RestController
public class KbAgent {

    private final ChatClient chatClient;

    public KbAgent(ChatClient.Builder builder, VectorStore vectorStore) {
        this.chatClient = builder
                .defaultAdvisors(QuestionAnswerAdvisor.builder(vectorStore).build())
                .build();
    }

    @PostMapping("/chat")
    public String chat(@RequestBody String prompt) {
        return chatClient.prompt().user(prompt).call().content();
    }

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

That's it. The JBang header declares dependencies, Spring AI auto-configures the VectorStore bean from the environment variable, and QuestionAnswerAdvisor handles RAG automatically.

Key Points

No EmbeddingModel needed: Unlike PGVector, Bedrock KB handles embeddings internally. If you'd like to build RAG with PostgreSQL and PGVector instead, check out my previous post.
Auto-configuration: Just set SPRING_AI_VECTORSTORE_BEDROCK_KNOWLEDGE_BASE_KNOWLEDGE_BASE_ID
QuestionAnswerAdvisor: Automatically retrieves relevant documents and adds them to the prompt

Run the Application

KB_ID=$(aws bedrock-agent list-knowledge-bases --query "knowledgeBaseSummaries[?name=='kb-demo'].knowledgeBaseId|[0]" --output text --no-cli-pager)
echo "KB: ${KB_ID}"
SPRING_AI_VECTORSTORE_BEDROCK_KNOWLEDGE_BASE_KNOWLEDGE_BASE_ID=${KB_ID} jbang KbAgent.java

JBang downloads dependencies on first run, then starts the Spring Boot application.

Test the Application

In another terminal:

# Test travel policy
curl -s -X POST http://localhost:8080/chat -H "Content-Type: text/plain" \
  -d "What is the accommodation limit for Europe?"

# Test IT policy
curl -s -X POST http://localhost:8080/chat -H "Content-Type: text/plain" \
  -d "What is the home office equipment budget?"

Expected output:

Based on the context information provided, the accommodation limit for Europe is €130 per night, and manager approval is required.

Based on the context information provided, the home office equipment budget is **$500 per year**.

The AI responds with information from your company documents - not generic training data.

Cleanup

ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text --no-cli-pager)
KB_ID=$(aws bedrock-agent list-knowledge-bases --query "knowledgeBaseSummaries[?name=='kb-demo'].knowledgeBaseId|[0]" --output text --no-cli-pager)

[ "${KB_ID}" != "None" ] && aws bedrock-agent delete-knowledge-base --knowledge-base-id ${KB_ID} --no-cli-pager 2>/dev/null
aws s3 rb s3://kb-demo-${ACCOUNT_ID} --force --no-cli-pager 2>/dev/null
aws s3vectors delete-index --vector-bucket-name kb-demo-vectors-${ACCOUNT_ID} --index-name kb-demo-index --no-cli-pager 2>/dev/null
aws s3vectors delete-vector-bucket --vector-bucket-name kb-demo-vectors-${ACCOUNT_ID} --no-cli-pager 2>/dev/null
aws iam delete-role-policy --role-name kb-demo-role --policy-name s3vectors --no-cli-pager 2>/dev/null
aws iam detach-role-policy --role-name kb-demo-role --policy-arn arn:aws:iam::aws:policy/AmazonS3ReadOnlyAccess --no-cli-pager 2>/dev/null
aws iam detach-role-policy --role-name kb-demo-role --policy-arn arn:aws:iam::aws:policy/AmazonBedrockFullAccess --no-cli-pager 2>/dev/null
aws iam delete-role --role-name kb-demo-role --no-cli-pager 2>/dev/null

What's Next?

This demo uses S3 with text files, but Bedrock Knowledge Base supports:

Multiple data sources: Confluence, SharePoint, Salesforce, web crawlers
Advanced search: Hybrid search combining semantic and keyword matching
Reranking: Improve relevance with Bedrock reranking models
Metadata filtering: Filter results by document attributes

See the Spring AI documentation for configuration options.

Conclusion

With minimal setup - one Java file and a few shell commands - you have an AI assistant grounded in your own data. No vector database to manage, no embedding pipeline to build.

I'm proud to have contributed this integration to Spring AI 2.0.0 M2. The source is available on GitHub if you want to see how it works under the hood.

Learn More

Modern Java Observability in 2026 - Spring Boot 4 on Amazon EKS

Yuriy Bezsonov — Tue, 13 Jan 2026 07:21:29 +0000

If you're running Spring Boot applications on Kubernetes, you've probably hit the same wall I did: containers restart, logs disappear, and when something goes wrong or slows down, you're left guessing which microservice caused the issue.

Two recent developments prompted me to revisit my observability setup. First, the OpenTelemetry Java Agent v2.0 (January 2024) shifted from "instrument everything automatically" to "explicit over implicit" - requiring adjustments to maintain visibility into business logic. Second, Spring Boot 4.0 (November 2025) introduced the new spring-boot-starter-opentelemetry, making it easier than ever to export metrics, traces, and logs via OpenTelemetry Protocol (OTLP).

In this post, I'll walk you through setting up observability for Spring Boot applications on Amazon EKS - starting with the basics (logs and metrics), diving into distributed tracing, and finishing with Application Signals. Hopefully this saves you some time.

Overview of the Solution

The Three Pillars

Quick refresher on the three pillars of observability:

Logs: Discrete events with timestamps and context
Metrics: Numerical measurements aggregated over time
Traces: Request flows across service boundaries

Each answers different questions. Logs tell you what happened. Metrics tell you how much and how often. Traces tell you where time was spent across services.

AWS Services for Observability

Here's the AWS stack I'm using:

Service	Purpose
CloudWatch Logs	Centralized log aggregation and search
CloudWatch Container Insights	Infrastructure metrics for EKS
AWS X-Ray	Distributed tracing and service maps
Application Signals	Application Performance Monitoring (APM) dashboards and Service Level Objectives (SLOs)

Architecture Overview

┌─────────────────────────────────────────────────────────────────────┐
│                           EKS Cluster                               │
│  ┌─────────────────┐     ┌──────────────────────────────────────┐   │
│  │  Java App Pod   │     │  CloudWatch Observability Add-on     │   │
│  │  + ADOT Agent   │────▶│  - Fluent Bit (logs)                 │   │
│  │                 │     │  - CloudWatch Agent (metrics/traces) │   │
│  └─────────────────┘     └──────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────┘
                                      │
                    ┌─────────────────┼─────────────────┐
                    ▼                 ▼                 ▼
             CloudWatch Logs      X-Ray         Application Signals

The AWS Distro for OpenTelemetry (ADOT) agent runs inside your application container, collecting telemetry and sending it to the CloudWatch Observability add-on. From there, data flows to the appropriate AWS services.

Why I Chose ADOT Over Community OpenTelemetry

Feature	Community Agent	ADOT Agent
X-Ray trace ID format	✗	✓
AWS resource detection	Basic	Enhanced
Application Signals	✗	✓

I tried the community agent first, but the X-Ray integration was complicated. ADOT just works - it's AWS-supported and adds the features I actually need.

The Foundation: Logs and Metrics

Setting up logs and metrics on EKS is the easy part. The CloudWatch Observability add-on handles everything:

Fluent Bit as a DaemonSet for log collection
CloudWatch agent for metrics and trace forwarding

Quick Setup

One command:

aws eks create-addon \
  --cluster-name your-cluster \
  --addon-name amazon-cloudwatch-observability \
  --no-cli-pager

That's it. Fluent Bit automatically collects container logs from /var/log/containers/ and sends them to CloudWatch Logs. The CloudWatch agent collects infrastructure metrics and exposes them in Container Insights.

What You Get

Logs appear in CloudWatch under /aws/containerinsights/{cluster-name}/application. Container Insights gives you dashboards showing CPU, memory, network, and disk metrics per pod, node, and namespace.

For Java applications, this foundation is necessary but not sufficient. You can see that your pods are running and consuming resources, but you can't see inside the Java Virtual Machine (JVM) or trace requests across services. That's where things get interesting.

Deep Dive: Distributed Tracing

This is where I spent most of my time. Distributed tracing tracks requests as they flow through microservices - essential for debugging latency issues and understanding dependencies.

The OpenTelemetry v2 Changes

In January 2024, OpenTelemetry Java Agent v2.0 introduced significant changes:

Change	Before (v1)	After (v2)
Controller spans	Enabled	Disabled by default
View spans	Enabled	Disabled by default
Micrometer bridge	Enabled	Disabled by default
OTLP protocol	gRPC	HTTP/protobuf

The philosophy shifted from "capture everything" to "opt-in for extras." This reduces noise and overhead, but means you need to explicitly enable features you relied on before. If you upgraded and noticed spans disappeared, this is why.

What Spring Boot 4 Brings

Spring Boot 4.0 introduced spring-boot-starter-opentelemetry with several benefits:

Native OTLP export for metrics, traces, and logs without additional dependencies
Seamless bridge between Micrometer observations and OpenTelemetry spans
Auto-configuration for OpenTelemetry SDK components
Support for W3C trace context propagation out of the box

This means @Observed annotations now create both Micrometer metrics and OpenTelemetry spans automatically - no manual bridging required.

The Hybrid Solution

Here's what I landed on - combining ADOT auto-instrumentation with manual @Observed annotations:

What ADOT auto-instruments (no code changes needed):

HTTP clients and servers (Spring MVC, JAX-RS)
Database clients (JDBC, Hibernate)
Messaging systems (Kafka, SQS)
AWS SDK calls (EventBridge, S3, DynamoDB)

What I had to add manually:

Internal @Service methods (business logic)
Custom spans for specific operations

Understanding Spring's Observability Stack

To make @Observed annotations work, you need to understand three components that work together:

Micrometer Observation API - A unified API that creates both metrics and traces from a single instrumentation point. When you annotate a method with @Observed, the Observation API records:

A timer metric (how long the method took)
A trace span (for distributed tracing)

This means one annotation gives you both a Prometheus metric like unicorn.create.duration and a trace span visible in X-Ray - no need to instrument twice.

Micrometer Tracing - The bridge that connects observations to tracing backends. It takes the spans created by the Observation API and exports them via OpenTelemetry (or other formats like Zipkin). Spring Boot 4's spring-boot-starter-opentelemetry auto-configures this bridge, so spans flow to your OTLP endpoint without manual wiring.

AspectJ weaving - The mechanism that intercepts @Observed method calls at runtime. When your code calls an @Observed method, AspectJ wraps the call to:

Start a timer and create a span before the method executes
Record the duration and close the span after the method completes
Capture exceptions if the method fails

Without AspectJ, the @Observed annotation is just metadata sitting on your method - nothing actually captures timing or creates spans.

Enabling @Observed Annotations

Add these dependencies to your pom.xml:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-opentelemetry</artifactId>
</dependency>
<dependency>
    <groupId>org.aspectj</groupId>
    <artifactId>aspectjweaver</artifactId>
</dependency>

Then annotate your business logic methods:

@Observed(name = "unicorn.create")
@Transactional
public Unicorn createUnicorn(Unicorn unicorn) {
    // Business logic - now traced!
}

This gives you both a Prometheus metric (unicorn.create.duration) and an X-Ray span from a single annotation.

Dockerfile Configuration

Here's the Dockerfile configuration I use:

FROM public.ecr.aws/docker/library/amazoncorretto:21-al2023

# Download ADOT agent
ADD https://github.com/aws-observability/aws-otel-java-instrumentation/releases/latest/download/aws-opentelemetry-agent.jar /opt/aws-opentelemetry-agent.jar

# Attach agent to JVM
ENV JAVA_TOOL_OPTIONS="-javaagent:/opt/aws-opentelemetry-agent.jar"

# OTLP configuration
ENV OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
ENV OTEL_METRICS_EXPORTER="none"
ENV OTEL_LOGS_EXPORTER="none"

# Traces configuration
ENV OTEL_TRACES_SAMPLER="always_on"
ENV OTEL_PROPAGATORS="tracecontext,baggage,xray"
ENV OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="http://cloudwatch-agent.amazon-cloudwatch:4316/v1/traces"

# Application Signals
ENV OTEL_AWS_APPLICATION_SIGNALS_ENABLED="true"
ENV OTEL_AWS_APPLICATION_SIGNALS_EXPORTER_ENDPOINT="http://cloudwatch-agent.amazon-cloudwatch:4316/v1/metrics"

COPY app.jar /app.jar
ENTRYPOINT ["java", "-jar", "/app.jar"]

Why these specific settings:

OTEL_METRICS_EXPORTER=none: I use Prometheus for metrics, not OTLP
OTEL_LOGS_EXPORTER=none: CloudWatch Logs handles logs via Fluent Bit
OTEL_PROPAGATORS: Includes xray for X-Ray trace ID format
Endpoints point to the CloudWatch agent service in the amazon-cloudwatch namespace

What Gets Traced

With this setup, X-Ray shows the complete request flow:

Component	Auto-traced	Manual (@Observed)
HTTP Server (Spring MVC)	✓
JDBC (PostgreSQL)	✓
AWS SDK (EventBridge, S3)	✓
Business logic methods		✓

Each trace shows end-to-end latency, time spent in each component, database queries, and external API calls. Finally, full visibility from HTTP request to database and back.

The Capstone: Application Signals

This is where it all comes together. Application Signals is AWS's APM solution that builds on top of traces. It automatically discovers services, collects telemetry, and displays key metrics without additional instrumentation.

Why I Like Application Signals

Traditional APM tools require vendor-specific agents and create lock-in. Application Signals uses standard OpenTelemetry instrumentation - the same ADOT agent configuration that enables tracing also enables Application Signals.

Just set OTEL_AWS_APPLICATION_SIGNALS_ENABLED=true and you're done. No additional code changes.

Service Health Dashboards

Application Signals automatically creates dashboards showing:

Request volume, latency (p50, p90, p99), and error rates
Service operations breakdown (which endpoints are slow?)
Service dependencies (what does this service call?)

These dashboards appear automatically once traffic flows through your instrumented application. No manual configuration needed - this was a pleasant surprise.

Service Level Objectives

SLOs monitor service reliability against defined targets. For example: "POST /unicorns will achieve latency under 1000ms for 99.9% of requests over a 14-day period."

I've set up SLOs for my critical endpoints and connected them to CloudWatch alarms. When an SLO is at risk, I get notified early.

Runtime Metrics

Application Signals also collects JVM runtime metrics:

Heap and non-heap memory usage
Garbage collection frequency and pause times
Thread count and states
CPU usage

These metrics have helped me catch memory leaks and GC pressure issues that weren't visible from infrastructure metrics alone.

Trade-offs and Considerations

Cost

CloudWatch pricing applies to logs, metrics, traces, and Application Signals. For high-traffic applications, costs can add up. Here's what I do:

Log retention policies (I don't keep DEBUG logs forever)
Trace sampling for high-volume services
Standard metric resolution (high-resolution only where needed)

Performance

The ADOT agent adds approximately 10-50ms to application startup time. Runtime overhead is minimal in my testing.

AspectJ weaving for @Observed annotations adds 1-2 seconds to startup. Worth it for the visibility it provides.

Complexity

The hybrid instrumentation approach (ADOT auto-instrumentation + manual @Observed) requires understanding what gets traced automatically versus what needs explicit annotation.

Conclusion

Here's the observability journey I've landed on for Java on Amazon EKS:

Logs and metrics via the CloudWatch Observability add-on provide the foundation
Distributed tracing with ADOT and @Observed annotations gives visibility into request flows
Application Signals delivers APM-level insights without vendor lock-in

The key insight: these layers build on each other. Application Signals needs traces. Traces need proper instrumentation. Proper instrumentation requires understanding the OpenTelemetry v2 changes.

If you want to try this yourself with complete code examples, check out the Java on AWS Immersion Day workshop. It's what I used to build my initial setup.

Learn More

A Practical Guide to Building AI Agents with Java and Spring AI - Part 6 - Multi-Modal Multi-Model

Yuriy Bezsonov — Mon, 22 Dec 2025 07:41:28 +0000

In Part 5 of this series, we added MCP to our AI agent, enabling dynamic tool integration without code changes. However, we discovered another limitation: when users wants to upload expense receipts, invoices, or travel documents, the agent can only process text—it cannot analyze images or extract information from visual documents.

Text-only AI agents miss critical information embedded in images, scanned documents, charts, and diagrams. In business scenarios like expense management, travel booking confirmations, or invoice processing, most information arrives as images or PDFs rather than structured text.

In this post, we'll add multi-modal capabilities (vision and document analysis) and multi-model support to our AI agent, allowing it to analyze images, extract structured data from receipts, and use different AI models optimized for specific tasks.

Overview of the Solution

The Multi-Modal Challenge

Text-only AI agents cannot:

Extract information from receipt images or scanned invoices
Analyze charts, diagrams, or infographics
Process travel booking confirmations (often PDFs with images)
Understand visual context in documents
Verify expense compliance from uploaded receipts

Users expect to upload a photo of their restaurant receipt and have the AI extract the amount, date, merchant, and check policy compliance automatically.

We'll solve this with multi-modal AI and multi-model architecture:

Add vision-capable models that can analyze images and documents
Create specialized service for document analysis with expense extraction
Configure different models for different tasks (chat vs. document analysis)
Route requests based on content type (text vs. image/document)

What is Multi-Modal AI?

Multi-modal AI models can process and understand multiple types of input:

Text: Natural language questions and responses
Images: Photos, screenshots, diagrams
Documents: PDFs, scanned receipts, invoices
Combined: Text prompts with attached images

Vision-capable models like Claude Sonnet, Amazon Nova and some other models can "see" images and extract structured information, enabling use cases like:

Expense receipt analysis and extraction
Invoice processing and validation
Travel document verification
Chart and diagram interpretation
Visual quality inspection

What is Multi-Model Architecture?

Different AI models excel at different tasks. A multi-model architecture uses:

Chat Model: Optimized for conversational interactions, reasoning, and tool calling
Document Model: Optimized for vision, document analysis, and structured data extraction
Embedding Model: Optimized for semantic search and RAG (already using Titan Embeddings)

This allows you to choose the best model for each task while maintaining a unified user experience.

Architecture Overview

User Request
     ↓
[ChatController]
     ↓
Has Image/Document?
     ├─ Yes → [DocumentChatService] → Vision Model (Claude Sonnet)
     └─ No  → [ChatService] → Chat Model (Claude Sonnet/Amazon Nova)
                    ↓
            [Memory + RAG + MCP Tools]
                    ↓
                Response

Key Spring AI Components

ChatClient: Unified interface for all AI models
Multi-Modal Support: Handle text, images, and documents in prompts
Model Options: Configure different models per request

Prerequisites

Before you start, ensure you have:

Completed Part 5 of this series with the working ai-agent application
Java 21 JDK installed (Amazon Corretto 21)
Maven 3.6+ installed
Docker Desktop running (for Testcontainers with PostgreSQL/PGVector)
AWS CLI configured with access to Amazon Bedrock
Access to vision-capable models in Amazon Bedrock (Claude Sonnet, Amazon Nova)

Navigate to your project directory from Part 5:

cd ai-agent

Multi-Model Configuration

We'll configure two models: one for chat interactions and one for document analysis.

Configure Models

Add model configuration to src/main/resources/application.properties:

cat >> src/main/resources/application.properties << 'EOF'

# Document processing model (vision-capable)
ai.agent.document.model=global.anthropic.claude-sonnet-4-5-20250929-v1:0
EOF

This configuration:

Uses Claude Sonnet 4.5 for document analysis (vision-capable)
Keeps the existing chat model configuration for conversations
Allows independent model selection for different tasks

You can use different models for chat and documents. For example, use Nova Pro for chat (cost-effective) and Claude Sonnet for documents (superior vision capabilities).

Document Analysis Service

We'll create a specialized service for analyzing images and documents with vision models.

Create DocumentChatService

Create the service that handles multi-modal document analysis:

mkdir -p src/main/java/com/example/ai/agent/service
cat <<'EOF' > src/main/java/com/example/ai/agent/service/DocumentChatService.java
package com.example.ai.agent.service;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.ai.chat.client.ChatClient;
import org.springframework.ai.chat.model.ChatModel;
import org.springframework.ai.model.tool.ToolCallingChatOptions;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.core.io.ByteArrayResource;
import org.springframework.http.MediaType;
import org.springframework.http.MediaTypeFactory;
import org.springframework.stereotype.Service;
import org.springframework.util.MimeType;
import org.springframework.util.MimeTypeUtils;
import reactor.core.publisher.Flux;
import java.util.Base64;

@Service
public class DocumentChatService {
    private static final Logger logger = LoggerFactory.getLogger(DocumentChatService.class);

    private final ChatClient documentChatClient;
    private final ChatService chatService;

    @Value("${ai.agent.document.model}")
    private String documentModel;

    public static final String DOCUMENT_ANALYSIS_PROMPT = """
        Extract expense information from this document.

        Required fields:
        - Document Type: [RECEIPT, INVOICE, TICKET, BILL, OTHER]
        - Expense Type: [MEALS, ACCOMMODATION, TRANSPORTATION, OFFICE_SUPPLIES, OTHER]
        - Amount and Currency
        - Date: [YYYY-MM-DD]

        Category-specific details:
        - ACCOMMODATION: check-in/out dates, nights, rate per night, location
        - MEALS: contains alcohol (yes/no)
        - TRANSPORTATION: type, route or location

        Check against the Expense Policy and provide approval status with reasoning.
        If not an expense document, provide a brief summary.
        For missing information, state "I don't know".
        """;

    public DocumentChatService(ChatModel chatModel, ChatService chatService) {
        this.documentChatClient = ChatClient.builder(chatModel)
                .defaultSystem(DOCUMENT_ANALYSIS_PROMPT)
                .build();
        this.chatService = chatService;
    }

    public Flux<String> processDocument(String prompt, String fileBase64, String fileName) {
        logger.info("Processing document: {}", fileName);

        return Flux.create(sink -> {
            // 1. Emit immediate feedback
            sink.next("Analyzing document...\n\n");

            // 2. Analyze document with multimodal AI
            String documentAnalysis = analyzeDocument(prompt, fileBase64, fileName);

            // 3. Stream structured summary with currency conversion
            String summaryPrompt = documentAnalysis + "\n\n" +
                "Based on the extracted information, provide a structured summary including:\n" +
                "- Amount in EUR: If original currency is EUR, use original amount. " +
                "Otherwise, convert to EUR using the document date (or current date if unavailable).\n\n" +
                "After presenting the information, ask the user to confirm and offer to register the expense.";

            chatService.processChat(summaryPrompt)
                .subscribe(
                    chunk -> sink.next(chunk),
                    error -> sink.error(error),
                    () -> sink.complete()
                );
        });
    }

    private String analyzeDocument(String prompt, String fileBase64, String fileName) {
        MimeType mimeType = determineMimeType(fileName);
        byte[] fileData = Base64.getDecoder().decode(fileBase64);
        ByteArrayResource resource = new ByteArrayResource(fileData);

        String userPrompt = (prompt != null && !prompt.trim().isEmpty())
                ? prompt
                : "Analyze this document";

        try {
            var chatResponse = documentChatClient
                    .prompt()
                    .options(ToolCallingChatOptions.builder()
                            .model(documentModel)
                            .build())
                    .user(userSpec -> {
                        userSpec.text(userPrompt);
                        userSpec.media(mimeType, resource);
                    })
                    .call().chatResponse();

            return (chatResponse != null)
                ? chatResponse.getResult().getOutput().getText()
                : "I don't know - no response received.";
        } catch (Exception e) {
            logger.error("Error analyzing document", e);
            return "I don't know - there was an error analyzing the document.";
        }
    }

    private MimeType determineMimeType(String fileName) {
        if (fileName != null && !fileName.trim().isEmpty()) {
            MediaType mediaType = MediaTypeFactory.getMediaType(fileName)
                    .orElse(MediaType.APPLICATION_OCTET_STREAM);
            return new MimeType(mediaType.getType(), mediaType.getSubtype());
        }
        return MimeTypeUtils.APPLICATION_OCTET_STREAM;
    }
}
EOF

Key features:

Multi-modal prompts: Combines text and images in a single request
Expense extraction: Structured prompt for extracting receipt information
Policy compliance: Checks expenses against company policies (via RAG)
Currency conversion: Uses tools to convert amounts to EUR
Streaming response: Provides immediate feedback and streams results

Update ChatController

Update ChatController to route document requests:

src/main/java/com/example/ai/agent/controller/ChatController.java

import com.example.ai.agent.service.DocumentChatService;
    ...
    private final DocumentChatService documentChatService;

    public ChatController(ChatService chatService,
                         ChatMemoryService chatMemoryService,
                         ConversationSummaryService summaryService,
                         DocumentChatService documentChatService) {
        this.chatService = chatService;
        this.chatMemoryService = chatMemoryService;
        this.summaryService = summaryService;
        this.documentChatService = documentChatService;
    }

    @PostMapping(value = "message", produces = MediaType.APPLICATION_OCTET_STREAM_VALUE)
    public Flux<String> chat(@RequestBody ChatRequest request, Principal principal) {
        String userId = getUserId(request.userId(), principal);
        chatMemoryService.setCurrentUserId(userId);

        // Route to document analysis or regular chat
        return hasFile(request)
            ? documentChatService.processDocument(request.prompt(), request.fileBase64(), request.fileName())
            : chatService.processChat(request.prompt());
    }

    ...

    private boolean hasFile(ChatRequest request) {
        return request.fileBase64() != null && !request.fileBase64().trim().isEmpty();
    }

    public record ChatRequest(String prompt, String userId, String fileBase64, String fileName) {}
    ...

The controller now:

Accepts file uploads as base64-encoded strings
Routes requests with files to DocumentChatService
Routes text-only requests to ChatService
Maintains the same streaming response interface

Update WebViewController

Enable multi-modal features in the UI:

src/main/java/com/example/ai/agent/controller/WebViewController.java

...
    @Value("${ui.features.multi-user:true}")
    private boolean multiUserEnabled;

    @Value("${ui.features.multi-modal:true}")
    private boolean multiModalEnabled;

    @GetMapping("/")
    public String index(Model model) {
        model.addAttribute("multiUserEnabled", multiUserEnabled);
        model.addAttribute("multiModalEnabled", multiModalEnabled);
        return "chat";
    }
}

This enables the file upload button in the web interface, allowing users to attach images and documents to their messages.

Testing Multi-Modal Capabilities

If you completed Part 5, you can either start the travel MCP server from Part 5, or comment out the MCP client configuration in application.properties to test multi-modal features independently:
# spring.ai.mcp.client.sse.connections.travel.url=http://localhost:8082

Let's test document analysis with a tram ticket image:

./mvnw spring-boot:test-run

Download the sample ticket image:

# Download sample tram ticket
curl -o ticket-tram-cz.png https://raw.githubusercontent.com/aws-samples/java-on-aws/main/samples/spring-ai-te-agent/ai-agent/samples/ticket-tram-cz.png

Test in the UI at http://localhost:8080:

Click the file upload button (📎)
Select the ticket-tram-cz.png image
Type "Analyze this expense receipt" in the message box
Click Send

The AI will analyze the tram ticket image and extract:

Analyzing document...

| Field | Details |
|-------|---------|
| **Document Type** | Public Transport Ticket |
| **Date** | 2025-06-12 |
| **Time** | 17:13 |
| **Original Amount** | 30.00 CZK |
| **Amount in EUR** | €1.22* |
| **Expense Category** | TRANSPORTATION |
| **Description** | Prague public transport 30-minute transfer ticket (zones P, O, B) |
| **Vendor** | Dopravní Podnik hl. m. Prahy, a.s. |
| **Location** | Prague, Czech Republic |

**Policy Compliance:**
✅ Approved: Transportation expenses are within policy limits

Would you like me to register this expense?

✅ Success! The AI agent can now analyze images and extract structured information.

You can also test in the UI at http://localhost:8080 - use the file upload feature to analyze receipts, invoices, or travel documents.

To test expense registration, you can download the backend MCP server from the sample repository and connect your AI Agent to it using the techniques learned in Part 5. The backend server provides expense management tools that work seamlessly with document analysis.

How Multi-Modal Works

When you upload a receipt image, here's what happens:

Image upload: Browser converts image to base64 and sends to server
Routing: ChatController detects file and routes to DocumentChatService
Vision analysis: Claude Sonnet analyzes the image and extracts expense data
Policy check: RAG retrieves relevant expense policies
Currency conversion: Tools convert amounts to EUR if needed (if backend server is connected)
Structured response: Formats results with approval status

The AI "sees" the receipt image and extracts text, amounts, dates, and merchant information automatically.

Multi-Model Benefits

Using different models for different tasks provides:

Cost optimization: Use cheaper models for simple chat, expensive models for complex vision tasks
Performance optimization: Vision models for documents, fast models for chat
Capability matching: Use models with specific strengths (Claude for vision, Nova for speed)
Flexibility: Switch models without changing application code

Cleanup

To stop the application, press Ctrl+C in the terminal where it's running.

The PostgreSQL container will continue running (due to withReuse(true)). If necessary, stop and remove it:

docker stop ai-agent-postgres
docker rm ai-agent-postgres

(Optional) To remove all data and start fresh:

docker volume prune

Commit Changes

git add .
git commit -m "Add multi-modal document analysis and multi-model support"

Conclusion

In this post, we've added multi-modal and multi-model capabilities to our AI agent:

Multi-Modal Support: Analyze images, receipts, invoices, and documents
Document Analysis Service: Specialized service for vision-based extraction
Multi-Model Architecture: Different models for chat vs. document analysis
Expense Extraction: Structured data extraction from receipt images
Policy Compliance: Automatic checking against company policies

Our AI agent now has a complete, production-ready architecture: memory (Part 2), knowledge (Part 3), real-time information (Part 4), dynamic tool integration (Part 5), and multi-modal capabilities (Part 6). It can handle text conversations, analyze images, integrate with any service via MCP, and use the best AI model for each task—all essential capabilities for enterprise AI applications.

What's Next

Explore production deployment patterns, monitoring and observability, security best practices, and scaling strategies for AI agents in enterprise environments.

Learn More

Let's continue building intelligent Java applications with Spring AI!

Let's continue this journey in 2026!

A Practical Guide to Building AI Agents with Java and Spring AI - Part 5 - Add MCP

Yuriy Bezsonov — Tue, 16 Dec 2025 08:00:00 +0000

In Part 4 of this series, we added tool calling to our AI agent, allowing it to access real-time information like weather forecasts and current dates. However, we discovered another limitation: when asked to book flights or hotels, the agent couldn't access those systems because we'd need to hardcode every API integration into our application.

Hardcoding API integrations creates maintenance challenges. Every new service requires code changes, recompilation, and redeployment. As your organization adds more systems (booking platforms, inventory systems, CRM tools), your AI agent becomes increasingly difficult to maintain and extend.

In this post, we'll add Model Context Protocol (MCP) to our AI agent, allowing it to dynamically discover and use tools from external services without code changes or redeployment. You'll learn how MCP enables you to expose your legacy systems, enterprise applications, or microservices to AI agents without rewriting them.

Overview of the Solution

The Integration Challenge

Hardcoding tool integrations has several problems:

Every new API requires code changes and redeployment
Tools are tightly coupled to the AI agent application
Different teams can't independently develop and deploy their tools
Testing and versioning tools becomes complex
Scaling to dozens or hundreds of integrations becomes unmanageable

We need a way to add new capabilities to our AI agent without modifying its code.

We'll solve this with Model Context Protocol (MCP):

Create MCP servers that expose tools via a standardized protocol
Configure MCP client in our AI agent to discover available tools
Let the AI automatically call tools from any connected MCP server
Add new capabilities by simply starting new MCP servers

What is Model Context Protocol?

Model Context Protocol (MCP) is an open protocol that standardizes how AI applications connect to external tools and data sources. Think of it as a universal adapter that lets AI agents discover and use tools from any service that implements the protocol.

Key benefits:

Standardized Interface: All tools use the same protocol, regardless of implementation
Dynamic Discovery: AI agents automatically discover available tools from connected servers
Loose Coupling: Tools and AI agents can be developed, deployed, and scaled independently
Multiple Transports: Supports Streamable HTTP (recommended), SSE (Server-Sent Events), stdio, and custom transports
Language Agnostic: Servers can be written in any language (Java, Python, Node.js, etc.)

Architecture Overview

AI Agent (MCP Client)
     ↓
[MCP Protocol - Streamable HTTP Transport]
     ↓
┌─────────────────────────────┐     ┌─────────────────────────────┐
│     Travel Server           │     │  More MCP Servers can be    │
│     (URL:8082)              │     │  added via URL:PORT         │
├─────────────────────────────┤     │  - GitHub Server            │
│ - findFlightsByRoute        │     │  - Jira Server              │
│ - findFlightByNumber        │     │  - CRM Server               │
│ - findHotelsByCity          │     │  - Inventory Server         │
│ - findHotelsByName          │     │  - ...                      │
│ - getHotel                  │     └─────────────────────────────┘
└─────────────────────────────┘

Key Spring AI Components

MCP Server Starter: Auto-configures MCP server capabilities in Spring Boot applications
MCP Client Starter: Connects to MCP servers and registers their tools automatically
ToolCallbackProvider: Spring AI interface for tool registration and invocation

Prerequisites

Before you start, ensure you have:

Completed Part 4 of this series with the working ai-agent application
Java 21 JDK installed (Amazon Corretto 21)
Maven 3.6+ installed
Docker Desktop running (for Testcontainers with PostgreSQL/PGVector)
AWS CLI configured with access to Amazon Bedrock

Navigate to your project directory from Part 4:

cd ai-agent

MCP Server

We'll create a separate Spring Boot application that acts as an MCP server, exposing travel-related tools (flight and hotel search/booking) that our AI agent can use.

Why Separate Server?

Separating the MCP server from the AI agent provides several benefits:

Independent Deployment: Update travel services without redeploying the AI agent
Team Autonomy: Different teams can own and maintain their own MCP servers
Scalability: Scale travel services independently based on demand
Reusability: Multiple AI agents or applications can use the same MCP server

Clone Travel Server

We'll use a pre-built travel server that demonstrates MCP server capabilities:

cd ..
git clone https://github.com/aws-samples/java-on-aws.git
cd java-on-aws/samples/spring-ai-te-agent/travel

Explore Travel Server Structure

The travel server provides comprehensive travel management capabilities:

# View the project structure
ls -la src/main/java/com/example/travel/

Key components:

HotelTools: Search and booking tools for hotels
FlightTools: Search and booking tools for flights
AirportTools: Airport information lookup
Services: Business logic for travel operations
Repositories: Data access layer with Spring Data JPA

The travel server is configured as an MCP server with these key dependencies in pom.xml:

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

And configuration in application.properties:

# MCP Server properties
spring.ai.mcp.server.name=travel
spring.ai.mcp.server.version=1.0.0
spring.ai.mcp.server.instructions="Travel management: search for airports, flights, hotels; book flights and hotels"
spring.ai.mcp.server.protocol=STREAMABLE
logging.level.org.springframework.ai=DEBUG

These properties configure the MCP server identity and provide instructions that help AI agents understand the server's capabilities.

Note: Starting with Spring AI 1.1.0, we use the Streamable HTTP MCP Server which provides better performance and reliability compared to SSE transport.

Review HotelTools

Let's examine how tools are exposed via MCP:

cat src/main/java/com/example/travel/accommodations/HotelTools.java

package com.example.travel.accommodations;

import org.springframework.ai.tool.annotation.Tool;
import org.springframework.ai.tool.ToolCallbackProvider;
import org.springframework.ai.tool.method.MethodToolCallbackProvider;
import org.springframework.context.annotation.Bean;
import org.springframework.stereotype.Component;

import java.time.LocalDate;
import java.util.List;

@Component
public class HotelTools {

    private final HotelService hotelService;

    public HotelTools(HotelService hotelService) {
        this.hotelService = hotelService;
    }

    @Bean
    public ToolCallbackProvider hotelToolsProvider(HotelTools hotelTools) {
        return MethodToolCallbackProvider.builder()
                .toolObjects(hotelTools)
                .build();
    }

    @Tool(description = """
        Find hotels in a city for specific dates.
        Requires: city - Name of the city to search in,
                 checkInDate - Check-in date (YYYY-MM-DD),
                 numberOfNights - Number of nights to stay.
        Returns: List of available hotels sorted by price from lowest to highest.
        Errors: NOT_FOUND if no hotels found in the specified city.
        """)
    public List<Hotel> findHotelsByCity(String city, LocalDate checkInDate, Integer numberOfNights) {
        return hotelService.findHotelsByCity(city, checkInDate, numberOfNights);
    }

    @Tool(description = """
        Find hotel details by hotel name.
        Requires: hotelName - The name of the hotel.
        Returns: Complete hotel details including amenities, pricing, and availability.
        Errors: NOT_FOUND if hotel doesn't exist with the specified hotelName.
        """)
    public List<Hotel> findHotelsByName(String hotelName) {
        return hotelService.findHotelsByName(hotelName);
    }

    @Tool(description = """
        Get hotel details by ID.
        Requires: id - The unique identifier of the hotel.
        Returns: Complete hotel details including amenities, pricing, and availability.
        Errors: NOT_FOUND if hotel doesn't exist with the specified ID.
        """)
    public Hotel getHotel(String id) {
        return hotelService.getHotel(id);
    }
}

Key points:

@Tool annotation: Marks methods as callable tools with detailed descriptions
ToolCallbackProvider bean: Registers tools with Spring AI's MCP server
Separation of concerns: Tools delegate to service layer for business logic
Clear descriptions: Help the AI understand when and how to use each tool
Tools files pattern: Create separate Tools classes instead of annotating service methods directly, allowing you to expand complex objects into individual parameters and use descriptive method names that help the AI model understand which method to call with which parameters

Important: The real power of Spring AI's MCP server starter is that you can add MCP capabilities to almost any existing Java application or microservice. By simply adding the starter dependency and annotating methods with @Tool, you can expose your legacy systems, enterprise applications, or microservices to AI agents without rewriting them. This enables AI integration across your entire application landscape.

Start Travel Server

Open a new terminal and run the travel server. It uses Testcontainers for automatic PostgreSQL management:

./mvnw spring-boot:test-run

You should see:

Creating container for image: postgres:16
Container postgres:16 is starting...
Container postgres:16 started
Started TravelApplication in X.XXX seconds

The server is now running on http://localhost:8082 with:

Over 100 hotels across major cities
Sample flights between popular destinations
MCP server endpoints for tool discovery

Keep this terminal open - the travel server needs to run while we test the AI agent.

Test Travel Server

Open a new terminal and verify the server is working:

# Search for hotels in Paris
curl "http://localhost:8082/api/hotels/search?city=Paris&checkInDate=2025-11-15&numberOfNights=3" | jq '.[0:2]'

# Search for flights from London to Paris
curl "http://localhost:8082/api/flights/search?departureCity=London&arrivalCity=Paris" | jq '.[0:2]'

✅ Success! The travel server is running and responding to requests.

MCP Client

Now we'll configure our AI agent to connect to the travel server via MCP, automatically discovering and using its tools.

Add MCP Client Dependency

Navigate back to your AI agent project:

Open pom.xml and add the MCP client dependency to the <dependencies> section:

        <!-- MCP Client -->
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-starter-mcp-client</artifactId>
        </dependency>

Configure MCP Client

Add MCP client configuration to src/main/resources/application.properties:

cat >> src/main/resources/application.properties << 'EOF'

# MCP Client Configuration
spring.ai.mcp.client.toolcallback.enabled=true
spring.ai.mcp.client.streamablehttp.connections.travel.url=http://localhost:8082
EOF

This configuration:

Enables automatic tool callback registration
Connects to the travel server via Streamable HTTP transport
Names the connection "travel" for identification in logs

Update ChatService with MCP

Update ChatService to use tools from MCP servers:

src/main/java/com/example/ai/agent/service/ChatService.java

    ...
    public ChatService(ChatMemoryService chatMemoryService,
                      VectorStore vectorStore,
                      DateTimeService dateTimeService,
                      WeatherService weatherService,
                      ToolCallbackProvider tools,
                      ChatClient.Builder chatClientBuilder) {

        // Build ChatClient with RAG, tools, and memory
        this.chatClient = chatClientBuilder
                .defaultSystem(SYSTEM_PROMPT)
                .defaultAdvisors(QuestionAnswerAdvisor.builder(vectorStore).build())  // RAG for policies
                .defaultTools(dateTimeService, weatherService)  // Custom tools
                .defaultToolCallbacks(tools)  // Auto-registered tools from MCP
                .build();

        this.chatMemoryService = chatMemoryService;
    }
    ...

The key change is adding ToolCallbackProvider tools parameter and .defaultToolCallbacks(tools) method. Spring AI automatically:

Connects to configured MCP servers
Discovers available tools
Registers them with the ChatClient
Makes them available to the AI model

Testing MCP Integration

Let's test the complete MCP integration with travel bookings:

./mvnw spring-boot:test-run

You should see in the logs:

...
Server response with Protocol: 2024-11-05, Capabilities: ServerCapabilities[completions=CompletionCapabilities[], experimental=null, logging=LoggingCapabilities[], prompts=PromptCapabilities[listChanged=true], resources=ResourceCapabilities[subscribe=false, listChanged=true], tools=ToolCapabilities[listChanged=true]], Info: Implementation[name=travel, version=1.0.0] and Instructions "Travel management: search for airports, flights, hotels; book flights and hotels"
...1
Started AiAgentApplication in 3.088 seconds (process running for 3.31)

Test with REST API:

# Search for hotels in Paris
curl -X POST http://localhost:8080/api/chat/message \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Find me hotels in Paris for 3 nights starting November 15, 2025", "userId": "alice"}' \
  --no-buffer
# Response: Lists available hotels with prices, amenities, and ratings

# Search for flights
curl -X POST http://localhost:8080/api/chat/message \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Find flights from London to Paris", "userId": "alice"}' \
  --no-buffer
# Response: Lists available flights with times, airlines, and prices

# Complex travel planning
curl -X POST http://localhost:8080/api/chat/message \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Please find me inbound and outbound flights and accommodations for a trip from London to Paris next week, from Monday to Friday. I travel alone, prefer BA flights in the first part of the day, and choose accommodation which is the most expensive but complies with our travel policy. Give me a travel itinerary with flights, accommodation, prices and weather forecast for each day of the travel.",
    "userId": "alice"
  }' \
  --no-buffer
# Response: Complete travel itinerary with flights, hotel, prices, and weather

✅ Success! The AI agent now has access to travel booking capabilities through MCP without any hardcoded integrations.

You can also test in the UI at http://localhost:8080 - ask about flights, hotels, or complete travel planning.

How MCP Works

When you ask "Find hotels in Paris for 3 nights", here's what happens:

AI analyzes the question: Recognizes it needs hotel search capabilities
Tool discovery: Finds findHotelsByCity tool from the travel MCP server
Parameter extraction: Extracts city="Paris", numberOfNights=3, and determines check-in date
Tool invocation: Calls the travel server via MCP protocol
Response synthesis: Formats hotel results into a natural language response

The AI automatically decides which tools to call from which servers, all through the standardized MCP protocol.

Let's continue the chat. Alice returned from her Paris trip and wants to submit her expenses:

curl -X POST http://localhost:8080/api/chat/message \
  -H "Content-Type: application/json" \
  -d '{"prompt": "I just returned from Paris and need to submit my hotel receipt and restaurant expenses. Can you help me process them?", "userId": "alice"}' \
  --no-buffer
# Response: "I can help you submit expenses, but I need the receipt details. Please provide the amounts, dates, and merchant names."

❌ Problem discovered: Alice has photos of her receipts on her phone, but the agent can only process text—it cannot analyze images or extract information from visual documents like receipts, invoices, or travel confirmations.

We'll address this limitation in the next part of the series! Stay tuned!

Add More MCP Servers

The power of MCP is that you can add new capabilities without changing the AI agent code:

# Start another MCP server on a different port
# The AI agent will automatically discover its tools
export SPRING_AI_MCP_CLIENT_STREAMABLEHTTP_CONNECTIONS_TRAVEL_URL=http://localhost:8083
./mvnw spring-boot:test-run

You can add as many MCP servers as needed, each providing different capabilities (CRM, inventory, analytics, etc.).

Cleanup

To stop the applications:

Press Ctrl+C in the AI agent terminal
Press Ctrl+C in the travel server terminal

The PostgreSQL containers will continue running (due to withReuse(true)). If necessary, stop and remove them:

docker stop ai-agent-postgres
docker rm ai-agent-postgres

(Optional) To remove all data and start fresh:

docker volume prune

Commit Changes

git add .
git commit -m "Add MCP client integration"

Conclusion

In this post, we've added dynamic tool integration to our AI agent through MCP:

MCP Server: Created a separate travel service exposing hotel and flight tools
MCP Client: Configured AI agent to discover and use tools from MCP servers
Dynamic Discovery: AI automatically finds and calls tools without hardcoded integrations
Loose Coupling: Travel services can be updated independently of the AI agent
Scalability: Add new capabilities by starting new MCP servers

Our AI agent now has a complete, production-ready architecture: memory (Part 2), knowledge (Part 3), real-time information (Part 4), and dynamic tool integration (Part 5). It can remember conversations, answer policy questions, access current information, and integrate with any service that implements the MCP protocol—all essential capabilities for enterprise AI applications.

What's Next

Explore advanced features like multi-modal support (image and document analysis) using various models.

Learn More

Let's continue building intelligent Java applications with Spring AI!

A Practical Guide to Building AI Agents with Java and Spring AI - Part 4 - Add Tools

Yuriy Bezsonov — Tue, 25 Nov 2025 09:59:00 +0000

In Part 3 of this series, we enhanced our AI agent with domain-specific knowledge through RAG, allowing it to answer questions based on company documents. However, we discovered another critical limitation: when asked about real-time information like weather forecasts or current dates, the agent couldn't provide accurate answers.

AI models are trained on historical data with a knowledge cutoff date. They don't have access to real-time information like current weather, today's date, live flight prices, or currency exchange rates. This makes them unable to help with time-sensitive tasks that require up-to-date information.

In this post, we'll add tool calling (also known as function calling) to our AI agent, allowing it to access real-time information and take actions by calling external APIs and services.

Overview of the Solution

The Real-Time Information Challenge

AI models are trained on historical data and don't have access to:

Current date and time
Weather forecasts
Live flight prices
Currency exchange rates
Real-time inventory or availability

They might provide outdated or incorrect information based on their training data cutoff.

We'll solve this with tool calling (function calling):

Define tools as Java methods annotated with @Tool
Provide clear descriptions to help the AI choose the right tool
Let the AI automatically call tools when needed
Return real-time data to ground AI responses

Why Tool Calling?

Tool calling enables two key capabilities:

Information Retrieval: Access external data sources (weather APIs, databases, web services) to augment the AI's knowledge with real-time information
Taking Action: Execute operations (send emails, book flights, create records) to automate tasks that require system integration

Architecture Overview

User Question
     ↓
AI Model (Amazon Bedrock)
     ↓
[Decides which tool to call]
     ↓
[DateTimeService] ← Get current date/time
[WeatherService] ← Get weather forecast
     ↓
Response (with real-time data)

Prerequisites

Before you start, ensure you have:

Completed Part 3 of this series with the working ai-agent application
Java 21 JDK installed (Amazon Corretto 21)
Maven 3.6+ installed
Docker Desktop running (for Testcontainers with PostgreSQL/PGVector)
AWS CLI configured with access to Amazon Bedrock

Navigate to your project directory from Part 3:

cd ai-agent

Tool Calling

Add WebClient Dependency

We'll use Spring WebFlux's WebClient for non-blocking HTTP calls to external APIs.

Open pom.xml and add this dependency to the <dependencies> section:

        <!-- WebClient for HTTP calls -->
        <dependency>
            <groupId>org.springframework</groupId>
            <artifactId>spring-webflux</artifactId>
        </dependency>

Create DateTimeService

Create a tool that provides the current date and time in any timezone:

mkdir -p src/main/java/com/example/ai/agent/tool
cat <<'EOF' > src/main/java/com/example/ai/agent/tool/DateTimeService.java
package com.example.ai.agent.tool;

import java.time.ZonedDateTime;
import java.time.ZoneId;
import java.time.format.DateTimeFormatter;
import org.springframework.ai.tool.annotation.Tool;
import org.springframework.stereotype.Service;

@Service
public class DateTimeService {

    @Tool(description = """
        Get current date and time in specified timezone.

        Parameters:
        - timeZone: e.g., 'UTC', 'America/New_York', 'Europe/London'

        Returns: ISO format (YYYY-MM-DDTHH:MM:SS)

        Use this when users mention relative dates like "next week" or "tomorrow".
        """)
    public String getCurrentDateTime(String timeZone) {
        return ZonedDateTime.now(ZoneId.of(timeZone))
                .format(DateTimeFormatter.ISO_LOCAL_DATE_TIME);
    }
}
EOF

@Tool Annotation: Marks methods as callable tools for the AI. The description helps the AI understand when and how to use it.

Create WeatherService

Create a tool that fetches weather forecasts from Open-Meteo API:

cat <<'EOF' > src/main/java/com/example/ai/agent/tool/WeatherService.java
package com.example.ai.agent.tool;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.ai.tool.annotation.Tool;
import org.springframework.stereotype.Service;
import org.springframework.web.reactive.function.client.WebClient;

import java.net.URLEncoder;
import java.nio.charset.StandardCharsets;
import java.time.Duration;
import java.time.LocalDate;
import java.util.Collections;
import java.util.List;
import java.util.Map;

@Service
public class WeatherService {
    private static final Logger logger = LoggerFactory.getLogger(WeatherService.class);
    private final WebClient webClient;

    public WeatherService(WebClient.Builder webClientBuilder) {
        this.webClient = webClientBuilder.build();
    }

    @Tool(description = """
        Get weather forecast for a city on a specific date.
        Requires:
        - city: City name (e.g., 'London', 'Paris', 'New York')
        - date: Date in YYYY-MM-DD format
        Returns: Weather forecast with minimum and maximum temperatures.

        Examples:
        - getWeather("London", "2025-11-10")
        - getWeather("Paris", "2025-11-15")

        Use this tool when users ask about weather conditions for travel planning.
        """)
    public String getWeather(String city, String date) {
        if (city == null || city.trim().isEmpty()) {
            return "Error: City parameter is required";
        }

        try {
            LocalDate.parse(date);
        } catch (Exception e) {
            return "Error: Invalid date format. Use YYYY-MM-DD";
        }

        logger.info("Fetching weather for city: {}, date: {}", city, date);

        try {
            // Get city coordinates
            String encodedCity = URLEncoder.encode(city.trim(), StandardCharsets.UTF_8);
            String geocodingUrl = "https://geocoding-api.open-meteo.com/v1/search?name=" + encodedCity + "&count=1";

            Map<?, ?> geocodingResponse = webClient.get()
                    .uri(geocodingUrl)
                    .retrieve()
                    .bodyToMono(Map.class)
                    .timeout(Duration.ofSeconds(15))
                    .block();

            List<?> results = Collections.emptyList();
            if (geocodingResponse != null && geocodingResponse.containsKey("results")) {
                Object resultsObj = geocodingResponse.get("results");
                if (resultsObj instanceof List) {
                    results = (List<?>) resultsObj;
                }
            }

            if (results.isEmpty()) {
                return "Error: City not found: " + city;
            }

            var location = (Map<?, ?>) results.get(0);
            var latitude = ((Number) location.get("latitude")).doubleValue();
            var longitude = ((Number) location.get("longitude")).doubleValue();
            var cityName = (String) location.get("name");
            var country = location.get("country") != null ? (String) location.get("country") : "";

            // Get weather data
            String weatherUrl = String.format(
                    "https://api.open-meteo.com/v1/forecast?latitude=%s&longitude=%s&daily=temperature_2m_max,temperature_2m_min&timezone=auto&start_date=%s&end_date=%s",
                    latitude, longitude, date, date
            );

            Map<?, ?> weatherResponse = webClient.get()
                    .uri(weatherUrl)
                    .retrieve()
                    .bodyToMono(Map.class)
                    .timeout(Duration.ofSeconds(15))
                    .block();

            if (weatherResponse == null) {
                return "Error: No response from weather service";
            }

            var dailyData = (Map<?, ?>) weatherResponse.get("daily");
            var dailyUnits = (Map<?, ?>) weatherResponse.get("daily_units");

            if (dailyData == null || dailyUnits == null) {
                return "Error: Invalid weather data format";
            }

            var maxTempList = (List<?>) dailyData.get("temperature_2m_max");
            var minTempList = (List<?>) dailyData.get("temperature_2m_min");

            if (maxTempList == null || minTempList == null || maxTempList.isEmpty() || minTempList.isEmpty()) {
                return "Error: No temperature data for date: " + date;
            }

            var maxTemp = ((Number) maxTempList.get(0)).doubleValue();
            var minTemp = ((Number) minTempList.get(0)).doubleValue();
            var unit = (String) dailyUnits.get("temperature_2m_max");

            String locationDisplay = cityName + (country.isEmpty() ? "" : ", " + country);
            String formattedUnit = unit.replace("°", " deg ");

            logger.info("Retrieved weather for {}: min: {}{}, max: {}{}",
                    locationDisplay, minTemp, formattedUnit, maxTemp, formattedUnit);

            return String.format(
                    "Weather for %s on %s:\nMin: %.1f%s, Max: %.1f%s",
                    locationDisplay, date, minTemp, formattedUnit, maxTemp, formattedUnit
            );

        } catch (Exception e) {
            logger.error("Error fetching weather for city: {}, date: {}", city, date, e);
            return "Error: Unable to fetch weather data - " + e.getMessage();
        }
    }
}
EOF

The WeatherService:

Converts city names to coordinates using the Geocoding API
Fetches weather data from Open-Meteo API
Returns formatted temperature forecasts
Handles errors gracefully

Update ChatService with Tools

Add the tools to ChatService:

src/main/java/com/example/ai/agent/service/ChatService.java

    ...
    private final ChatMemoryService chatMemoryService;

    public static final String SYSTEM_PROMPT = """
        You are a helpful AI Agent for travel and expenses.

        Guidelines:
        1. Use markdown tables for structured data
        2. If unsure, say "I don't know"
        3. Use provided context for company policies
        4. Use tools for dynamic data (flights, weather, bookings, currency)
        """;

    public ChatService(ChatMemoryService chatMemoryService,
                      VectorStore vectorStore,
                      DateTimeService dateTimeService,
                      WeatherService weatherService,
                      ChatClient.Builder chatClientBuilder) {

        this.chatClient = chatClientBuilder
                .defaultSystem(SYSTEM_PROMPT)
                .defaultAdvisors(QuestionAnswerAdvisor.builder(vectorStore).build())  // RAG for policies
                .defaultTools(dateTimeService, weatherService)  // Custom tools
                .build();

        this.chatMemoryService = chatMemoryService;
    }
    ...

Testing Tools

Let's test the tool calling with real-time information:

./mvnw spring-boot:test-run

Test with REST API:

# Test current date/time and weather forecast
curl -X POST http://localhost:8080/api/chat/message \
  -H "Content-Type: application/json" \
  -d '{"prompt": "I would like to travel to Paris next week from Monday to Friday. What is the weather forecast?", "userId": "alice"}' \
  --no-buffer
# Response: "Weather for Paris, France on 2025-11-11: Min: 8.7 deg C, Max: 14.3 deg C"

✅ Success! The agent now has access to real-time information through tools.

You can also test in the UI at http://localhost:8080 - ask about weather, dates, or travel planning questions that require real-time data.

How Tool Calling Works

When you ask "What is the weather tomorrow in Paris?", here's what happens:

AI analyzes the question: Recognizes it needs current date and weather data
AI calls getCurrentDateTime: Gets today's date to calculate "tomorrow"
AI calls getWeather: Fetches forecast for Paris on the calculated date
AI synthesizes response: Combines tool results into a natural language answer

The AI automatically decides which tools to call, in what order, and with what parameters—all based on the tool descriptions you provided.

Let's continue the chat:

curl -X POST http://localhost:8080/api/chat/message \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Please find me inbound and outbound flights and accommodations for a trip from London to Paris next week, From Monday to Friday. I travel alone, prefer BA flights in the first part of the day, and choose accommodation which is the most expensive, but comply with our travel policy. Give me a travel itinerary with flights, accommodation, prices and weather forecast for each day of the travel.",
    "userId": "alice"
  }' \
  --no-buffer
# Response: "I understand you'd like a complete travel itinerary for your London to Paris trip next week (Monday-Friday), but I don't have access to flight booking systems or hotel reservation platforms to search for specific BA flights or accommodations."

❌ Problem discovered: The agent doesn't have access to flight booking systems or hotel reservation platforms to search for specific BA flights or accommodations, and we cannot integrate every required system via APIs like we did with the weather system. We need a more flexible way.

We'll address this limitation in the next part of the series! Stay tuned!

Cleanup

To stop the application, press Ctrl+C in the terminal where it's running.

The PostgreSQL container will continue running (due to withReuse(true)). If necessary, stop and remove it:

docker stop ai-agent-postgres
docker rm ai-agent-postgres

(Optional) To remove all data and start fresh:

docker volume prune

Commit Changes

git add .
git commit -m "Add tool calling with date/time and weather"

Conclusion

In this post, we've added real-time capabilities to our AI agent through tool calling:

DateTimeService: Provides current date and time in any timezone
WeatherService: Fetches weather forecasts from Open-Meteo API
Automatic tool selection: AI decides which tools to call based on user questions
Real-time data: Agent can now answer time-sensitive questions accurately

Our AI agent now has the complete foundation for production use: memory (Part 2), knowledge (Part 3), and real-time information access (Part 4). It can remember conversations, answer policy questions, and provide up-to-date information—all essential capabilities for real-world applications.

What's Next

We need to give the AI Agent the ability to connect to APIs on the Internet or in the Intranet in a flexible way.

Learn More

Let's continue building intelligent Java applications with Spring AI!

A Practical Guide to Building AI Agents with Java and Spring AI - Part 3 - Add Knowledge

Yuriy Bezsonov — Mon, 17 Nov 2025 08:30:00 +0000

In Part 2 of this series, we enhanced our AI agent with conversation memory, allowing it to remember previous interactions and maintain context across sessions. However, we discovered another critical limitation: when asked about company-specific information like travel policies, the agent couldn't provide accurate answers.

Generic AI models are trained on broad internet data but don't know your company's specific policies, procedures, or domain knowledge. They might provide plausible-sounding but incorrect answers (hallucinations), which is unacceptable for business applications.

In this post, we'll add domain-specific knowledge to our AI agent through RAG (Retrieval-Augmented Generation), allowing it to answer questions based on company documents with accuracy and confidence.

Overview of the Solution

We'll solve the knowledge problem with RAG (Retrieval-Augmented Generation):

Convert company documents (travel policy) into vector embeddings
Store embeddings in a vector database (PGVector)
Automatically retrieve relevant sections when users ask questions
Ground AI responses in actual company documents

What are vector embeddings?

Vector embeddings are numerical representations of words, sentences, or other data types in a continuous vector space, where similar meanings are located close together. For example, the vectors for “Paris” and “France” will be close to each other—just as “Tokyo” and “Japan” are—because the model learns their relationship through context. This concept allows computers to understand semantic similarity and is widely used in search engines, recommendation systems, and chatbots.

Architecture Overview

User Question
     ↓
[Vector Store] ← PGVector (company policies, RAG)
     ↓
AI Model (Amazon Bedrock)
     ↓
Response (grounded in documents)

Key Spring AI Components

QuestionAnswerAdvisor: Automatically retrieves relevant documents for RAG
PGVector: PostgreSQL extension for vector similarity search
Titan Embeddings: Amazon Bedrock's embedding model

Prerequisites

Before you start, ensure you have:

Completed Part 2 of this series with the working ai-agent application
Java 21 JDK installed (Amazon Corretto 21)
Maven 3.6+ installed
Docker Desktop running (for Testcontainers with PostgreSQL/PGVector)
AWS CLI configured with access to Amazon Bedrock
Access to Amazon Bedrock models (specifically Titan Embeddings) in your AWS account

Navigate to your project directory from Part 2:

cd ai-agent

Travel Policy and RAG

Why RAG?

RAG (Retrieval-Augmented Generation) grounds AI responses in actual documents, eliminating hallucinations and ensuring accuracy.

Why PGVector?

Spring AI supports multiple vector databases:

PGVector (PostgreSQL extension - what we'll use)
OpenSearch
Pinecone
Weaviate
Milvus
Chroma
Redis

We chose PGVector because:

✅ Reuses existing PostgreSQL database (from Part 2)
✅ Single database for both memory and knowledge
✅ No additional infrastructure needed
✅ OpenSearch and other specialized vector databases are excellent for large-scale production, but add complexity
✅ PGVector is sufficient for most applications

For large-scale production with millions of documents, consider dedicated vector databases like OpenSearch or Pinecone.

Add RAG Dependencies

Open pom.xml and add these dependencies to the <dependencies> section:

        <!-- RAG Dependencies -->
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-vector-store</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-advisors-vector-store</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-starter-vector-store-pgvector</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-starter-model-bedrock</artifactId>
        </dependency>

Configure Titan Embeddings and PGVector:

cat >> src/main/resources/application.properties << 'EOF'

# RAG Configuration
spring.ai.model.embedding=bedrock-titan
spring.ai.bedrock.titan.embedding.model=amazon.titan-embed-text-v2:0
spring.ai.bedrock.titan.embedding.input-type=text
spring.ai.vectorstore.pgvector.initialize-schema=true
spring.ai.vectorstore.pgvector.dimensions=1024
EOF

Create Travel Policy

Create the company travel and expense policy document:

mkdir -p samples
cat <<'EOF' > samples/policy-travel.md
# Travel Policy

## Purpose
Guidelines for booking business travel including flights, accommodation, and transportation.

## Accommodation

### Regional Limits
- Europe: Maximum €130 per night
- North America: Maximum $150 per night
- Asia Pacific: Maximum $120 per night

### Booking Requirements
- Use company-preferred vendors when available
- Exceeding regional limits requires Director approval

## Transportation

### Air Travel
- Economy class for standard flights
- Business class requires Director approval

### Ground Transportation
- Taxi/rideshare for airport transfers and business meetings
- Car rentals require Manager approval

## Approval Requirements
- All travel must be pre-approved by Manager
- Exceptions to policy limits require Director approval
EOF

Create VectorStoreService and Controller

Create a service to load documents into the vector store:

cat <<'EOF' > src/main/java/com/example/ai/agent/service/VectorStoreService.java
package com.example.ai.agent.service;

import org.springframework.ai.document.Document;
import org.springframework.ai.vectorstore.VectorStore;
import org.springframework.stereotype.Service;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import java.util.List;

@Service
public class VectorStoreService {
    private static final Logger logger = LoggerFactory.getLogger(VectorStoreService.class);

    private final VectorStore vectorStore;

    public VectorStoreService(VectorStore vectorStore) {
        this.vectorStore = vectorStore;
    }

    // Add content to vector store for semantic search
    public void addContent(String content) {
        logger.info("Adding content to vector store: {} chars", content.length());
        vectorStore.add(List.of(new Document(content)));
    }
}
EOF

Create a controller to expose the load endpoint:

cat <<'EOF' > src/main/java/com/example/ai/agent/controller/VectorStoreController.java
package com.example.ai.agent.controller;

import com.example.ai.agent.service.VectorStoreService;

import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("api/admin")
public class VectorStoreController {
    private final VectorStoreService vectorStoreService;

    public VectorStoreController(VectorStoreService vectorStoreService) {
        this.vectorStoreService = vectorStoreService;
    }

    @PostMapping("rag-load")
    public void loadDataToVectorStore(@RequestBody String content) {
        vectorStoreService.addContent(content);
    }
}
EOF

Why separate controller? The /api/admin/rag-load endpoint is for administrative purposes (loading company documents) and will require different security permissions (ROLE_ADMIN) than user-facing chat endpoints (ROLE_USER).

Update ChatService with RAG

Add QuestionAnswerAdvisor to ChatService:

src/main/java/com/example/ai/agent/service/ChatService.java

    ...
    public ChatService(ChatMemoryService chatMemoryService,
                      VectorStore vectorStore,
                      ChatClient.Builder chatClientBuilder) {

        // Build ChatClient with RAG and memory
        this.chatClient = chatClientBuilder
                .defaultSystem(SYSTEM_PROMPT)
                .defaultAdvisors(QuestionAnswerAdvisor.builder(vectorStore).build())  // RAG for policies
                .build();

        this.chatMemoryService = chatMemoryService;
    }
    ...

Testing Knowledge

Let's test the RAG system with policy questions:

./mvnw spring-boot:test-run

In another terminal, load the policy document:

curl -X POST http://localhost:8080/api/admin/rag-load \
  -H "Content-Type: text/plain" \
  --data-binary @samples/policy-travel.md

Test with REST API:

# Test hotel budget question
curl -X POST http://localhost:8080/api/chat/message \
  -H "Content-Type: application/json" \
  -d '{"prompt": "What is the hotel budget for France?", "userId": "alice"}'
# Response: "Based on your company's travel policy, the hotel budget for France is:
#            Hotel Budget for France
#            **Maximum:** €130 per night"

✅ Success! The agent provides accurate policy information grounded in company documents.

You can also test in the UI at http://localhost:8080 - ask policy questions and see grounded responses.

Let's continue the chat:

curl -X POST http://localhost:8080/api/chat/message \
  -H "Content-Type: application/json" \
  -d '{"prompt": "I would like to travel to Paris next week from Monday to Friday. What is the weather forecast?", "userId": "alice"}'
# Response: "I don't know - I don't have access to the current information"

❌ Problem discovered: The agent can't perform actions and access real-time information like the current date and the weather forecast.

We'll address this limitation in the next part of the series! Stay tuned!

Cleanup

To stop the application, press Ctrl+C in the terminal where it's running.

The PostgreSQL container will continue running (due to withReuse(true)). If necessary, stop and remove it:

docker stop ai-agent-postgres
docker rm ai-agent-postgres

(Optional) To remove all data and start fresh:

docker volume prune

Commit Changes

git add .
git commit -m "Add RAG with travel policy"

Conclusion

In this post, we've added domain-specific knowledge to our AI agent through RAG:

PGVector for vector similarity search
Titan Embeddings for semantic understanding
QuestionAnswerAdvisor for automatic context retrieval
Grounded responses in company documents

The foundation we've built—memory and knowledge—is essential for any production AI agent. You now have the tools to create intelligent assistants that remember conversations and provide accurate, domain-specific information.

What's Next

Add access to real-time information to our AI agent. The agent will finally be able to answer questions like "What is the weather forecast?" by calling the tools and execute functions.

Learn More

Let's continue building intelligent Java applications with Spring AI!

A Practical Guide to Building AI Agents with Java and Spring AI - Part 2 - Add Memory

Yuriy Bezsonov — Tue, 11 Nov 2025 08:00:00 +0000

In Part 1 of this series, we built a functional AI agent using Java, Spring AI, and Amazon Bedrock. However, we discovered a critical limitation: the agent couldn't remember previous conversations. When we asked "What is my name?" after introducing ourselves, the agent had no recollection of our earlier interaction.

This lack of memory creates a frustrating user experience and limits the agent's usefulness for real-world applications. Imagine a customer service agent that forgets your issue every time you send a message, or a travel assistant that can't recall your preferences from previous conversations.

In this post, we'll enhance our AI agent with a three-tier memory architecture that provides both short-term conversation context and long-term user knowledge. We'll implement this incrementally, starting with persistent session memory, then adding conversation summaries, and finally user preferences—all backed by PostgreSQL for production reliability.

Overview of the Solution

What is Spring AI Chat Memory?

Spring AI provides Chat Memory components that automatically manage conversation history:

MessageWindowChatMemory: Maintains a sliding window of recent messages
Multiple Storage Options: InMemory, JDBC, Cassandra, MongoDB, Neo4j, Redis
Automatic Context Injection: Messages are automatically included in prompts to the AI model

The framework handles the complexity of managing conversation state, allowing you to focus on your application logic.

Choosing the Right Memory Store

Spring AI supports multiple memory storage backends:

Storage Type	Use Case	Pros	Cons
InMemory	Development, testing	Fast, simple setup	Lost on restart, not scalable
JDBC	Production apps with existing DB	Reliable, ACID compliant, familiar	Requires database
Redis	High-performance caching	Very fast, distributed	Additional infrastructure
Cassandra	Massive scale	Highly scalable	Complex setup
MongoDB	Document-oriented apps	Flexible schema	Additional infrastructure
Neo4j	Graph-based relationships	Rich relationship queries	Specialized use case

We chose JDBC (PostgreSQL) because:

✅ Most Spring Boot applications already use a relational database
✅ No additional infrastructure needed
✅ ACID compliance ensures data reliability
✅ Familiar SQL tooling for debugging and monitoring
✅ Easy migration to managed services like Amazon Aurora

Prerequisites

Before you start, ensure you have:

Completed Part 1 of this series with the working ai-agent application
Java 21 JDK installed (Amazon Corretto 21)
Maven 3.6+ installed
Docker Desktop running (for Testcontainers to manage PostgreSQL)
AWS CLI configured with access to Amazon Bedrock

Navigate to your project directory from Part 1:

cd ai-agent

PostgreSQL with Testcontainers

We need a database for persistent memory storage. Manually installing and configuring PostgreSQL is tedious and error-prone. We want something that "just works" for development and easily transitions to production.

Why Testcontainers?

Testcontainers automatically manages Docker containers for your application. With container reuse enabled, the PostgreSQL container persists between application restarts—perfect for development!

Benefits:

✅ No manual PostgreSQL installation
✅ Automatic startup and configuration
✅ Data persists between app restarts (with reuse)
✅ Easy migration to production databases

When deploying to production, switch to Amazon Aurora PostgreSQL or any managed database by setting environment variables:

export SPRING_DATASOURCE_URL=jdbc:postgresql://aurora-cluster.region.rds.amazonaws.com:5432/ai_agent_db
export SPRING_DATASOURCE_USERNAME=admin
export SPRING_DATASOURCE_PASSWORD=secure_password

No code changes needed!

Add Dependencies

Open pom.xml and add these dependencies to the <dependencies> section:

        <!-- JDBC Memory -->
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-starter-model-chat-memory-repository-jdbc</artifactId>
        </dependency>
        <dependency>
            <groupId>org.postgresql</groupId>
            <artifactId>postgresql</artifactId>
            <scope>runtime</scope>
        </dependency>

        <!-- Testcontainers -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-testcontainers</artifactId>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>org.testcontainers</groupId>
            <artifactId>postgresql</artifactId>
            <scope>test</scope>
        </dependency>

Configure Database Properties

Add PostgreSQL and JDBC memory configuration to src/main/resources/application.properties:

cat >> src/main/resources/application.properties << 'EOF'

# PostgreSQL Configuration
spring.datasource.url=jdbc:postgresql://localhost:5432/ai_agent_db
spring.datasource.username=postgres
spring.datasource.password=postgres
spring.datasource.driver-class-name=org.postgresql.Driver

# JDBC Memory Configuration
spring.ai.chat.memory.repository.jdbc.initialize-schema=always
EOF

Create TestAiAgentApplication

Create a test application that starts PostgreSQL automatically:

mkdir -p src/test/java/com/example/ai/agent
cat <<'EOF' > src/test/java/com/example/ai/agent/TestAiAgentApplication.java
package com.example.ai.agent;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.test.context.TestConfiguration;
import org.springframework.boot.testcontainers.service.connection.ServiceConnection;
import org.springframework.context.annotation.Bean;
import org.testcontainers.containers.PostgreSQLContainer;
import org.testcontainers.containers.wait.strategy.Wait;
import org.testcontainers.utility.DockerImageName;
import java.time.Duration;

/**
 * Test application that starts with Testcontainers PostgreSQL.
 * Run with: ./mvnw spring-boot:test-run
 *
 * Container reuse enabled: same container persists between restarts.
 * To enable reuse: add "testcontainers.reuse.enable=true" to ~/.testcontainers.properties
 */
public class TestAiAgentApplication {

    public static void main(String[] args) {
        SpringApplication
                .from(AiAgentApplication::main)
                .with(TestcontainersConfig.class)
                .run(args);
    }

    @TestConfiguration(proxyBeanMethods = false)
    static class TestcontainersConfig {
        @Bean
        @ServiceConnection  // Auto-configures DataSource from container
        PostgreSQLContainer<?> postgresContainer() {
            return new PostgreSQLContainer<>(DockerImageName.parse("pgvector/pgvector:pg16"))
                    .withDatabaseName("ai_agent_db")
                    .withUsername("postgres")
                    .withPassword("postgres")
                    .withStartupTimeout(Duration.ofMinutes(5))
                    .withCreateContainerCmdModifier(cmd -> cmd.withName("ai-agent-postgres"))
                    .withReuse(true)  // Reuse container between restarts
                    .waitingFor(Wait.defaultWaitStrategy());
        }
    }
}
EOF

To enable container reuse, ensure you have testcontainers.reuse.enable=true in ~/.testcontainers.properties:

echo "testcontainers.reuse.enable=true" >> ~/.testcontainers.properties

Test Testcontainers

Start the application with Testcontainers:

./mvnw spring-boot:test-run

You should see:

Creating container for image: pgvector/pgvector:pg16
Container pgvector/pgvector:pg16 is starting...
Container pgvector/pgvector:pg16 started
Started AiAgentApplication in X.XXX seconds

✅ Success! The PostgreSQL container is now running!

You can verify with:

docker ps | grep ai-agent-postgres

Stop the application (Ctrl+C) and next time when you start again — the same container is reused with data intact!

Commit Changes

git add .
git commit -m "Add Testcontainers for PostgreSQL"

Three-Tier Memory Architecture

Real applications need multiple types of memory for different purposes. Users expect the agent to remember who they are (preferences), what they've discussed (context), and the current conversation flow (session).

Why Three Tiers?

Each tier serves a distinct purpose:

Tier	Storage	Purpose	Example
Session	20 messages	Current conversation flow	"What did we just talk about?"
Context	10 summaries	Historical discussions	"What topics have we covered?"
Preferences	1 profile	Static user information	"Who is this user?"

This separation allows efficient memory management—session handles immediate context, context tracks decisions over time, and preferences store unchanging user details (name, email, dietary restrictions). All three tiers use JDBC for persistence across restarts.

Architecture Overview

User Question
     ↓
[Session Memory] ← JDBC/PostgreSQL (20 recent messages)
     ↓
[Context Memory] ← JDBC/PostgreSQL (10 conversation summaries)
     ↓
[Preferences Memory] ← JDBC/PostgreSQL (1 user profile)
     ↓
AI Model (Amazon Bedrock)
     ↓
Response

Create ChatMemoryService

Create the service that manages all three memory tiers:

mkdir -p src/main/java/com/example/ai/agent/service
cat <<'EOF' > src/main/java/com/example/ai/agent/service/ChatMemoryService.java
package com.example.ai.agent.service;

import org.springframework.ai.chat.client.ChatClient;
import org.springframework.ai.chat.memory.MessageWindowChatMemory;
import org.springframework.ai.chat.memory.repository.jdbc.JdbcChatMemoryRepository;
import org.springframework.ai.chat.memory.repository.jdbc.PostgresChatMemoryRepositoryDialect;
import org.springframework.ai.chat.messages.*;
import org.springframework.ai.chat.prompt.Prompt;
import reactor.core.publisher.Flux;
import org.springframework.stereotype.Service;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import javax.sql.DataSource;
import java.util.List;

@Service
public class ChatMemoryService {
    private static final Logger logger = LoggerFactory.getLogger(ChatMemoryService.class);
    private static final int MAX_SESSION_MESSAGES = 20;
    private static final int MAX_CONTEXT_SUMMARIES = 10;
    private static final int MAX_PREFERENCES = 1;

    // Three-tier memory: Session (recent), Context (summaries), Preferences (profile)
    private final MessageWindowChatMemory sessionMemory;
    private final MessageWindowChatMemory contextMemory;
    private final MessageWindowChatMemory preferencesMemory;
    private final ThreadLocal<String> currentUserId = ThreadLocal.withInitial(() -> "user1");

    public ChatMemoryService(DataSource dataSource) {
        // Single JDBC repository shared by all three memory tiers
        var jdbcRepository = JdbcChatMemoryRepository.builder()
            .dataSource(dataSource)
            .dialect(new PostgresChatMemoryRepositoryDialect())
            .build();

        this.sessionMemory = MessageWindowChatMemory.builder()
            .chatMemoryRepository(jdbcRepository)
            .maxMessages(MAX_SESSION_MESSAGES)
            .build();

        this.contextMemory = MessageWindowChatMemory.builder()
            .chatMemoryRepository(jdbcRepository)
            .maxMessages(MAX_CONTEXT_SUMMARIES)
            .build();

        this.preferencesMemory = MessageWindowChatMemory.builder()
            .chatMemoryRepository(jdbcRepository)
            .maxMessages(MAX_PREFERENCES)
            .build();
    }

    public Flux<String> callWithMemory(ChatClient chatClient, String prompt) {
        String conversationId = getCurrentConversationId();

        // 1. Auto-load previous context on first message
        if (sessionMemory.get(conversationId).isEmpty()) {
            loadPreviousContext(conversationId, chatClient);
        }

        // 2. Add user message to session memory
        sessionMemory.add(conversationId, new UserMessage(prompt));

        // 3. Stream AI response with full conversation history
        StringBuilder fullResponse = new StringBuilder();
        return chatClient
                .prompt(new Prompt(sessionMemory.get(conversationId)))
                .stream()
                .content()
                .doOnNext(fullResponse::append)
                .doOnComplete(() -> {
                    // 4. Save complete response to session memory
                    String responseText = fullResponse.toString();
                    if (!responseText.isEmpty()) {
                        sessionMemory.add(conversationId, new AssistantMessage(responseText));
                        logger.info("Saved response to memory: {} chars", responseText.length());
                    }
                });
    }

    private void loadPreviousContext(String conversationId, ChatClient chatClient) {
        logger.info("Loading previous context for: {}", conversationId);

        // 1. Load preferences (userId_preferences) and context (userId_context)
        List<Message> preferences = preferencesMemory.get(conversationId + "_preferences");
        String preferencesText = preferences.isEmpty() ? "" : preferences.get(0).getText();
        List<Message> summaries = contextMemory.get(conversationId + "_context");

        if (summaries.isEmpty() && preferencesText.isEmpty()) {
            logger.info("No previous context found");
            return;
        }

        logger.info("Found {} summaries, {} preferences", summaries.size(), preferences.isEmpty() ? 0 : 1);

        // 2. Combine preferences and summaries
        StringBuilder contextBuilder = new StringBuilder();
        if (!preferencesText.isEmpty()) {
            contextBuilder.append("User Preferences:\n").append(preferencesText).append("\n\n");
        }
        if (!summaries.isEmpty()) {
            contextBuilder.append("Previous Conversations:\n");
            summaries.forEach(msg -> contextBuilder.append(msg.getText()).append("\n\n"));
        }

        // 3. Summarize combined context with AI
        var chatResponse = chatClient.prompt()
            .user("Summarize this user information concisely:\n\n" + contextBuilder)
            .call()
            .chatResponse();

        String contextSummary = (chatResponse != null &&
            chatResponse.getResult() != null &&
            chatResponse.getResult().getOutput() != null)
            ? chatResponse.getResult().getOutput().getText()
            : null;

        if (contextSummary == null || contextSummary.isEmpty()) {
            logger.warn("Failed to generate context summary");
            return;
        }

        // 4. Add context as system message to session memory
        String contextMessage = String.format(
            "You are continuing a conversation with this user. Here is what you know:\n\n%s\n\n" +
            "Use this information to provide personalized responses.",
            contextSummary
        );
        sessionMemory.add(conversationId, new SystemMessage(contextMessage));
        logger.info("Loaded context summary");
    }

    // Getters and setters
    public MessageWindowChatMemory getSessionMemory() {
        return sessionMemory;
    }

    public MessageWindowChatMemory getContextMemory() {
        return contextMemory;
    }

    public MessageWindowChatMemory getPreferencesMemory() {
        return preferencesMemory;
    }

    public void setCurrentUserId(String userId) {
        this.currentUserId.set(userId.toLowerCase());
    }

    public String getCurrentConversationId() {
        return currentUserId.get();
    }
}
EOF

Update ChatService

Update ChatService to use memory:

src/main/java/com/example/ai/agent/service/ChatService.java

    ...
    private final ChatMemoryService chatMemoryService;

    public ChatService(ChatMemoryService chatMemoryService,
                      ChatClient.Builder chatClientBuilder) {
        this.chatClient = chatClientBuilder
                .defaultSystem(SYSTEM_PROMPT)
                .build();

        this.chatMemoryService = chatMemoryService;
    }

    public Flux<String> processChat(String prompt) {
        logger.info("Processing chat: '{}'", prompt);
        try {
            return chatMemoryService.callWithMemory(chatClient, prompt);
        } catch (Exception e) {
            logger.error("Error processing chat", e);
            return Flux.just("I don't know - there was an error processing your request.");
        }
    }
    ...

Conversation Summary

Session memory holds 20 recent messages, but long conversations exceed this limit. We need to summarize conversations and extract two types of information:

Context: What was discussed, decisions made, topics covered
Preferences: Who the user is, their preferences, static information

Why Separate Context and Preferences?

Context changes: Each conversation adds new topics and decisions
Preferences persist: User's name, email, dietary restrictions don't change that often
Efficient updates: Only update what changed, preserve what didn't

Create ConversationSummaryService

Create a service that extracts both context and preferences:

cat <<'EOF' > src/main/java/com/example/ai/agent/service/ConversationSummaryService.java
package com.example.ai.agent.service;

import org.springframework.ai.chat.client.ChatClient;
import org.springframework.ai.chat.messages.Message;
import org.springframework.ai.chat.messages.AssistantMessage;
import org.springframework.stereotype.Service;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import java.time.LocalDateTime;
import java.time.format.DateTimeFormatter;
import java.util.List;

@Service
public class ConversationSummaryService {
    private static final Logger logger = LoggerFactory.getLogger(ConversationSummaryService.class);
    private static final DateTimeFormatter TIMESTAMP_FORMAT = DateTimeFormatter.ofPattern("yyyyMMdd HHmmss");

    private final ChatMemoryService chatMemoryService;
    private final ChatClient chatClient;

    public ConversationSummaryService(ChatMemoryService chatMemoryService,
                                     ChatClient.Builder chatClientBuilder) {
        this.chatMemoryService = chatMemoryService;
        this.chatClient = chatClientBuilder.build();
    }

    public String summarizeAndSave(String conversationId) {
        logger.info("Summarizing conversation: {}", conversationId);

        // 1. Get session messages and existing preferences
        List<Message> messages = chatMemoryService.getSessionMemory().get(conversationId);
        if (messages.isEmpty()) {
            return "No conversation to summarize";
        }

        List<Message> existingPrefs = chatMemoryService.getPreferencesMemory().get(conversationId + "_preferences");
        String existingPrefsText = existingPrefs.isEmpty() ? "" : existingPrefs.get(0).getText();

        // 2. Convert messages to text
        String messagesText = messages.stream()
            .filter(msg -> msg.getText() != null && !msg.getText().isEmpty())
            .map(msg -> msg.getMessageType() + ": " + msg.getText())
            .reduce((a, b) -> a + "\n" + b)
            .orElse("");

        if (messagesText.isEmpty()) {
            return "No valid conversation content to summarize";
        }

        logger.info("Summarizing {} characters", messagesText.length());

        // 3. Generate AI summary (preferences + context)
        String preferencesPrompt = existingPrefsText.isEmpty()
            ? "Extract static user information (name, email, preferences). If none, return empty."
            : "Merge preferences. Keep existing:\n" + existingPrefsText +
              "\nAdd new from conversation. Update only if explicitly changed. Keep existing if unchanged.";

        var chatResponse = chatClient.prompt()
            .user("Analyze this conversation and provide TWO separate summaries:\n\n" +
                  "PREFERENCES:\n" + preferencesPrompt + "\n\n" +
                  "CONTEXT:\n" +
                  "Summarize: topics discussed, questions asked, decisions made, pending items.\n" +
                  "DO NOT include: prices, dates, flight numbers, hotel names, policies.\n\n" +
                  "Output format:\n===PREFERENCES===\n[preferences]\n===CONTEXT===\n[context]\n\n" +
                  "Conversation:\n" + messagesText)
            .call()
            .chatResponse();

        String response = (chatResponse != null &&
            chatResponse.getResult() != null &&
            chatResponse.getResult().getOutput() != null)
            ? chatResponse.getResult().getOutput().getText()
            : null;

        if (response == null || response.trim().isEmpty()) {
            throw new RuntimeException("Failed to generate summary");
        }

        // 4. Parse preferences and context
        String preferences = extractSection(response, "===PREFERENCES===", "===CONTEXT===");
        String context = extractSection(response, "===CONTEXT===", null);

        if (context.isEmpty() && preferences.isEmpty()) {
            context = response; // Fallback: use full response as context
        }

        logger.info("Extracted preferences: {} chars, context: {} chars", preferences.length(), context.length());

        // 5. Save to memory tiers
        String timestamp = LocalDateTime.now().format(TIMESTAMP_FORMAT);

        if (!preferences.isEmpty()) {
            chatMemoryService.getPreferencesMemory()
                .add(conversationId + "_preferences", new AssistantMessage(preferences));
        }

        if (!context.isEmpty()) {
            chatMemoryService.getContextMemory()
                .add(conversationId + "_context", new AssistantMessage("[" + timestamp + "] " + context));
        }

        // 6. Clear session memory
        chatMemoryService.getSessionMemory().clear(conversationId);
        logger.info("Summary saved, session cleared");

        return formatSummaryResponse(timestamp, preferences, context);
    }

    private String extractSection(String response, String startMarker, String endMarker) {
        try {
            if (!response.contains(startMarker)) {
                return "";
            }
            int start = response.indexOf(startMarker) + startMarker.length();
            int end = endMarker != null && response.contains(endMarker)
                ? response.indexOf(endMarker)
                : response.length();
            return end > start ? response.substring(start, end).trim() : "";
        } catch (Exception e) {
            logger.warn("Failed to extract section: {}", startMarker, e);
            return "";
        }
    }

    private String formatSummaryResponse(String timestamp, String preferences, String context) {
        return "**Summary:** [" + timestamp + "]\n\n" +
               "**Preferences:**\n" + (preferences.isEmpty() ? "None" : preferences) +
               "\n\n**Context:**\n" + context;
    }
}
EOF

Update ChatController and WebViewController

Update ChatController to add multi-user support and the summarize endpoint:

cat > src/main/java/com/example/ai/agent/controller/ChatController.java <<'EOF'
package com.example.ai.agent.controller;

import com.example.ai.agent.service.ChatService;
import com.example.ai.agent.service.ChatMemoryService;
import com.example.ai.agent.service.ConversationSummaryService;
import org.springframework.http.MediaType;
import org.springframework.web.bind.annotation.*;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import reactor.core.publisher.Flux;
import java.security.Principal;

@RestController
@RequestMapping("api/chat")
public class ChatController {
    private static final Logger logger = LoggerFactory.getLogger(ChatController.class);

    private final ChatService chatService;
    private final ChatMemoryService chatMemoryService;
    private final ConversationSummaryService summaryService;

    public ChatController(ChatService chatService,
                         ChatMemoryService chatMemoryService,
                         ConversationSummaryService summaryService) {
        this.chatService = chatService;
        this.chatMemoryService = chatMemoryService;
        this.summaryService = summaryService;
    }

    @PostMapping(value = "message", produces = MediaType.APPLICATION_OCTET_STREAM_VALUE)
    public Flux<String> chat(@RequestBody ChatRequest request, Principal principal) {
        String userId = getUserId(request.userId(), principal);
        chatMemoryService.setCurrentUserId(userId);
        return chatService.processChat(request.prompt());
    }

    @PostMapping("summarize")
    public String summarize(@RequestBody(required = false) SummarizeRequest request, Principal principal) {
        try {
            String userId = getUserId(request != null ? request.userId() : null, principal);
            return summaryService.summarizeAndSave(userId);
        } catch (Exception e) {
            logger.error("Error summarizing conversation", e);
            return "Failed to summarize conversation. Please try again.";
        }
    }

    private String getUserId(String requestUserId, Principal principal) {
        // Production: use authenticated user from Spring Security
        if (principal != null) {
            return principal.getName().toLowerCase();
        }
        // Development: use provided userId or default
        return requestUserId != null ? requestUserId.toLowerCase() : "user1";
    }

    public record ChatRequest(String prompt, String userId) {}
    public record SummarizeRequest(String userId) {}
}
EOF

Update WebViewController to enable multi-user UI:

cat > src/main/java/com/example/ai/agent/controller/WebViewController.java <<'EOF'
package com.example.ai.agent.controller;

import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.ui.Model;
import org.springframework.beans.factory.annotation.Value;

@Controller
public class WebViewController {

    @Value("${ui.features.multi-user:true}")
    private boolean multiUserEnabled;

    @GetMapping("/")
    public String index(Model model) {
        model.addAttribute("multiUserEnabled", multiUserEnabled);
        return "chat";
    }
}
EOF

Test Complete Three-Tier Memory

Start the application:

./mvnw spring-boot:test-run

Test the complete flow with Alice:

# Alice introduces herself
curl -X POST http://localhost:8080/api/chat/message \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Hi, my name is Alice and my email is alice@example.com", "userId": "alice"}' \
  --no-buffer

# Alice shares travel plans
curl -X POST http://localhost:8080/api/chat/message \
  -H "Content-Type: application/json" \
  -d '{"prompt": "I am planning a trip to Paris next week for a conference", "userId": "alice"}' \
  --no-buffer

# Summarize Alice's conversation
curl -X POST http://localhost:8080/api/chat/summarize \
  -H "Content-Type: application/json" \
  -d '{"userId": "alice"}'

You should see output like:

**Summary:** [20251108 162743]

**Preferences:**
Name: Alice
Email: alice@example.com

**Context:**
Alice is planning a business conference trip to Paris next week. The assistant offered comprehensive travel assistance and asked for additional details including travel dates, conference venue location, accommodation status, departure city, expense reimbursement information, budget planning needs, travel preferences, and whether she needs recommendations or policy guidance. Alice has not yet provided responses to these questions, leaving multiple planning aspects pending.%

You can also test in the UI at http://localhost:8080 - use the "📝 Summarize" button and switch between users with the User ID field.

Test with Bob to verify multi-user isolation:

# Bob introduces himself
curl -X POST http://localhost:8080/api/chat/message \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Hi, my name is Bob and my email is bob@example.com", "userId": "bob"}' \
  --no-buffer

# Bob shares different travel plans
curl -X POST http://localhost:8080/api/chat/message \
  -H "Content-Type: application/json" \
  -d '{"prompt": "I need to book a flight to Tokyo for next month", "userId": "bob"}' \
  --no-buffer

# Summarize Bob's conversation
curl -X POST http://localhost:8080/api/chat/summarize \
  -H "Content-Type: application/json" \
  -d '{"userId": "bob"}'

Now test if Alice's agent remembers her information (not Bob's):

# Ask about Alice's email
curl -X POST http://localhost:8080/api/chat/message \
  -H "Content-Type: application/json" \
  -d '{"prompt": "What is my email address?", "userId": "alice"}' \
  --no-buffer
# Response: "Your email address is alice@example.com"

# Ask about Alice's travel plans
curl -X POST http://localhost:8080/api/chat/message \
  -H "Content-Type: application/json" \
  -d '{"prompt": "What are my recent travel plans?", "userId": "alice"}' \
  --no-buffer
# Response includes: Paris, conference, next week (NOT Tokyo)

✅ Success! All three memory tiers work together with proper user isolation!

Let's continue the chat:

curl -X POST http://localhost:8080/api/chat/message \
  -H "Content-Type: application/json" \
  -d '{"prompt": "What is the hotel budget for France?", "userId": "alice"}' \
  --no-buffer
# Response: "I don't have information about your specific hotel budget for France or your company's travel policy limits for French accommodations."

❌ Problem: The agent doesn't have access to company-specific knowledge like travel policies.

We'll address this in the next part of the series! Stay tuned!

Cleanup

To stop the application, press Ctrl+C in the terminal where it's running.

The PostgreSQL container will continue running (due to withReuse(true)). If necessary, stop and remove it:

docker stop ai-agent-postgres
docker rm ai-agent-postgres

(Optional) To remove all data and start fresh:

docker volume prune

Commit Changes

git add .
git commit -m "Add conversation summarization with context and preferences"

Conclusion

In this post, we've enhanced our AI agent with a production-ready three-tier memory system:

Session Memory: 20 recent messages persisted in PostgreSQL
Context Memory: 10 conversation summaries with timestamps
Preferences Memory: Long-term user profile information
Auto-load: Previous context loaded automatically on first message
Multi-user support: Isolated conversations per user
AI-powered summarization: Extracts both context and preferences
Testcontainers: Zero-configuration PostgreSQL for development

The three-tier memory architecture provides the foundation for personalized, context-aware AI agents that remember both who users are and what they've discussed.

What's Next

Add knowledge to our AI agent. The agent will finally be able to answer questions like "What is the hotel budget for France?" by searching through travel and expense policies.

Learn More

Let's continue building intelligent Java applications with Spring AI!

A Practical Guide to Building AI Agents With Java and Spring AI - Part 1 - Create an AI Agent

Yuriy Bezsonov — Tue, 04 Nov 2025 13:18:03 +0000

Building AI-powered applications has become increasingly important for modern Java developers. With the rise of large language models and AI services, integrating intelligent capabilities into Java applications is no longer a luxury — it's a necessity for staying competitive.

Spring AI makes this integration seamless by providing a unified framework for building AI-powered applications with Java. Combined with Amazon Bedrock, developers can create sophisticated AI agents that leverage state-of-the-art foundation models without managing complex infrastructure.

In this post, I'll guide you through creating your first AI agent using Java and Spring AI, connected to Amazon Bedrock. We'll build a complete application with both REST API and web interface, demonstrating how to integrate AI capabilities into your Java applications.

Overview of the Solution

What is Spring AI?

Spring AI is a framework that brings the familiar Spring programming model to AI applications. It provides:

Unified API: A consistent interface for working with different AI models and providers
Seamless Integration: Native Spring Boot integration with auto-configuration
Multiple Providers: Support for OpenAI, Azure OpenAI, Amazon Bedrock, Ollama, and more
Advanced Features: Built-in support for RAG (Retrieval Augmented Generation), function calling, and chat memory
Production Ready: Observability, error handling, and resilience patterns

The framework abstracts the complexity of working with different AI providers, allowing you to focus on building your application logic rather than dealing with API specifics.

What is Amazon Bedrock?

Amazon Bedrock is a fully managed service that provides access to high-performing foundation models from leading AI companies including Anthropic, Meta, Stability AI, and Amazon's own models. Key benefits include:

No Infrastructure Management: Serverless architecture with automatic scaling
Multiple Models: Access to various foundation models through a single API
Security & Privacy: Your data stays within your AWS account
Cost Effective: Pay only for what you use with no upfront commitments

We'll create a Spring Boot application that demonstrates the core concepts of building AI agents.

The application will include:

Spring Boot web application with Thymeleaf templates
REST API for chat interactions
Integration with Amazon Bedrock via Spring AI
Streaming responses for better user experience

Prerequisites

Before you start, ensure you have:

Java 21 JDK installed (we'll use Amazon Corretto 21)
Maven 3.6+ installed
AWS CLI configured with appropriate permissions for Amazon Bedrock
Access to Amazon Bedrock models in your AWS account

The AI Agent

Context

We'll build a complete Spring Boot application that demonstrates the core concepts of building AI agents. The application will include both a REST API for programmatic access and a web interface for interactive testing.

Use Spring Initializer

We'll use Spring Initializer to bootstrap our project with the necessary dependencies:

curl https://start.spring.io/starter.zip \
  -d type=maven-project \
  -d language=java \
  -d bootVersion=3.5.7 \
  -d baseDir=ai-agent \
  -d groupId=com.example \
  -d artifactId=ai-agent \
  -d name=ai-agent \
  -d description="AI Agent with Spring AI and Amazon Bedrock" \
  -d packageName=com.example.ai.agent \
  -d packaging=jar \
  -d javaVersion=21 \
  -d dependencies=spring-ai-bedrock-converse,web,thymeleaf,actuator,devtools \
  -o ai-agent.zip

unzip ai-agent.zip
cd ai-agent

Add a Git repository to the project to track changes

git init -b main
git add .
git commit -m "Initialize the AI agent"

Configure Amazon Bedrock Integration

Create the application configuration in src/main/resources/application.properties:

cat >> src/main/resources/application.properties << 'EOF'

# Simplified logging pattern - only show the message
logging.pattern.console=%msg%n

# Debugging
logging.level.org.springframework.ai=DEBUG
spring.ai.chat.observations.log-completion=true
spring.ai.chat.observations.include-error-logging=true
spring.ai.tools.observations.include-content=true

# Thymeleaf Configuration
spring.thymeleaf.cache=false
spring.thymeleaf.prefix=classpath:/templates/
spring.thymeleaf.suffix=.html

# Amazon Bedrock Configuration
spring.ai.bedrock.aws.region=us-east-1
spring.ai.bedrock.converse.chat.options.max-tokens=10000
spring.ai.bedrock.converse.chat.options.model=global.anthropic.claude-sonnet-4-20250514-v1:0
EOF

The most important part of the properties is the GenAI model which we are going to use.
We're using Claude Sonnet 4 via Amazon Bedrock's cross-region inference profile.

Model ID Format:

global.anthropic.claude-sonnet-4-20250514-v1:0 - Cross-region inference profile
anthropic.claude-sonnet-4-20250514-v1:0 - Region-specific model

Why Cross-Region Inference Profiles?

Amazon Bedrock offers cross-region inference profiles that provide:

Higher Availability: Automatically routes requests across multiple AWS regions
Better Throughput: Distributes load to avoid throttling
Lower Latency: Routes to the nearest available region
Same Pricing: No additional cost compared to single-region access

Start with Claude Sonnet 4 using the global.* prefix for the best experience. You can always switch models by changing the configuration without code changes.

Create the Chat Service

The ChatClient interface is the core abstraction in Spring AI that provides:

Unified API: Works with different AI model providers without code changes
Streaming Support: Real-time response streaming for better user experience
Prompt Management: Built-in support for structured prompts and templates
Response Handling: Consistent response format across different models

Key methods include:

call(Prompt prompt): Synchronous response
stream(Prompt prompt): Streaming response
generate(List<Prompt> prompts): Batch processing

Create a service to handle chat interactions with the AI model:

mkdir -p src/main/java/com/example/ai/agent/service
cat <<'EOF' > src/main/java/com/example/ai/agent/service/ChatService.java
package com.example.ai.agent.service;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.stereotype.Service;
import reactor.core.publisher.Flux;

import org.springframework.ai.chat.client.ChatClient;

@Service
public class ChatService {
    private static final Logger logger = LoggerFactory.getLogger(ChatService.class);

    private final ChatClient chatClient;

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

    public Flux<String> processChat(String prompt) {
        logger.info("Processing streaming chat request - prompt: '{}'", prompt);
        try {
            return chatClient
                .prompt().user(prompt)
                .stream()
                .content();
        } catch (Exception e) {
            logger.error("Error processing streaming chat request", e);
            return Flux.just("I don't know - there was an error processing your request.");
        }
    }
}
EOF

Create the Chat Controller

Create the REST controller that handles chat interactions:

mkdir -p src/main/java/com/example/ai/agent/controller
cat <<'EOF' > src/main/java/com/example/ai/agent/controller/ChatController.java
package com.example.ai.agent.controller;

import com.example.ai.agent.service.ChatService;
import org.springframework.http.MediaType;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import reactor.core.publisher.Flux;

@RestController
@RequestMapping("api/chat")
public class ChatController {
    private final ChatService chatService;

    public ChatController(ChatService chatService) {
        this.chatService = chatService;
    }

    @PostMapping(value = "message", produces = MediaType.APPLICATION_OCTET_STREAM_VALUE)
    public Flux<String> chat(@RequestBody ChatRequest request) {
        return chatService.processChat(request.prompt());
    }

    public record ChatRequest(String prompt) {}
}
EOF

Create the Web Controller

Create a controller to serve the web interface:

cat <<'EOF' > src/main/java/com/example/ai/agent/controller/WebViewController.java
package com.example.ai.agent.controller;

import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.GetMapping;

@Controller
public class WebViewController {
    @GetMapping("/")
    public String index() {
        return "chat";
    }
}
EOF

Create the Web Interface

Create a modern chat interface using Thymeleaf and Tailwind CSS:

cat <<'EOF' > src/main/resources/templates/chat.html
<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
    <!-- ========== BASE: Core Dependencies ========== -->
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>AI Agent</title>
    <script src="https://cdn.tailwindcss.com"></script>
    <script src="https://cdn.jsdelivr.net/npm/marked@9.1.2/marked.min.js"></script>
    <script>
        tailwind.config = { darkMode: 'class' }
    </script>
</head>
<body class="bg-white dark:bg-gray-900 min-h-screen text-gray-800 dark:text-slate-200 transition-colors duration-300">
    <div class="container mx-auto px-4 py-8">
        <!-- ========== BASE: Header ========== -->
        <header class="mb-8">
            <div class="flex justify-between items-center">
                <h1 class="text-3xl font-bold text-indigo-500">🤖 AI Agent</h1>
                <div class="flex items-center gap-2">
                    <!-- MEMORY: Multi-user Controls -->
                    <div th:if="${multiUserEnabled}" class="flex items-center gap-2">
                        <label for="userIdInput" class="text-sm text-gray-500 dark:text-slate-400">User:</label>
                        <input type="text" id="userIdInput" value="user1"
                               class="bg-white dark:bg-gray-900 border border-gray-200 dark:border-gray-700 px-3 py-1 rounded text-sm focus:outline-none focus:ring-2 focus:ring-indigo-500 text-gray-800 dark:text-slate-200 w-32">
                        <button id="summarizeBtn" class="bg-purple-600 text-white px-4 py-2 rounded hover:bg-purple-700 transition">
                            📝 Summarize
                        </button>
                    </div>
                    <!-- BASE: Dark Mode Toggle -->
                    <button id="themeToggle" class="bg-indigo-500 text-white px-4 py-2 rounded hover:bg-indigo-600 transition">
                        🌙 Dark
                    </button>
                </div>
            </div>
            <p class="text-gray-500 dark:text-slate-400 mt-2">Chat with our AI Agent to help you with your questions!</p>
        </header>

        <!-- ========== BASE: Chat Container ========== -->
        <div class="bg-slate-50 dark:bg-gray-800 rounded-xl shadow-lg p-6 chat-container border border-gray-200 dark:border-gray-700 flex flex-col">
            <!-- BASE: Message Container -->
            <div class="message-container flex-grow mb-4 bg-white dark:bg-gray-900 rounded-lg p-4" id="messageContainer">
                <div class="flex mb-4">
                    <div class="w-10 h-10 rounded-full bg-indigo-500 bg-opacity-30 flex items-center justify-center mr-3 flex-shrink-0">
                        <span class="text-lg">🤖</span>
                    </div>
                    <div class="message-bubble-ai rounded-lg p-3 max-w-3xl">
                        <p>Welcome to the AI Agent! How can I help you today?</p>
                    </div>
                </div>
            </div>

            <!-- BASE: Input Area -->
            <div class="border-t border-gray-200 dark:border-gray-700 pt-4 mt-auto">
                <form id="chatForm" class="flex w-full">
                    <!-- UPLOAD: File Input and Button -->
                    <input type="file" id="fileInput" class="hidden" accept=".jpg,.jpeg,.png">
                    <button th:if="${multiModalEnabled}" type="button" id="fileButton" class="bg-indigo-500 text-white px-4 py-3 rounded-l-lg hover:bg-indigo-600 transition flex items-center justify-center">
                        📎
                    </button>
                    <!-- BASE: Text Input -->
                    <input type="text" id="userInput" th:class="${multiModalEnabled} ? 'flex-grow bg-white dark:bg-gray-900 border border-gray-200 dark:border-gray-700 px-4 py-3 focus:outline-none focus:ring-2 focus:ring-indigo-500 text-gray-800 dark:text-slate-200' : 'flex-grow bg-white dark:bg-gray-900 border border-gray-200 dark:border-gray-700 px-4 py-3 rounded-l-lg focus:outline-none focus:ring-2 focus:ring-indigo-500 text-gray-800 dark:text-slate-200'" placeholder="Please ask your question...">
                    <!-- BASE: Send Button -->
                    <button type="submit" class="bg-indigo-500 text-white px-6 py-3 rounded-r-lg hover:bg-indigo-600 transition">Send</button>
                </form>
            </div>
        </div>
    </div>

    <!-- ========== UPLOAD: Image Modal ========== -->
    <div id="imageModal" class="image-modal">
        <span class="close">&times;</span>
        <img id="modalImage" src="" alt="">
    </div>

    <script>
        document.addEventListener('DOMContentLoaded', function() {
            // ========== BASE: Initialize Marked.js ==========
            marked.setOptions({
                gfm: true,
                tables: true,
                breaks: true
            });

            // ========== BASE: DOM Elements ==========
            const messageContainer = document.getElementById('messageContainer');
            const chatForm = document.getElementById('chatForm');
            const userInput = document.getElementById('userInput');
            const themeToggle = document.getElementById('themeToggle');
            const fileInput = document.getElementById('fileInput');
            const fileButton = document.getElementById('fileButton');

            // ========== BASE: Chat Form Submit ==========
            chatForm.addEventListener('submit', async function(e) {
                e.preventDefault();
                const message = userInput.value.trim();
                if (!message) return;

                addMessage(message, 'user');
                userInput.value = '';

                try {
                    const loadingId = showLoading();
                    const userIdInput = document.getElementById('userIdInput');
                    const response = await fetch('api/chat/message', {
                        method: 'POST',
                        headers: {
                            'Content-Type': 'application/json',
                            'Accept': 'application/octet-stream'
                        },
                        body: JSON.stringify({
                            prompt: message,
                            userId: userIdInput ? userIdInput.value : null,
                            fileBase64: currentFileBase64 || null,
                            fileName: currentFileName || null
                        })
                    });

                    if (!response.ok) throw new Error('Failed to get response');
                    removeLoading(loadingId);

                    // Handle streaming response
                    const reader = response.body.getReader();
                    const decoder = new TextDecoder();
                    let fullResponse = '';
                    let messageDiv = null;

                    while (true) {
                        const { done, value } = await reader.read();
                        if (done) break;

                        const chunk = decoder.decode(value, { stream: true });
                        fullResponse += chunk;

                        if (!messageDiv) {
                            messageDiv = createStreamingMessage();
                        }
                        updateStreamingMessage(messageDiv, fullResponse);
                    }
                } catch (error) {
                    removeLoading(loadingId);
                    console.error('Error:', error);
                    addMessage('Sorry, I encountered an error. Please try again.', 'ai');
                }
            });

            // ========== BASE: Message Functions ==========
            function createStreamingMessage() {
                const messageDiv = document.createElement('div');
                messageDiv.className = 'flex mb-4';
                messageDiv.innerHTML = `
                    <div class="w-10 h-10 rounded-full bg-indigo-500 bg-opacity-30 flex items-center justify-center mr-3 flex-shrink-0">
                        <span class="text-lg">🤖</span>
                    </div>
                    <div class="message-bubble-ai rounded-lg p-3 max-w-4xl ai-response">
                        <button class="copy-button" data-copy-text="">📋</button>
                        <div class="streaming-content"></div>
                    </div>
                `;
                messageContainer.appendChild(messageDiv);
                messageContainer.scrollTop = messageContainer.scrollHeight;
                return messageDiv;
            }

            function updateStreamingMessage(messageDiv, content) {
                const contentDiv = messageDiv.querySelector('.streaming-content');
                const copyButton = messageDiv.querySelector('.copy-button');
                const renderedContent = marked.parse(content);
                contentDiv.innerHTML = renderedContent;
                copyButton.setAttribute('data-copy-text', escapeHtml(content));
                messageContainer.scrollTop = messageContainer.scrollHeight;
            }

            function addMessage(content, sender) {
                const messageDiv = document.createElement('div');
                messageDiv.className = 'flex mb-4';

                if (sender === 'user') {
                    messageDiv.innerHTML = `
                        <div class="ml-auto flex">
                            <div class="message-bubble-user rounded-lg p-3 max-w-3xl">
                                <button class="copy-button" data-copy-text="${escapeHtml(content)}">📋</button>
                                <p>${escapeHtml(content)}</p>
                            </div>
                            <div class="w-10 h-10 rounded-full bg-blue-500 bg-opacity-30 flex items-center justify-center ml-3 flex-shrink-0">
                                <span class="text-lg">👤</span>
                            </div>
                        </div>
                    `;
                } else {
                    const renderedContent = marked.parse(content);
                    messageDiv.innerHTML = `
                        <div class="w-10 h-10 rounded-full bg-indigo-500 bg-opacity-30 flex items-center justify-center mr-3 flex-shrink-0">
                            <span class="text-lg">🤖</span>
                        </div>
                        <div class="message-bubble-ai rounded-lg p-3 max-w-4xl ai-response">
                            <button class="copy-button" data-copy-text="${escapeHtml(content)}">📋</button>
                            ${renderedContent}
                        </div>
                    `;
                }

                messageContainer.appendChild(messageDiv);
                messageContainer.scrollTop = messageContainer.scrollHeight;
            }

            // ========== BASE: Loading Indicator ==========
            function showLoading() {
                const loadingId = 'loading-' + Date.now();
                const loadingDiv = document.createElement('div');
                loadingDiv.id = loadingId;
                loadingDiv.className = 'flex mb-4';
                loadingDiv.innerHTML = `
                    <div class="w-10 h-10 rounded-full bg-indigo-500 bg-opacity-30 flex items-center justify-center mr-3 flex-shrink-0">
                        <span class="text-lg">🤖</span>
                    </div>
                    <div class="message-bubble-ai rounded-lg p-3">
                        <div class="flex space-x-2">
                            <div class="w-2 h-2 bg-indigo-500 rounded-full animate-bounce"></div>
                            <div class="w-2 h-2 bg-indigo-500 rounded-full animate-bounce" style="animation-delay: 0.2s"></div>
                            <div class="w-2 h-2 bg-indigo-500 rounded-full animate-bounce" style="animation-delay: 0.4s"></div>
                        </div>
                    </div>
                `;
                messageContainer.appendChild(loadingDiv);
                messageContainer.scrollTop = messageContainer.scrollHeight;
                return loadingId;
            }

            function removeLoading(loadingId) {
                const loadingDiv = document.getElementById(loadingId);
                if (loadingDiv) loadingDiv.remove();
            }

            // ========== BASE: Utility Functions ==========
            function escapeHtml(unsafe) {
                return unsafe
                    .replace(/&/g, "&amp;")
                    .replace(/</g, "&lt;")
                    .replace(/>/g, "&gt;")
                    .replace(/"/g, "&quot;")
                    .replace(/'/g, "&#039;");
            }

            function copyToClipboard(text) {
                navigator.clipboard.writeText(text).then(function() {
                    console.log('Text copied to clipboard');
                }).catch(function(err) {
                    console.error('Failed to copy text: ', err);
                });
            }

            messageContainer.addEventListener('click', function(e) {
                if (e.target.classList.contains('copy-button')) {
                    const textToCopy = e.target.getAttribute('data-copy-text');
                    copyToClipboard(textToCopy);
                }
            });

            // ========== BASE: Dark Mode Toggle ==========
            themeToggle.addEventListener('click', function() {
                const html = document.documentElement;
                html.classList.toggle('dark');
                themeToggle.innerHTML = html.classList.contains('dark') ? '☀️ Light' : '🌙 Dark';
            });

            // ========== MEMORY: Summarize Button ==========
            const summarizeBtn = document.getElementById('summarizeBtn');
            if (summarizeBtn) {
                summarizeBtn.addEventListener('click', async function() {
                    try {
                        const userId = document.getElementById('userIdInput').value;
                        const loadingId = showLoading();

                        const response = await fetch('api/chat/summarize', {
                            method: 'POST',
                            headers: { 'Content-Type': 'application/json' },
                            body: JSON.stringify({ userId: userId })
                        });

                        removeLoading(loadingId);
                        if (!response.ok) throw new Error('Failed to summarize');
                        const summary = await response.text();
                        addMessage('📝 ' + summary, 'ai');
                    } catch (error) {
                        console.error('Error summarizing:', error);
                        addMessage('Failed to summarize conversation. Please try again.', 'ai');
                    }
                });
            }

            // ========== UPLOAD: File State ==========
            let currentFileBase64 = null;
            let currentFileName = null;

            // ========== UPLOAD: File Upload Handler ==========
            if (fileButton) {
                fileButton.addEventListener('click', function() {
                    fileInput.click();
                });
            }

            if (fileInput) {
                fileInput.addEventListener('change', async function(e) {
                    const file = e.target.files[0];
                    if (file) {
                        try {
                            currentFileBase64 = await fileToBase64(file);
                            currentFileName = file.name;
                            addImageMessage(file);
                            await sendDocumentAnalysis();
                        } catch (error) {
                            console.error('Error processing file:', error);
                            addMessage('Error processing file. Please try again.', 'ai');
                        }
                    }
                });
            }

            function addImageMessage(file) {
                const messageDiv = document.createElement('div');
                messageDiv.className = 'flex mb-4';
                const imageUrl = URL.createObjectURL(file);
                messageDiv.innerHTML = `
                    <div class="ml-auto flex">
                        <div class="message-bubble-user rounded-lg p-3 max-w-3xl">
                            <button class="copy-button" data-copy-text="File attached: ${file.name}">📋</button>
                            <p class="mb-2">📎 File attached: ${file.name}</p>
                            <img src="${imageUrl}" alt="${file.name}" class="max-w-full max-h-64 rounded border border-gray-200 dark:border-gray-700 cursor-pointer hover:opacity-80 transition" onclick="openImageModal('${imageUrl}')" />
                        </div>
                        <div class="w-10 h-10 rounded-full bg-blue-500 bg-opacity-30 flex items-center justify-center ml-3 flex-shrink-0">
                            <span class="text-lg">👤</span>
                        </div>
                    </div>
                `;
                messageContainer.appendChild(messageDiv);
                messageContainer.scrollTop = messageContainer.scrollHeight;
            }

            async function sendDocumentAnalysis() {
                try {
                    const loadingId = showLoading();
                    const response = await fetch('api/chat/message', {
                        method: 'POST',
                        headers: { 'Content-Type': 'application/json' },
                        body: JSON.stringify({
                            prompt: "",
                            fileBase64: currentFileBase64,
                            fileName: currentFileName
                        })
                    });
                    removeLoading(loadingId);
                    if (!response.ok) throw new Error('Failed to analyze document');

                    const reader = response.body.getReader();
                    const decoder = new TextDecoder();
                    const messageId = createStreamingMessage();
                    let fullText = '';

                    while (true) {
                        const { done, value } = await reader.read();
                        if (done) break;
                        const chunk = decoder.decode(value, { stream: true });
                        fullText += chunk;
                        updateStreamingMessage(messageId, fullText);
                    }

                    currentFileBase64 = null;
                    currentFileName = null;
                    fileInput.value = '';
                } catch (error) {
                    console.error('Error analyzing document:', error);
                    addMessage('I don\'t know - there was an error analyzing the document.', 'ai');
                    currentFileBase64 = null;
                    currentFileName = null;
                    fileInput.value = '';
                }
            }

            function fileToBase64(file) {
                return new Promise((resolve, reject) => {
                    const reader = new FileReader();
                    reader.readAsDataURL(file);
                    reader.onload = () => resolve(reader.result.split(',')[1]);
                    reader.onerror = error => reject(error);
                });
            }

            // ========== UPLOAD: Image Modal ==========
            window.openImageModal = function(imageSrc) {
                const modal = document.getElementById('imageModal');
                const modalImg = document.getElementById('modalImage');
                modal.style.display = 'block';
                modalImg.src = imageSrc;
            }

            const imageModal = document.getElementById('imageModal');
            if (imageModal) {
                imageModal.addEventListener('click', function(e) {
                    if (e.target === this || e.target.className === 'close') {
                        this.style.display = 'none';
                    }
                });
            }
        });
    </script>

    <!-- ========== STYLES ========== -->
    <style>
        /* ========== BASE: Layout ========== */
        .chat-container {
            height: calc(100vh - 180px);
        }
        .message-container {
            height: calc(100vh - 280px);
            overflow-y: auto;
        }

        /* ========== BASE: Markdown Tables ========== */
        .ai-response table {
            width: 100%;
            border-collapse: collapse;
            margin: 1rem 0;
            border-radius: 8px;
            overflow: hidden;
            background: #ffffff;
            border: 1px solid #e5e7eb;
        }
        .dark .ai-response table {
            background: #1e293b !important;
            border: 1px solid #374151 !important;
        }
        .ai-response th {
            background: #6366f1 !important;
            color: white !important;
            padding: 12px;
            text-align: left;
            font-weight: 600;
        }
        .ai-response td {
            padding: 10px 12px;
            border-bottom: 1px solid #e5e7eb;
            color: #111827 !important;
            background: #ffffff !important;
            font-weight: 600 !important;
        }
        .dark .ai-response td {
            border-bottom: 1px solid #374151 !important;
            color: #f9fafb !important;
            background: #1e293b !important;
        }
        .ai-response tr:last-child td {
            border-bottom: none;
        }
        .ai-response tr:nth-child(even) td {
            background: #f1f5f9 !important;
            color: #111827 !important;
        }
        .dark .ai-response tr:nth-child(even) td {
            background: #334155 !important;
            color: #f9fafb !important;
        }

        /* BASE: Markdown Headings and Text */
        .ai-response h1, .ai-response h2, .ai-response h3 {
            color: #6366f1;
            margin: 1rem 0 0.5rem 0;
        }
        .ai-response strong {
            color: #111827 !important;
            font-weight: 700 !important;
        }
        .dark .ai-response strong {
            color: #f9fafb !important;
            font-weight: 700 !important;
        }
        .ai-response em {
            color: #6b7280;
        }
        .dark .ai-response em {
            color: #94a3b8;
        }
        .ai-response p {
            color: #1f2937;
        }
        .dark .ai-response p {
            color: #e2e8f0;
        }

        /* ========== BASE: Message Bubbles ========== */
        .message-bubble-ai {
            background: #ffffff;
            border: 1px solid #e5e7eb;
            color: #1f2937;
            position: relative;
        }
        .dark .message-bubble-ai {
            background: #1e293b !important;
            border: 1px solid #374151 !important;
            color: #e2e8f0 !important;
        }
        .message-bubble-user {
            background: #f3f4f6;
            border: 1px solid #e5e7eb;
            color: #1f2937;
            position: relative;
        }
        .dark .message-bubble-user {
            background: #1e293b !important;
            border: 1px solid #374151 !important;
            color: #e2e8f0 !important;
        }
        .message-bubble-ai p, .message-bubble-ai * {
            color: #1f2937 !important;
        }
        .dark .message-bubble-ai p, .dark .message-bubble-ai * {
            color: #e2e8f0 !important;
        }
        .message-bubble-user p, .message-bubble-user * {
            color: #1f2937 !important;
        }
        .dark .message-bubble-user p, .dark .message-bubble-user * {
            color: #e2e8f0 !important;
        }

        /* BASE: Copy Button */
        .copy-button {
            position: absolute;
            top: 8px;
            right: 8px;
            background: rgba(99, 102, 241, 0.8);
            color: white;
            border: none;
            border-radius: 4px;
            padding: 4px 8px;
            font-size: 12px;
            cursor: pointer;
            opacity: 0;
            transition: opacity 0.2s;
        }
        .copy-button:hover {
            background: rgba(99, 102, 241, 1);
        }
        .message-bubble-ai:hover .copy-button,
        .message-bubble-user:hover .copy-button {
            opacity: 1;
        }

        /* ========== UPLOAD: Image Modal ========== */
        .image-modal {
            display: none;
            position: fixed;
            z-index: 1000;
            left: 0;
            top: 0;
            width: 100%;
            height: 100%;
            background-color: rgba(0, 0, 0, 0.9);
        }
        .image-modal img {
            margin: auto;
            display: block;
            max-width: 90%;
            max-height: 90%;
            margin-top: 5%;
        }
        .image-modal .close {
            position: absolute;
            top: 15px;
            right: 35px;
            color: #f1f1f1;
            font-size: 40px;
            font-weight: bold;
            cursor: pointer;
        }
        .image-modal .close:hover {
            color: #bbb;
        }
    </style>
</body>
</html>
EOF

Running the Application

Configure AWS credentials in the terminal. The assumed role or user should have access to Amazon Bedrock models.

export AWS_REGION=us-east-1

Start the Application

./mvnw spring-boot:run

Test the Application

Test REST API

Open the new terminal and test the REST API with curl:

curl -X POST http://localhost:8080/api/chat/message \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Hi, my name is Alex. Who are you?"}'

✅ Success! The API responds with the AI agent's message.

Test Web Interface

Open your browser and navigate to http://localhost:8080 and try the same interaction:

Hi, my name is Alex. Who are you?

✅ Success! The AI agent responds, but its responses are generic.

❌ Problem: The agent lacks a specific persona and business context.

Let's fix this by adding an AI Agent Persona.

Stop the application with Ctrl+C.

Commit Changes

git add .
git commit -m "Create the AI agent"

System Prompt and Persona

The system prompt defines the AI agent's personality and behavior:

ChatService.java

    ...
    public static final String SYSTEM_PROMPT = """
        You are a helpful AI Agent for travel and expenses.

        Guidelines:
        1. Use markdown tables for structured data
        2. If unsure, say "I don't know"
        """;
    ...
            this.chatClient = chatClientBuilder
                .defaultSystem(SYSTEM_PROMPT)
                .build();
    ...

This gives the AI agent:

A specific business context (Travel and Expenses Agent)
Behavioral guidelines (helpful)
Honesty constraints (admit when it doesn't know something)

Test the Application

Test the AI agent with the persona using the Web UI:

Hi, my name is Alex. Who are you?

or the REST API:

curl -X POST http://localhost:8080/api/chat/message \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Hi, my name is Alex. Who are you?"}' \
  --no-buffer

✅ Success! The AI agent now has a persona aligned with our requirements!

Let's continue the chat:

What is my name?

❌ Problem: The AI agent doesn't remember our name, even though we provided it.

We'll fix this in the next part of the blog series! Stay tuned!

Cleanup

To stop the application, press Ctrl+C in the terminal where it's running.

Commit Changes

git add .
git commit -m "Add the Persona"

Conclusion

In this post, we've successfully created a complete AI agent application using Java and Spring AI with Amazon Bedrock integration:

Setting up a Spring Boot project with Spring AI dependencies
Configuring Amazon Bedrock integration
Creating REST APIs with streaming responses
Building a modern web interface with streaming chat
Implementing AI agent personas with system prompts

The application demonstrates the power of Spring AI's unified programming model, making it easy to integrate sophisticated AI capabilities into Java applications.

What's Next:

Add multi-tier memory to the AI Agent!

Learn More:

Let's continue building intelligent Java applications with Spring AI!