In the last tutorial we saw a very simple example involving AiServices. Here we are going though all methods in AiServices and understand how to use them.

AiServices Method Reference: Grouped by Purpose

Entry Point Methods

Static methods to create or start building an AI Service:

static <T> T create(Class<T>, ChatModel)

Quick creation with ChatModel

static <T> T create(Class<T>, StreamingChatModel)

Quick creation with StreamingChatModel

static <T> AiServices<T> builder(Class<T>)

Start building with interface class

static <T> AiServices<T> builder(AiServiceContext)

Internal builder with context

Instance Methods

The following methods are all instance methods that can be chained using the builder fluent API. The AiServices class itself acts as a builder, allowing you to configure your AI service by chaining these methods together before calling build().

Core Model Configuration

Configure the underlying AI model:

AiServices<T> chatModel(ChatModel)

Set synchronous chat model

AiServices<T> streamingChatModel(StreamingChatModel)

Set streaming chat model

Message & Prompt Configuration

Control system messages and prompts:

AiServices<T> systemMessageProvider(Function<Object, String>)

Dynamic system message provider

Memory Management

Configure conversation history:

AiServices<T> chatMemory(ChatMemory)

Shared memory for all conversations

AiServices<T> chatMemoryProvider(ChatMemoryProvider)

Per-user/conversation memory

AiServices<T> storeRetrievedContentInChatMemory(boolean)

Control RAG content storage in memory

Request Transformation

Modify requests before sending to LLM:

AiServices<T> chatRequestTransformer(UnaryOperator<ChatRequest>)

Transform without memory ID

AiServices<T> chatRequestTransformer(BiFunction<ChatRequest, Object, ChatRequest>)

Transform with memory ID

Content Moderation

Safety and content filtering:

AiServices<T> moderationModel(ModerationModel)

Configure content moderation

Tool Configuration

Configure tools/functions the LLM can use:

AiServices<T> tools(Object...)

Configure with annotated objects (varargs)

AiServices<T> tools(Collection<Object>)

Configure with annotated objects (collection)

AiServices<T> tools(Map<ToolSpecification, ToolExecutor>)

Programmatic tool configuration

AiServices<T> tools(Map<ToolSpecification, ToolExecutor>, Set<String>)

With immediate return tools

AiServices<T> toolProvider(ToolProvider)

Dynamic tool provider

Tool Execution Control

Control how tools are executed:

AiServices<T> executeToolsConcurrently()

Enable concurrent execution with default executor

AiServices<T> executeToolsConcurrently(Executor)

Enable concurrent execution with custom executor

AiServices<T> maxSequentialToolsInvocations(int)

Limit sequential tool calls

Tool Error Handling

Handle tool-related errors:

AiServices<T> hallucinatedToolNameStrategy(Function<ToolExecutionRequest, ToolExecutionResultMessage>)

Handle nonexistent tool calls

AiServices<T> toolArgumentsErrorHandler(ToolArgumentsErrorHandler)

Handle argument parsing errors

AiServices<T> toolExecutionErrorHandler(ToolExecutionErrorHandler)

Handle execution errors

RAG (Retrieval-Augmented Generation)

Configure content retrieval:

AiServices<T> contentRetriever(ContentRetriever)

Simple content retrieval

AiServices<T> retrievalAugmentor(RetrievalAugmentor)

Advanced retrieval augmentation

Input Guardrails

Configure input validation and safety:

AiServices<T> inputGuardrailsConfig(InputGuardrailsConfig)

Configure with config object

<I extends InputGuardrail> AiServices<T> inputGuardrailClasses(List<Class<? extends I>>)

Configure with classes (list)

<I extends InputGuardrail> AiServices<T> inputGuardrailClasses(Class<? extends I>...)

Configure with classes (varargs)

<I extends InputGuardrail> AiServices<T> inputGuardrails(List<I>)

Configure with instances (list)

<I extends InputGuardrail> AiServices<T> inputGuardrails(I...)

Configure with instances (varargs)

Output Guardrails

Configure output validation and safety:

AiServices<T> outputGuardrailsConfig(OutputGuardrailsConfig)

Configure with config object

<O extends OutputGuardrail> AiServices<T> outputGuardrailClasses(List<Class<? extends O>>)

Configure with classes (list)

<O extends OutputGuardrail> AiServices<T> outputGuardrailClasses(Class<? extends O>...)

Configure with classes (varargs)

<O extends OutputGuardrail> AiServices<T> outputGuardrails(List<O>)

Configure with instances (list)

<O extends OutputGuardrail> AiServices<T> outputGuardrails(O...)

Configure with instances (varargs)

Event Listening & Observability

Track and monitor AI service events:

<I extends AiServiceEvent> AiServices<T> registerListener(AiServiceListener<I>)

Register single listener

AiServices<T> registerListeners(AiServiceListener<?>...)

Register multiple listeners (varargs)

AiServices<T> registerListeners(Collection<? extends AiServiceListener<?>>)

Register multiple listeners (collection)

<I extends AiServiceEvent> AiServices<T> unregisterListener(AiServiceListener<I>)

Unregister single listener

AiServices<T> unregisterListeners(AiServiceListener<?>...)

Unregister multiple listeners (varargs)

AiServices<T> unregisterListeners(Collection<? extends AiServiceListener<?>>)

Unregister multiple listeners (collection)

Build Method

Finalize and create the AI Service instance:

abstract T build()

Construct the AI Service proxy

Typical Usage Flow

AiServices.builder(MyInterface.class)
    // Core Model
    .chatModel(model)
    // Memory
    .chatMemory(memory)
    // Tools
    .tools(toolObject)
    // RAG
    .contentRetriever(retriever)
    // Guardrails
    .inputGuardrails(...)
    .outputGuardrails(...)
    // Listeners
    .registerListener(listener)
    // Build
    .build();
    

What's Next?

This overview provides a comprehensive grouping of all methods available in the AiServices class. Each category serves a specific purpose in building and configuring your AI Service. In the upcoming tutorials, we will explore practical examples for each of these method groups, demonstrating how to effectively use them in real-world scenarios. You'll learn how to combine these configurations to create powerful, production-ready AI services tailored to your specific needs.