Package akka.javasdk.agent

Interface ContentLoader

All Known Subinterfaces:

ImageLoader

public interface ContentLoader

Interface for loading content from URIs.

Implement this interface to provide custom content loading logic for MessageContent.LoadableMessageContent types. This is useful when content must be fetched from custom sources such as cloud storage, databases, or authenticated endpoints.

Example implementation:

 public class MyContentLoader implements ContentLoader {
   @Override
   public LoadedContent load(MessageContent.LoadableMessageContent content) {
     return switch (content) {
       case MessageContent.ImageUrlMessageContent image -> {
         byte[] data = fetchFromStorage(image.url());
         String mimeType = image.mimeType().orElse("image/jpeg");
         yield new LoadedContent(data, Optional.of(mimeType));
       }
       case MessageContent.PdfUrlMessageContent pdf -> {
         byte[] data = fetchFromStorage(pdf.url());
         yield new LoadedContent(data);
       }
     };
   }
 }
 

To use the content loader, pass it to the agent effect builder:

 return effects()
     .contentLoader(new MyContentLoader())
     .userMessage(UserMessage.from(
         MessageContent.TextMessageContent.from("Describe this image"),
         MessageContent.ImageMessageContent.fromUrl(imageUrl)))
     .thenReply();
 

The instance used could be a new one for each agent request, to for example allow per-request credentials, or it could be created globally in the service bootstrap, and made available to each agent via dependency injection.

In case of a shared instance, care must be taken that it is thread safe since it can be used by multiple separate agent interactions concurrently.

See Also:

• Agent.Effect.Builder.contentLoader(ContentLoader)

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static final record	ContentLoader.LoadedContent	Represents loaded content with its binary data and MIME type.

Method Summary

Modifier and Type	Method	Description
ContentLoader.LoadedContent	load(MessageContent.LoadableMessageContent content)	Loads content from the given loadable message content.

Method Details

load

ContentLoader.LoadedContent load(MessageContent.LoadableMessageContent content)

Loads content from the given loadable message content.

This method is called by the runtime when processing multimodal messages that contain URL-referenced content. The implementation should fetch the content data and return it along with the appropriate MIME type.

Use pattern matching on the content parameter to handle different content types:

• MessageContent.ImageUrlMessageContent — provides the URL, detail level, and optional MIME type hint
• MessageContent.PdfUrlMessageContent — provides the URL of the PDF

If the method throws, the entire agent request is failed.

Parameters:

content - The loadable message content containing the URL and metadata

Returns:

The loaded content data and MIME type