Spring AI Roles Tutorial

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.

Introduction

The evolution of prompts in AI has transitioned from basic, straightforward text to more organized and complex formats with specific roles and structures. Initially, prompts were simple strings. Over time, they evolved to include specific placeholders within these strings, such as "USER:", which the AI model could recognize and respond to accordingly. OpenAI then introduced a more organized approach where prompts are a series of messages, each assigned a specific role. These roles categorize the messages, enhancing the nuance and effectiveness of communication with the AI.

Primary Roles

1. System Role: Guides the AI’s behavior and response style, setting parameters or rules for how the AI interprets and replies to the input.
2. User Role: Represents the user’s input – their questions, commands, or statements to the AI.
3. Assistant Role: The AI’s response to the user’s input. This role maintains the flow of the conversation.
4. 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) {
        // Define the system message
        ChatMessage systemMessage = new ChatMessage("system", "You are an AI assistant.");

        // Define the assistant message
        ChatMessage assistantMessage = new ChatMessage("assistant", "How can I assist you today?");

        // 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 an endpoint 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) {
        return roleService.interactWithRoles(userMessage);
    }
}

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 Endpoint

Use Postman, curl, or your browser to test the endpoint. For example:

http://localhost:8080/interact?userMessage=Tell me a joke

You should receive a response 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 an endpoint to interact with the AI model. 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.