CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/maven-org-springframework-ai--spring-ai-model

Core model interfaces and abstractions for Spring AI framework providing portable API for chat, embeddings, images, audio, and tool calling across multiple AI providers

Overview
Eval results
Files

messages.mddocs/reference/

Message Types

Message abstractions for different conversation roles including UserMessage, SystemMessage, AssistantMessage, and ToolResponseMessage. Supports multi-modal content with text, images, and audio.

Capabilities

Message Interface

Base interface for all message types.

public interface Message {
    /**
     * Get the message type (USER, ASSISTANT, SYSTEM, TOOL).
     *
     * @return the message type
     */
    MessageType getMessageType();

    /**
     * Get the message text content.
     *
     * @return the text content
     */
    String getText();

    /**
     * Get message metadata.
     *
     * @return metadata map
     */
    Map<String, Object> getMetadata();

    /**
     * Create a copy of this message.
     * The copy will have the same content and metadata as the original.
     *
     * @return a new message instance with copied data
     */
    Message copy();
}

MediaContent Interface

Interface for messages that can contain media (images, audio, etc.).

public interface MediaContent {
    /**
     * Get the list of media attachments.
     *
     * @return list of media
     */
    List<Media> getMedia();
}

UserMessage

Message from the user to the AI model.

public class UserMessage extends AbstractMessage implements MediaContent {
    /**
     * Construct a UserMessage with text content.
     *
     * @param content the message text
     */
    public UserMessage(String content);

    /**
     * Construct a UserMessage from a resource file.
     *
     * @param resource the resource containing message text
     */
    public UserMessage(Resource resource);

    /**
     * Construct a UserMessage with text and media.
     *
     * @param content the message text
     * @param media the list of media attachments
     */
    public UserMessage(String content, List<Media> media);

    /**
     * Construct a UserMessage with text, media, and metadata.
     *
     * @param content the message text
     * @param media the list of media attachments
     * @param metadata the message metadata
     */
    public UserMessage(String content, List<Media> media, Map<String, Object> metadata);

    /**
     * Get the text content of this message.
     *
     * @return the text content
     */
    String getText();

    /**
     * Get the media attachments.
     *
     * @return list of media
     */
    List<Media> getMedia();

    /**
     * Create a copy of this message.
     *
     * @return a new copy
     */
    UserMessage copy();

    /**
     * Create a builder from this message for mutation.
     *
     * @return a builder initialized with this message's data
     */
    Builder mutate();

    /**
     * Create a new user message builder.
     *
     * @return a new builder
     */
    static Builder builder();

    /**
     * Builder for constructing UserMessage instances.
     */
    public static final class Builder {
        /**
         * Set the message content.
         *
         * @param content the message text
         * @return this builder
         */
        public Builder content(String content);

        /**
         * Set the media attachments.
         *
         * @param media the list of media
         * @return this builder
         */
        public Builder media(List<Media> media);

        /**
         * Set the message metadata.
         *
         * @param metadata the metadata map
         * @return this builder
         */
        public Builder metadata(Map<String, Object> metadata);

        /**
         * Build the UserMessage instance.
         *
         * @return the constructed UserMessage
         */
        public UserMessage build();
    }
}

SystemMessage

System instruction message that sets context or behavior for the AI model.

public class SystemMessage extends AbstractMessage {
    /**
     * Construct a SystemMessage with text content.
     *
     * @param content the message text
     */
    public SystemMessage(String content);

    /**
     * Construct a SystemMessage from a resource file.
     *
     * @param resource the resource containing message text
     */
    public SystemMessage(Resource resource);

    /**
     * Construct a SystemMessage with text and metadata.
     *
     * @param content the message text
     * @param metadata the message metadata
     */
    public SystemMessage(String content, Map<String, Object> metadata);

    /**
     * Get the text content of this message.
     *
     * @return the text content
     */
    String getText();

    /**
     * Create a copy of this message.
     *
     * @return a new copy
     */
    SystemMessage copy();

    /**
     * Create a builder from this message for mutation.
     *
     * @return a builder initialized with this message's data
     */
    Builder mutate();

    /**
     * Create a new system message builder.
     *
     * @return a new builder
     */
    static Builder builder();

    /**
     * Builder for constructing SystemMessage instances.
     */
    public static final class Builder {
        /**
         * Set the message content.
         *
         * @param content the message text
         * @return this builder
         */
        public Builder content(String content);

        /**
         * Set the message metadata.
         *
         * @param metadata the metadata map
         * @return this builder
         */
        public Builder metadata(Map<String, Object> metadata);

        /**
         * Build the SystemMessage instance.
         *
         * @return the constructed SystemMessage
         */
        public SystemMessage build();
    }
}

AssistantMessage

Message from the AI assistant, potentially containing tool calls.

public class AssistantMessage extends AbstractMessage implements MediaContent {
    /**
     * Construct an AssistantMessage with text content.
     *
     * @param content the message text
     */
    public AssistantMessage(String content);

    /**
     * Construct an AssistantMessage with text and metadata.
     *
     * @param content the message text
     * @param metadata the message metadata
     */
    public AssistantMessage(String content, Map<String, Object> metadata);

    /**
     * Construct an AssistantMessage with text, metadata, and tool calls.
     *
     * @param content the message text
     * @param metadata the message metadata
     * @param toolCalls the list of tool calls
     */
    public AssistantMessage(String content, Map<String, Object> metadata, List<ToolCall> toolCalls);

    /**
     * Construct an AssistantMessage with text, metadata, tool calls, and media.
     *
     * @param content the message text
     * @param metadata the message metadata
     * @param toolCalls the list of tool calls
     * @param media the list of media
     */
    public AssistantMessage(
        String content,
        Map<String, Object> metadata,
        List<ToolCall> toolCalls,
        List<Media> media
    );

    /**
     * Get the tool calls requested by the assistant.
     *
     * @return list of tool calls
     */
    List<ToolCall> getToolCalls();

    /**
     * Check if this message has tool calls.
     *
     * @return true if tool calls present
     */
    boolean hasToolCalls();

    /**
     * Get the media attachments.
     *
     * @return list of media
     */
    List<Media> getMedia();

    /**
     * Create a new assistant message builder.
     *
     * @return a new builder
     */
    static Builder builder();

    /**
     * Builder for constructing AssistantMessage instances.
     */
    public static final class Builder {
        /**
         * Set the message content.
         *
         * @param content the message text
         * @return this builder
         */
        public Builder content(String content);

        /**
         * Set the message metadata.
         *
         * @param metadata the metadata map
         * @return this builder
         */
        public Builder metadata(Map<String, Object> metadata);

        /**
         * Set the tool calls.
         *
         * @param toolCalls the list of tool calls
         * @return this builder
         */
        public Builder toolCalls(List<ToolCall> toolCalls);

        /**
         * Set the media attachments.
         *
         * @param media the list of media
         * @return this builder
         */
        public Builder media(List<Media> media);

        /**
         * Build the AssistantMessage instance.
         *
         * @return the constructed AssistantMessage
         */
        public AssistantMessage build();
    }
}

AssistantMessage.ToolCall

Represents a request to call a tool/function.

public record ToolCall(String id, String type, String name, String arguments) {
    /**
     * The unique identifier for this tool call.
     */
    public String id();

    /**
     * The type of tool call (e.g., "function").
     */
    public String type();

    /**
     * The name of the tool/function to call.
     */
    public String name();

    /**
     * The JSON-encoded arguments for the tool call.
     */
    public String arguments();
}

ToolResponseMessage

Message containing responses to tool/function calls.

public class ToolResponseMessage extends AbstractMessage {
    /**
     * Construct a ToolResponseMessage with responses.
     *
     * @param responses the list of tool responses
     */
    public ToolResponseMessage(List<ToolResponse> responses);

    /**
     * Construct a ToolResponseMessage with responses and metadata.
     *
     * @param responses the list of tool responses
     * @param metadata the message metadata
     */
    public ToolResponseMessage(List<ToolResponse> responses, Map<String, Object> metadata);

    /**
     * Get the tool responses.
     *
     * @return list of tool responses
     */
    List<ToolResponse> getResponses();

    /**
     * Create a new tool response message builder.
     *
     * @return a new builder
     */
    static Builder builder();

    /**
     * Builder for constructing ToolResponseMessage instances.
     */
    public static final class Builder {
        /**
         * Set the tool responses.
         *
         * @param responses the list of tool responses
         * @return this builder
         */
        public Builder responses(List<ToolResponse> responses);

        /**
         * Set the message metadata.
         *
         * @param metadata the metadata map
         * @return this builder
         */
        public Builder metadata(Map<String, Object> metadata);

        /**
         * Build the ToolResponseMessage instance.
         *
         * @return the constructed ToolResponseMessage
         */
        public ToolResponseMessage build();
    }
}

ToolResponseMessage.ToolResponse

Individual response to a tool call.

public record ToolResponse(String id, String name, String responseData) {
    /**
     * The ID of the tool call this responds to.
     */
    public String id();

    /**
     * The name of the tool that was called.
     */
    public String name();

    /**
     * The response data from the tool execution.
     */
    public String responseData();
}

AbstractMessage

Base class for message implementations providing common functionality.

public abstract class AbstractMessage implements Message {
    /**
     * Construct an AbstractMessage with text content.
     *
     * @param text the message text
     */
    protected AbstractMessage(String text);

    /**
     * Construct an AbstractMessage with text and metadata.
     *
     * @param text the message text
     * @param metadata the message metadata
     */
    protected AbstractMessage(String text, Map<String, Object> metadata);

    /**
     * Get the message text content.
     *
     * @return the text content
     */
    @Override
    public String getText();

    /**
     * Get message metadata.
     *
     * @return metadata map
     */
    @Override
    public Map<String, Object> getMetadata();
}

Media Support

Media

Represents media content in messages (images, audio, etc.).

public class Media {
    /**
     * Construct a Media with MIME type and data.
     *
     * @param mimeType the MIME type
     * @param data the media data (URL, base64, byte array, etc.)
     */
    public Media(MimeType mimeType, Object data);

    /**
     * Construct a Media with MIME type, data, and metadata.
     *
     * @param mimeType the MIME type
     * @param data the media data
     * @param metadata the media metadata
     */
    public Media(MimeType mimeType, Object data, Map<String, Object> metadata);

    /**
     * Get the MIME type of this media.
     *
     * @return the MIME type
     */
    public MimeType getMimeType();

    /**
     * Get the media data.
     * Can be a URL string, base64 string, byte array, or other format.
     *
     * @return the media data
     */
    public Object getData();

    /**
     * Get the media metadata.
     * Contains additional information about the media such as dimensions, duration, etc.
     *
     * @return the media metadata map
     */
    public Map<String, Object> getMetadata();
}

MimeType Enum

Enumeration of supported MIME types for media.

public enum MimeType {
    IMAGE_PNG("image/png"),
    IMAGE_JPEG("image/jpeg"),
    IMAGE_GIF("image/gif"),
    IMAGE_WEBP("image/webp"),
    AUDIO_WAV("audio/wav"),
    AUDIO_MP3("audio/mp3"),
    AUDIO_FLAC("audio/flac"),
    AUDIO_OPUS("audio/opus"),
    AUDIO_AAC("audio/aac"),
    VIDEO_MP4("video/mp4"),
    VIDEO_MPEG("video/mpeg");

    /**
     * Get the MIME type string value.
     *
     * @return the MIME type string
     */
    public String getValue();
}

Enums

MessageType

Enumeration of message types.

public enum MessageType {
    USER("user"),
    ASSISTANT("assistant"),
    SYSTEM("system"),
    TOOL("tool");

    /**
     * Get the string value of this message type.
     *
     * @return the string value
     */
    public String getValue();

    /**
     * Parse a MessageType from a string value.
     *
     * @param value the string value
     * @return the MessageType
     * @throws IllegalArgumentException if value is invalid
     */
    public static MessageType fromValue(String value);
}

Usage Examples

Creating Basic Messages

import org.springframework.ai.chat.messages.*;

// User message
UserMessage userMsg = new UserMessage("What is the weather today?");

// System message
SystemMessage systemMsg = new SystemMessage("You are a helpful weather assistant.");

// Assistant message
AssistantMessage assistantMsg = new AssistantMessage("The weather is sunny and 72°F.");

Multi-Modal User Message

import org.springframework.ai.chat.messages.UserMessage;
import org.springframework.ai.chat.messages.Media;
import org.springframework.ai.chat.messages.MimeType;
import org.springframework.core.io.ClassPathResource;

// Create media from image URL
Media imageMedia = new Media(MimeType.IMAGE_JPEG, "https://example.com/image.jpg");

// Create user message with text and image
UserMessage multiModalMsg = new UserMessage(
    "What is in this image?",
    List.of(imageMedia)
);

User Message with Base64 Image

import java.util.Base64;

// Load image as bytes
byte[] imageBytes = loadImageBytes();
String base64Image = Base64.getEncoder().encodeToString(imageBytes);

// Create media with base64 data
Media media = new Media(MimeType.IMAGE_PNG, base64Image);

UserMessage msg = new UserMessage("Analyze this image", List.of(media));

Assistant Message with Tool Calls

import org.springframework.ai.chat.messages.AssistantMessage;
import org.springframework.ai.chat.messages.AssistantMessage.ToolCall;

// Create tool calls
List<ToolCall> toolCalls = List.of(
    new ToolCall("call_123", "function", "get_weather", "{\"location\":\"Paris\"}"),
    new ToolCall("call_124", "function", "get_time", "{\"timezone\":\"UTC\"}")
);

// Create assistant message with tool calls
AssistantMessage assistantMsg = new AssistantMessage(
    "I'll check the weather and time for you.",
    Map.of(),
    toolCalls
);

// Check for tool calls
if (assistantMsg.hasToolCalls()) {
    for (ToolCall call : assistantMsg.getToolCalls()) {
        System.out.println("Tool: " + call.name());
        System.out.println("Args: " + call.arguments());
    }
}

Tool Response Message

import org.springframework.ai.chat.messages.ToolResponseMessage;
import org.springframework.ai.chat.messages.ToolResponseMessage.ToolResponse;

// Create tool responses
List<ToolResponse> responses = List.of(
    new ToolResponse("call_123", "get_weather", "{\"temp\":72,\"condition\":\"sunny\"}"),
    new ToolResponse("call_124", "get_time", "{\"time\":\"14:30:00\"}")
);

// Create tool response message
ToolResponseMessage toolResponseMsg = new ToolResponseMessage(responses);

Message with Metadata

import java.util.Map;

// Create message with custom metadata
Map<String, Object> metadata = Map.of(
    "userId", "user_123",
    "timestamp", System.currentTimeMillis(),
    "priority", "high"
);

UserMessage msgWithMetadata = new UserMessage(
    "Important question",
    List.of(),
    metadata
);

// Access metadata
Object userId = msgWithMetadata.getMetadata().get("userId");

Using Message Builders

// Build user message
UserMessage userMsg = UserMessage.builder()
    .content("Hello!")
    .media(List.of(new Media(MimeType.IMAGE_PNG, imageData)))
    .metadata(Map.of("source", "mobile"))
    .build();

// Build system message
SystemMessage systemMsg = SystemMessage.builder()
    .content("You are helpful.")
    .metadata(Map.of("version", "1.0"))
    .build();

Loading Message from File

import org.springframework.core.io.ClassPathResource;
import org.springframework.core.io.Resource;

// Load system prompt from file
Resource systemPromptResource = new ClassPathResource("prompts/system.txt");
SystemMessage systemMsg = new SystemMessage(systemPromptResource);

// Load user message from file
Resource userPromptResource = new ClassPathResource("prompts/user-query.txt");
UserMessage userMsg = new UserMessage(userPromptResource);

Copying and Mutating Messages

// Copy a message
UserMessage original = new UserMessage("Hello");
UserMessage copy = original.copy();

// Mutate a message
UserMessage mutated = original.mutate()
    .content("Hello, updated!")
    .metadata(Map.of("updated", true))
    .build();

Audio in Messages

// Create audio media
Media audioMedia = new Media(MimeType.AUDIO_WAV, audioBytes);

// Add to user message
UserMessage audioMsg = new UserMessage(
    "Please transcribe this audio",
    List.of(audioMedia)
);

Install with Tessl CLI

npx tessl i tessl/maven-org-springframework-ai--spring-ai-model

docs

reference

audio-transcription.md

chat-memory.md

chat-models.md

converters.md

core-abstractions.md

document-enrichment.md

embeddings.md

image-models.md

messages.md

metadata.md

moderation.md

observability.md

prompts.md

text-to-speech.md

tool-calling-options.md

tools.md

utilities.md

index.md

tile.json