Creating an AI Agent in Java Using Embabel Agent Framework

1. Overview

Modern applications are increasingly using Large Language Models (LLMs) to build solutions that go beyond simple question-answering. To achieve most real-world use cases, we need an AI agent capable of orchestrating complex workflows between LLMs and external tools.

The Embabel Agent Framework, created by Spring Framework founder Rod Johnson, aims to simplify creating AI agents on the JVM by providing a higher level of abstraction on top of Spring AI.

Through the use of Goal-Oriented Action Planning (GOAP), it enables agents to dynamically find paths to achieve goals without explicitly programming every workflow.

In this tutorial, we’ll explore the Embabel agent framework by building a basic quiz generation agent named Quizzard. Our agent fetches content from a blog post URL and then uses it to generate multiple-choice questions.

2. Setting up the Project

Before we start implementing our Quizzard agent, we’ll need to include the necessary dependency and configure our application correctly.

2.1. Dependencies

Let’s start by adding the necessary dependency to our project’s pom.xml file:

<dependency>
    <groupId>com.embabel.agent</groupId>
    <artifactId>embabel-agent-starter</artifactId>
    <version>0.1.0-SNAPSHOT</version>
</dependency>

For our Spring Boot application, we import the embabel-agent-starter dependency, which provides us with all the core classes required to build our Quizzard agent.

Since we’re using a snapshot version of the library, we’ll also need to add the Embabel snapshot repository to our pom.xml:

<repositories>
    <repository>
        <id>embabel-snapshots</id>
        <url>https://repo.embabel.com/artifactory/libs-snapshot</url>
        <snapshots>
            <enabled>true</enabled>
        </snapshots>
    </repository>
</repositories>

This is where we’ll be able to access the snapshot artifacts of Embabel, as opposed to the standard Maven Central repository.

2.2. Configuring an LLM Model

Next, let’s configure a chat model in our application.yaml file:

embabel:
  models:
    default-llm: claude-opus-4-20250514

For our demonstration, we specify Claude 4 Opus by Anthropic, as our default model for all agent operations, using the claude-opus-4-20250514 model ID.

Notably, Embabel supports using multiple LLMs together, through which we can achieve cost-effectiveness and choose the best LLM for a given task based on its complexity.

Additionally, we’ll have to pass our Anthropic API key in the ANTHROPIC_API_KEY environment variable when running the application.

2.3. Defining a Quiz Generation Prompt Template

Finally, to make sure that our LLM generates high-quality quizzes against a blog’s content, we’ll define a detailed prompt template.

Let’s create a quiz-generation.txt file in the src/main/resources/prompt-templates directory:

Generate multiple choice questions based on the following blog content:

Blog title: %s
Blog content: %s

Requirements:
- Create exactly 5 questions
- Each question must have exactly 4 options
- Each question must have only one correct answer
- The difficulty level of the questions should be intermediate
- Questions should test understanding of key concepts from the blog
- Make the incorrect options plausible but clearly wrong
- Questions should be clear and unambiguous

Here, we clearly outline the requirements for the quiz. We leave two %s placeholders in our prompt template for the blog title and blog content, respectively. We’ll replace them with the actual values in our agent class.

For simplicity, we’re hardcoding the number of questions, options, and difficulty level directly in the prompt template. However, in a production application, we could make these configurable through properties or accept them as user input based on requirements.

3. Creating Our Agent

In Embabel, an agent is the central component, which encapsulates a set of capabilities, known as actions, and uses them to achieve goals.

And now that we have our configuration in place, let’s build our Quizzard agent. We’ll first define an action that fetches blog content from the web using a Model Context Protocol (MCP) server and then another that uses our configured LLM to generate a quiz from it.

3.1. Fetching Blog Content Using Web Search

To extract content from blogs, we’ll use the Fetch MCP server. It provides a tool that fetches content from a URL and converts it to markdown. Alternatively, we could use the Brave Search MCP server instead.

For our demonstration, we’ll add this MCP server to Docker Desktop using the MCP toolkit, which is available in version 4.42 or later. If using an older version, we can add the MCP toolkit as a Docker extension.

To use this MCP server, let’s first configure our application as an MCP client:

@SpringBootApplication
@EnableAgents(mcpServers = {
  McpServers.DOCKER_DESKTOP
})
class Application {
    // ...
}

Using the @EnableAgents annotation, our application will be able to act as an MCP client and connect to tools available through the Docker Desktop integration.

Next, let’s define our agent and its first action:

@Agent(
  name = "quizzard",
  description = "Generate multiple choice quizzes from documents"
)
class QuizGeneratorAgent {

    @Action(toolGroups = CoreToolGroups.WEB)
    Blog fetchBlogContent(UserInput userInput) {
        return PromptRunner
          .usingLlm()
          .createObject(
            "Fetch the blog content from the URL given in the following request: '%s'".formatted(userInput),
            Blog.class
          );
    }
}

Here, we annotate our QuizGeneratorAgent class with the @Agent annotation to declare it as an agent.

We provide its purpose in the description attribute, as it helps Embabel select the correct agent to handle a user’s request, especially when we define multiple agents in an application.

Next, we define the fetchBlogContent() method and annotate it with @Action, which marks it as a capability that the agent can perform. Additionally, to grant our action access to the fetch MCP server we enabled, we specify CoreToolGroups.WEB in the toolGroups attribute.

Inside our method, we use the PromptRunner class to pass a prompt to extract the URL’s content from the user’s input. To populate a Blog object with this extracted information, we pass the Blog class as the second argument in the createObject() method. Embabel automatically adds instructions to our prompt for the LLM to produce a structured output.

It’s worth noting that Embabel provides the UserInput and Blog domain models, so we don’t need to create them ourselves. The UserInput contains the user’s text request and timestamp, while the Blog type includes fields for the blog’s title, content, author, etc.

3.2. Generating Quiz From Fetched Blog

Now that we have an action capable of fetching a blog’s content, the next step is to define an action to generate the quiz.

First, let’s define a record to represent the structure of our quiz:

record Quiz(List<QuizQuestion> questions) {

    record QuizQuestion(
        String question,
        List<String> options,
        String correctAnswer
    ) {
    }
}

Our Quiz record contains a list of nested QuizQuestion records, which hold the question, each with its options and the correct answer.

Finally, let’s add the second action to our agent to generate the quiz from the fetched blog content:

@Value("classpath:prompt-templates/quiz-generation.txt")
private Resource promptTemplate;

@Action
@AchievesGoal(description = "Quiz has been generated")
Quiz generateQuiz(Blog blog) {
    String prompt = promptTemplate
      .getContentAsString(Charset.defaultCharset())
      .formatted(
        blog.getTitle(),
        blog.getContent()
      );
    return PromptRunner
      .usingLlm()
      .createObject(
        prompt,
        Quiz.class
      );
}

We create a new generateQuiz() method that takes the Blog object returned by our previous action as an argument.

In addition to @Action, we annotate this method with the @AchievesGoal annotation, to indicate that the successful execution of this action fulfils the agent’s primary purpose.

In our method, we replace the placeholders in our promptTemplate with the blog’s title and content. Then, we use the PromptRunner class again to generate a Quiz object based on this prompt.

4. Interacting With Our Agent

Now that we’ve built our agent, let’s interact with it and test it out.

First, let’s enable the interactive shell mode in our application:

@EnableAgentShell
@SpringBootApplication
@EnableAgents(mcpServers = {
  McpServers.DOCKER_DESKTOP
})
class Application {
    // ...
}

We annotate our main Spring Boot class with the @EnableAgentShell annotation, which provides us with an interactive CLI to interact with our agent.

Alternatively, we can also use the @EnableAgentMcpServer annotation to run our application as an MCP server where Embabel exposes our agent as an MCP-compatible tool, which an MCP client can consume. But for our demonstration, we’ll keep things simple.

Let’s start our application and give our agent a command:

execute 'Generate quiz for this article: https://www.baeldung.com/spring-ai-model-context-protocol-mcp'

Here, we use the execute command to send a request to our Quizzard agent. We provide natural language instructions that contain the URL of the Baeldung article we want to create a quiz for.

Let’s see the generated logs when we execute this command:

[main] INFO  Embabel - formulated plan 
	com.baeldung.quizzard.QuizGeneratorAgent.fetchBlogContent ->
		com.baeldung.quizzard.QuizGeneratorAgent.generateQuiz
[main] INFO  Embabel - executing action com.baeldung.quizzard.QuizGeneratorAgent.fetchBlogContent
[main] INFO  Embabel - (fetchBlogContent) calling tool embabel_docker_mcp_fetch({"url":"https://www.baeldung.com/spring-ai-model-context-protocol-mcp"})
[main] INFO  Embabel - received LLM response com.baeldung.quizzard.QuizGeneratorAgent.fetchBlogContent-com.embabel.agent.domain.library.Blog of type Blog from DefaultModelSelectionCriteria in 11 seconds
[main] INFO  Embabel - executing action com.baeldung.quizzard.QuizGeneratorAgent.generateQuiz
[main] INFO  Embabel - received LLM response com.baeldung.quizzard.QuizGeneratorAgent.generateQuiz-com.baeldung.quizzard.Quiz of type Quiz from DefaultModelSelectionCriteria in 5 seconds
[main] INFO  Embabel - goal com.baeldung.quizzard.QuizGeneratorAgent.generateQuiz achieved in PT16.332321S

You asked: UserInput(content=Generate quiz for this article: https://www.baeldung.com/spring-ai-model-context-protocol-mcp, timestamp=2025-07-09T15:36:20.056402Z)

{
  "questions":[
    {
      "question":"What is the primary purpose of the Model Context Protocol (MCP) introduced by Anthropic?",
      "options":[
        "To provide a standardized way to enhance AI model responses by connecting to external data sources",
        "To replace existing LLM architectures with a new protocol",
        "To create a new programming language for AI development",
        "To establish a security protocol for AI model deployment"
      ],
      "correctAnswer":"To provide a standardized way to enhance AI model responses by connecting to external data sources"
    },
    {
      "question":"In the MCP architecture, what is the relationship between MCP Clients and MCP Servers?",
      "options":[
        "MCP Clients establish many-to-many connections with MCP Servers",
        "MCP Clients establish 1:1 connections with MCP Servers",
        "MCP Servers establish connections to MCP Clients",
        "MCP Clients and Servers communicate through a central message broker"
      ],
      "correctAnswer":"MCP Clients establish 1:1 connections with MCP Servers"
    },
    {
      "question":"Which transport mechanism is used for TypeScript-based MCP servers in the tutorial?",
      "options":[
        "HTTP transport",
        "WebSocket transport",
        "stdio transport",
        "gRPC transport"
      ],
      "correctAnswer":"stdio transport"
    },
    {
      "question":"What annotation is used to expose custom tools in the MCP server implementation?",
      "options":[
        "@Tool",
        "@MCPTool",
        "@Function",
        "@Method"
      ],
      "correctAnswer":"@Tool"
    },
    {
      "question":"What type of transport is used for custom MCP servers in the tutorial?",
      "options":[
        "stdio transport",
        "HTTP transport",
        "SSE transport",
        "TCP transport"
      ],
      "correctAnswer":"SSE transport"
    }
  ]
}

LLMs used: [claude-opus-4-20250514]
Prompt tokens: 3,053, completion tokens: 996
Cost: $0.0141
Tool usage:
	ToolStats(name=embabel_docker_mcp_fetch, calls=1, avgResponseTime=1657 ms, failures=0)

The logs provide a clear view of the agent’s execution flow.

First, we can see that Embabel automatically and correctly formulated a plan to achieve our defined goal.

Next, the agent executes the plan, starting with the fetchBlogContent action. Additionally, we can see that it calls the fetch MCP server with the URL we provided. Once it fetches the content, the agent proceeds to the generateQuiz action.

Finally, the agent confirms that it achieved the goal and prints the final quiz in JSON format, along with useful metrics like token usage and cost.

5. Conclusion

In this article, we’ve explored how to build intelligent agents using the Embabel agent framework.

We built a practical, multi-step agent, Quizzard, that can fetch web content and generate a quiz from it. Our agent was able to dynamically determine the sequence of actions needed to achieve its goal.