Spring AI: BeanOutputParser

Introduction to BeanOutputParser

The BeanOutputParser in Spring AI is a specialized tool that allows you to parse AI-generated responses directly into Java beans. This parser helps convert raw model outputs into structured objects, making it easier to work with AI-generated data in a more type-safe and maintainable way. This tutorial will guide you through setting up a Spring Boot application and demonstrate how to use BeanOutputParser 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.BeanOutputParser;

public class OpenAiConfig {

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

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

    public BeanOutputParser beanOutputParser() {
        return new BeanOutputParser();

3. Implementing the BeanOutputParser

Step 1: Create a Data Bean

Create a simple Java bean to hold the parsed data.

package com.example.demo.model;

public class TaskInfo {
    private String userName;
    private String taskDescription;

    // Getters and Setters
    public String getUserName() {
        return userName;

    public void setUserName(String userName) {
        this.userName = userName;

    public String getTaskDescription() {
        return taskDescription;

    public void setTaskDescription(String taskDescription) {
        this.taskDescription = taskDescription;

Step 2: Create a Service for Parsing Output

Create a service class that will handle interactions with the ChatClient abstraction and use BeanOutputParser 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.BeanOutputParser;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;
import com.example.demo.model.TaskInfo;

public class BeanOutputParserService {

    private ChatClient chatClient;

    private BeanOutputParser beanOutputParser;

    public TaskInfo 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 TaskInfo bean
        return beanOutputParser.parse(response.getReply(), TaskInfo.class);

Step 3: Create a Controller for the Service

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

package com.example.demo.controller;

import com.example.demo.service.BeanOutputParserService;
import com.example.demo.model.TaskInfo;
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;

public class BeanOutputParserController {

    private BeanOutputParserService beanOutputParserService;

    public TaskInfo parseResponse(@RequestParam String userInput) {
        return beanOutputParserService.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 the TaskInfo bean.


In this tutorial, you learned how to set up and use the BeanOutputParser 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 BeanOutputParser implementation to process the AI-generated content into Java beans. 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 BeanOutputParser in your applications.