Source Code Examples

This tutorial will guide you through using roles in Spring AI to define and manage the behavior and permissions of AI interactions. Roles in Spring AI help control the context and functionality of AI models, allowing you to tailor interactions based on specific roles such as system, user, assistant, and function. We will also demonstrate different use cases by calling REST APIs with different inputs.

Introduction

Roles in Spring AI are essential for managing the context of AI interactions. They help define how different parts of the conversation should be handled, enhancing the nuance and effectiveness of communication with the AI.

Primary Roles

System Role: Guides the AI’s behavior and response style, setting parameters or rules for how the AI interprets and replies to the input.
User Role: Represents the user’s input – their questions, commands, or statements to the AI.
Assistant Role: The AI’s response to the user’s input. This role maintains the flow of the conversation.
Function Role: Focuses on carrying out specific actions or commands the user asks for, such as calculations or fetching data.

1. Setting Up the Project

Step 1: Create a New Spring Boot Project

Use Spring Initializr to create a new Spring Boot project. Include dependencies for Spring Web and Spring AI.

Using Spring Initializr:

Go to start.spring.io
Select:
- Project: Maven Project
- Language: Java
- Spring Boot: 3.0.0 (or latest)
- Dependencies: Spring Web
Generate the project and unzip it.

Step 2: Add Dependencies

In your project's pom.xml, add the necessary dependencies for Spring AI.

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-openai-spring-boot-starter</artifactId>
    <version>1.0.0</version>
</dependency>

2. Configuring Spring AI

Step 1: Add API Key to Configuration

Add your OpenAI API key to application.properties or application.yml.

For application.properties:

openai.api.key=your_openai_api_key

For application.yml:

openai:
  api:
    key: your_openai_api_key

Step 2: Configure Spring Beans

Create a configuration class to set up all necessary Spring beans, including the OpenAiClient and ChatClient.

package com.example.demo.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.ai.openai.OpenAiClient;
import org.springframework.ai.openai.OpenAiChatClient;
import org.springframework.ai.openai.ChatClient;

@Configuration
public class AppConfig {

    @Bean
    public OpenAiClient openAiClient() {
        return new OpenAiClient();
    }

    @Bean
    public ChatClient chatClient(OpenAiClient openAiClient) {
        return new OpenAiChatClient(openAiClient);
    }
}

3. Using Roles in AI Interactions

Step 1: Define Roles in the Service

Create a service to manage AI interactions with specific roles. In this example, we will define roles such as system, user, assistant, and function.

package com.example.demo.service;

import org.springframework.ai.openai.ChatClient;
import org.springframework.ai.openai.model.ChatMessage;
import org.springframework.ai.openai.model.ChatRequest;
import org.springframework.ai.openai.model.ChatResponse;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;

import java.util.List;

@Service
public class RoleService {

    private final ChatClient chatClient;

    @Autowired
    public RoleService(ChatClient chatClient) {
        this.chatClient = chatClient;
    }

    public String interactWithRoles(String userMessage, String systemMessageText, String assistantMessageText) {
        // Define the system message
        ChatMessage systemMessage = new ChatMessage("system", systemMessageText);

        // Define the assistant message
        ChatMessage assistantMessage = new ChatMessage("assistant", assistantMessageText);

        // Define the user message
        ChatMessage userMsg = new ChatMessage("user", userMessage);

        // Create a ChatRequest with the role-based messages
        ChatRequest request = new ChatRequest();
        request.setMessages(List.of(systemMessage, assistantMessage, userMsg));

        // Get the response from the ChatClient
        ChatResponse response = chatClient.sendMessage(request);
        return response.getReply();
    }
}

Step 2: Create a Controller to Expose the Service

Create a controller to expose endpoints for interacting with the AI using roles.

package com.example.demo.controller;

import com.example.demo.service.RoleService;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class RoleController {

    private final RoleService roleService;

    @Autowired
    public RoleController(RoleService roleService) {
        this.roleService = roleService;
    }

    @GetMapping("/interact")
    public String interact(@RequestParam String userMessage, @RequestParam String systemMessageText, @RequestParam String assistantMessageText) {
        return roleService.interactWithRoles(userMessage, systemMessageText, assistantMessageText);
    }

    @GetMapping("/provideInformation")
    public String provideInformation(@RequestParam String userMessage) {
        String systemMessageText = "You are a knowledgeable assistant.";
        String assistantMessageText = "How can I assist you with information?";
        return roleService.interactWithRoles(userMessage, systemMessageText, assistantMessageText);
    }

    @GetMapping("/performCalculation")
    public String performCalculation(@RequestParam String userMessage) {
        String systemMessageText = "You are an assistant that can perform calculations.";
        String assistantMessageText = "Please provide the calculation you need assistance with.";
        return roleService.interactWithRoles(userMessage, systemMessageText, assistantMessageText);
    }

    @GetMapping("/generateContent")
    public String generateContent(@RequestParam String adjective, @RequestParam String topic) {
        String userMessage = "Tell me a " + adjective + " joke about " + topic;
        String systemMessageText = "You are an assistant that can generate creative content.";
        String assistantMessageText = "Sure, let me think of a good one.";
        return roleService.interactWithRoles(userMessage, systemMessageText, assistantMessageText);
    }
}

4. Testing the Integration

Step 1: Run the Application

Run your Spring Boot application. Ensure the application starts without errors.

Step 2: Access the Interaction Endpoints

Use Postman, curl, or your browser to test the endpoints with different roles and inputs. For example:

General Interaction:

http://localhost:8080/interact?userMessage=Tell me a joke&systemMessageText=You are a helpful assistant.&assistantMessageText=How can I help you today?

Providing Information:

http://localhost:8080/provideInformation?userMessage=What is the capital of France?

Performing Calculations:

http://localhost:8080/performCalculation?userMessage=What is 10 + 15?

Generating Content:

http://localhost:8080/generateContent?adjective=funny&topic=technology

You should receive responses generated by the AI model based on the role-based messages.

Conclusion

This tutorial demonstrated how to set up and use roles in Spring AI to manage AI interactions in a Spring Boot application. You learned how to define system, user, assistant, and function roles, use them in a service, and expose endpoints to interact with the AI model. Different use cases were provided to show how roles can be used effectively in various scenarios. This setup allows you to create structured and contextually relevant prompts, enhancing the capabilities of your AI applications.

Explore further customization and enhancements to leverage the full potential of roles in your Spring Boot projects.

For more detailed information, refer to the Spring AI documentation.

Spring AI