Package akka.javasdk.agent

Interface ImageLoader

public interface ImageLoader

Interface for loading images from URIs.

Implement this interface to provide custom image loading logic for multimodal AI agent interactions. This allows loading images from custom sources such as cloud storage, databases, or authenticated endpoints.

Example implementation:

 public class MyImageLoader implements ImageLoader {
   @Override
   public LoadedImage load(
       URI uri,
       MessageContent.ImageMessageContent.DetailLevel detailLevel,
       Optional<String> mimeType) {
     // Load image bytes from your custom source
     byte[] imageData = fetchFromStorage(uri);
     String actualMimeType = mimeType.orElse("image/jpeg");
     return new LoadedImage(imageData, actualMimeType);
   }
 }
 

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

 return effects()
     .imageLoader(new MyImageLoader())
     .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:

• MessageContent.ImageMessageContent
• Agent.Effect.Builder.imageLoader(ImageLoader)

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static final record	ImageLoader.LoadedImage	Represents a loaded image with its binary data and MIME type.

Method Summary

Modifier and Type	Method	Description
ImageLoader.LoadedImage	load(URI uri, MessageContent.ImageMessageContent.DetailLevel detailLevel, Optional<String> mimeType)	Loads an image from the given URI.

Method Details

load

ImageLoader.LoadedImage load(URI uri,
 MessageContent.ImageMessageContent.DetailLevel detailLevel,
 Optional<String> mimeType)

Loads an image from the given URI.

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

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

Parameters:

uri - The URI of the image to load

detailLevel - The requested detail level for image processing (LOW, HIGH, or AUTO)

mimeType - Optional MIME type hint provided by the user. Note that the returned mime type *must* match the actual MIME type of the returned bytes if the input MIME type is not correct.

Returns:

The loaded image data and MIME type