Chapter 12: Employing agents

Introduction

Introduces generative AI agents as goal-oriented actors while noting that their precise definition is debated.

• Goal-oriented nature of agents: Explain what generative AI agents have in common despite differing definitions of what qualifies as an agent.
  Why it matters: This shared idea gives you a way to discuss agents without treating one debated definition as settled.

Key terms: generative AI agents, autonomous, agentic workflow, goal

12.1 Understanding agents

The section explains augmented LLMs, common agentic workflow patterns, and the book’s broad use of the term “agent.”

• Augmented LLM building block: Explain what makes an LLM augmented and why Spring AI’s ChatClient can serve that role in an agentic workflow.
  Why it matters: It connects the Spring AI capabilities you have already used to the building block of agentic systems.
• Agentic workflow patterns: Describe the workflow patterns listed in the section and how they organize work around augmented LLMs.
  Why it matters: These pattern names give you a way to describe different arrangements of LLM-driven work.
• Agent autonomy and terminology: Distinguish Anthropic’s use of “agents” from agentic workflows, and explain how this book uses the term.
  Why it matters: It prevents the book’s broad use of “agent” from being mistaken for a claim that every agent plans its own steps.

Key terms: augmented LLM, retrieval, tools, memory, ChatClient, agentic workflows, prompt chaining, routing, parallelization, orchestrator-workers

12.2 Implementing agentic workflows and patterns

This introduction previews prompt chaining, routing, and parallelization as workflow patterns to be implemented with Spring AI and ChatClient.

12.2.1 Chaining prompts

Builds a linear Spring Boot workflow that chains two actions to fetch a board game’s rules and identify its mechanics.

• Action and Chain roles: Explain how Action, Chain, and the controller pass a question through the workflow to produce an answer.
  Why it matters: This explains how separate jobs become one question-answering workflow.
• Rules fetching action: Trace how RuleFetcherAction turns a question about a game into rule text for the next action.
  Why it matters: The next action needs the rules text, not just the game named in the question.
• Mechanics determination and limits: Explain how the second action identifies game mechanics and why its answer may omit mechanics a game uses.
  Why it matters: The prompt’s list helps determine which mechanics the final answer can report.

Key terms: Action, act(), Chain, AgentWorkflowAskController, RuleFetcherAction, ChatClient, TikaDocumentReader, boardgame.rules.path, MechanicsDeterminerAction, system message

12.2.2 Routing tasks

This section shows how to keep agentic actions focused and use an LLM-powered router to send each question to the appropriate workflow chain.

• Single-purpose workflow actions: Explain why the workflow uses a separate PlayerCountAction rather than expanding MechanicsDeterminerAction to answer player-count questions.
  Why it matters: Focused actions let the workflow handle new kinds of questions without turning one action into a catch-all.
• LLM-based chain routing: Trace how the router chooses between the mechanics and player-count chains and passes the user input to the chosen chain.
  Why it matters: Routing lets one controller entry point handle different questions through the appropriate specialized chain.

Key terms: Single Responsibility Principle, PlayerCountAction, MechanicsDeterminerAction, prompt template, Router, ChatClient, Chain, Chain bean’s ID, AgentWorkflowAskController

12.2.3 Applying parallelization

This section shows how to run game-question actions in parallel, combine and summarize their answers, and connect them in an explicitly configured workflow.

• Parallel worker execution: Explain how ParallelizerAction sends the game rules to the mechanics and player-count actions, runs their act() methods in parallel with CompletableFuture, and combines their results.
  Why it matters: It explains how one request can obtain several independent answers before producing a combined response.
• Chained summarization workflow: Trace the configured flow from fetching game rules through parallel worker actions to an LLM-generated summary of their combined results.
  Why it matters: It connects parallel answers to the single response the user receives.
• Explicit workflow limitation: Explain why the configured ChatClient workflows are described as somewhat inflexible.
  Why it matters: It clarifies the boundary of the workflows demonstrated here without assuming the agent can plan new ones.

Key terms: parallelization, ParallelizerAction, worker actions, CompletableFuture, act(), AgentWorkflowConfig, Chain, RuleFetcherAction, SummarizerAction, LLM

12.3 Creating self-planning agentic solutions

Introduces Embabel as a Spring AI–based JVM framework that plans paths through agent actions without requiring developers to define workflows explicitly.

• Action-Based Agentic Planning: Explain how Embabel plans a path to an agent’s goal from actions and their pre- and postconditions, rather than requiring a predefined workflow or using an LLM to plan.
  Why it matters: This distinction explains why an Embabel agent can choose a path through actions without a workflow being wired in advance.
• Spring AI Framework Foundation: Describe Embabel’s relationship to Spring AI as presented here.
  Why it matters: It connects Embabel’s planning capability to the Spring AI components used elsewhere in the book.

Key terms: actions, pre- and postconditions, Goal-Oriented Action Planning (GOAP), agentic planning, Embabel, Spring AI

12.3.1 Initializing an Embabel project

This section sets up a Java Spring Boot project for an Embabel agent and adds the build configuration needed to use Embabel.

• Java agent project foundation: Describe how to start the agent project with Spring Initializr: choose Java and add only the Spring Web dependency. Distinguish this approach from Embabel’s project creator, which requires uvx.
  Why it matters: This establishes the application in which the agent will be built.
• Embabel build configuration: Explain why the build file needs manual changes and state what to add: Embabel’s repository alongside Maven Central, then the Embabel agent starter dependency.
  Why it matters: These build changes make Embabel available to the new Spring Boot project.

Key terms: Spring Initializr, Spring Web, Java, Embabel’s project creator, uvx, build file, Embabel’s repository, Maven Central, Embabel agent starter

12.3.2 Defining the agent class

This section defines an Embabel agent class and two goal-achieving actions that use game rules to determine game mechanics and player counts.

• Annotated Embabel agent class: Describe how GameInfoAgent is declared as an Embabel agent and where its actions are defined.
  Why it matters: These annotations identify the class and its methods to Embabel.
• Goal-achieving action methods: Distinguish what @Action and @AchievesGoal mean for the two actions, and state the goal each action completes.
  Why it matters: The distinction explains why these actions can serve as the endpoints of Embabel workflows.
• Rules-to-result prompt flow: Trace how the two actions turn game rules into typed results through a prompt template and PromptRunner.
  Why it matters: This is how the actions turn rules text into structured answers rather than returning raw LLM text.

Key terms: GameInfoAgent, @Agent, @Action, @AchievesGoal, determineGameMechanics(), determinePlayerCount(), GameRules, Resource, promptResourceToString(), StringTemplate

12.3.3 Defining an action to get game rules

This section explains how Embabel uses action-method types to derive a workflow and defines an action that loads and returns game rules.

• Type-driven action dependencies: Explain how the types accepted and returned by @Action methods help Embabel derive a workflow, and why an action must provide an object required by other actions.
  Why it matters: The method signatures help Embabel determine which actions can supply what other actions need.
• Intermediate action versus goal: Distinguish the getGameRules() action from an action that achieves a goal.
  Why it matters: It clarifies why a useful action need not be the workflow's final result.
• Game rules action inputs: Trace how getGameRules() obtains the rules file and creates its GameRules return object, including the typed inputs it still needs.
  Why it matters: This shows what the rules-loading action produces and which inputs other actions must provide.

Key terms: Embabel, @Action, type safety, workflow, getGameRules(), @AchievesGoal, end state, TikaDocumentReader, rulesFilePath, RulesFile

12.3.4 Defining an action to get the rules filename

This subsection explains how an intermediate action obtains the rules filename needed by the game-rules action.

• Rules filename action role: Explain that getGameRulesFilename() produces a RulesFile object by using a prompt template to match a game title with its rules filename. Describe why it is an intermediate action rather than a goal-achieving one.
  Why it matters: It shows how one action supplies an object another action needs without itself completing the goal.

Key terms: getGameRulesFilename(), RulesFile, GameTitle, prompt template, goal-achieving action method

12.3.5 Defining an action to get the game title

Defines the agent’s first action, which extracts a game title from user input, and explains where that input comes from.

• Game title extraction action: Trace how extractGameTitle() turns the user’s input into a GameTitle object: it renders a prompt, sends it to the LLM through PromptRunner, and returns the extracted title.
  Why it matters: This action supplies the game title that starts the agent’s workflow.
• Embabel-provided user input: Explain where the extractGameTitle() method’s UserInput parameter comes from and whether the agent needs another action to supply it.
  Why it matters: It clarifies how the first action receives input without another agent action.

Key terms: extractGameTitle(), GameTitle, PromptRunner, prompt template, UserInput, Embabel

12.3.6 Running the agent via Embabel’s shell

This section shows how to use Embabel’s development shell to run the game agent and inspect how it chooses actions and reports results.

• Development shell activation: Describe the two ways to enable Embabel’s agent shell and why the shell profile is preferable to hardcoding the annotation.
  Why it matters: You can try the agent during development without making its shell a default part of production.
• Execute command and agent planning: Explain what running a game question with execute shows about the agent’s actions and its ability to plan a path to a goal.
  Why it matters: The shell run makes the agent’s self-planning visible rather than requiring you to prescribe an action sequence.
• Blackboard and execution output: Describe what the blackboard records and what other information appears in the execute output.
  Why it matters: These details help you interpret what happened during a shell run, not just its final answer.

Key terms: agent shell, @EnableAgentShell, shell, SPRING_PROFILES_ACTIVE, execute, actions, goals, determinePlayerCount(), determineGameMechanics(), blackboard

12.3.7 Accessing the agent via MCP

This subsection shows how to run an Embabel agent as an MCP Server, export its goal-achieving actions as tools, and try those tools with MCP Inspector.

• MCP Server Startup Mode: Explain how to switch the agent from its shell to its native MCP Server mode.
  Why it matters: Changing the startup mode makes the agent available to an MCP client rather than through the shell.
• Goal Action Tool Exports: Describe how goal-achieving actions are exposed as MCP tools and what the export configuration specifies.
  Why it matters: Running an MCP Server alone does not make the agent’s actions available as tools.
• MCP Inspector Tool Check: Describe how the section checks that the exported tools can be used through MCP.
  Why it matters: Inspecting the server shows whether an MCP client can actually reach and use the exported actions.

Key terms: @EnableAgentShell, shell, MCP Server, @AchievesGoal, export, @Export, UserInput, MCP tool, MCP Inspector, server.port

12.4 Summary