Spring AI: MapOutputParser

Introduction to MapOutputParser

The MapOutputParser in Spring AI is a powerful tool that allows you to parse AI-generated responses directly into Java Map objects. This parser helps convert raw model outputs into key-value pairs, making it easier to work with AI-generated data in a structured and flexible way. This tutorial will guide you through setting up a Spring Boot application and demonstrate how to use MapOutputParser to handle AI-generated content effectively.

1. Setting Up the Project

Step 1: Create a New Spring Boot Project

You can create a new Spring Boot project using Spring Initializr or your preferred IDE. Ensure you include the necessary 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, Spring AI
  • Generate the project and unzip it.

Step 2: Add spring-ai-openai-spring-boot-starter Dependency

In your project's pom.xml, add the following dependency:


2. Configuring the Spring Boot Starter

Step 1: Add API Key to Configuration

Create a application.properties or application.yml file in your src/main/resources directory and add your OpenAI API key.

For application.properties:


For application.yml:

    key: your_openai_api_key

Step 2: Create a Configuration Class

Create a new configuration class to set up the OpenAI client and the ChatClient abstraction.

package com.example.demo.config;

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

public class OpenAiConfig {

    public OpenAiClient openAiClient() {
        return new OpenAiClient();

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

    public MapOutputParser mapOutputParser() {
        return new MapOutputParser();

3. Implementing the MapOutputParser

Step 1: Create a Service for Parsing Output

Create a service class that will handle interactions with the ChatClient abstraction and use MapOutputParser to process the AI-generated responses.

package com.example.demo.service;

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

import java.util.Map;

public class MapOutputParserService {

    private ChatClient chatClient;

    private MapOutputParser mapOutputParser;

    public Map<String, String> parseAiResponse(String userInput) {
        // Create the chat request
        ChatRequest request = new ChatRequest();

        // Send the chat request and get the response
        ChatResponse response = chatClient.sendMessage(request);

        // Parse the response into a Map
        return mapOutputParser.parse(response.getReply());

Step 2: Create a Controller for the Service

Create a controller to expose an endpoint for parsing AI-generated responses into a Map.

package com.example.demo.controller;

import com.example.demo.service.MapOutputParserService;
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;

import java.util.Map;

public class MapOutputParserController {

    private MapOutputParserService mapOutputParserService;

    public Map<String, String> parseResponse(@RequestParam String userInput) {
        return mapOutputParserService.parseAiResponse(userInput);

4. Testing the Integration

Step 1: Run the Application

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

Step 2: Access the Endpoint

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

http://localhost:8080/parseResponse?userInput=User John has the following task: complete the project report

You should receive a response with the parsed AI-generated content mapped into a Map.


In this tutorial, you learned how to set up and use the MapOutputParser feature in a Spring Boot application with Spring AI. You created a service to handle AI responses, a controller to expose an endpoint, and a MapOutputParser implementation to process the AI-generated content into a Map. This setup allows you to transform raw AI outputs into structured and usable data formats, making your AI integrations more powerful and flexible. Explore further customization and enhancements to leverage the full potential of MapOutputParser in your applications.