This version is still in development and is not considered stable yet. For the latest stable version, please use Spring AI 2.1.0!

Agents

An agent is an application in which the model decides what to do next: it calls tools, reads the results, and continues until the task is done. In Simon Willison’s definition, an LLM agent runs tools in a loop to achieve a goal.

Each step of the loop assembles the context, lets the model choose an action, observes the result, and assembles the context for the next step. In Spring AI, the brain is the chat model behind a ChatClient, and the body is its tools and MCP tools. The tool calling loop runs the loop and ends it when the model answers without asking for a tool, and session memory keeps the context across requests.

The Agent Harness

A model on its own only predicts text. What turns it into an agent is the harness around it: in the words of LangChain’s The Anatomy of an Agent Harness, every piece of code, configuration and execution logic that isn’t the model itself. In short, Agent = Model + Harness. The harness runs the loop, gives the model its tools, manages its context and memory, checks what goes in and out, and records what happened.

For an agent built on a ChatClient, the backbone of the harness is the client’s advisor chain. Every call runs through the chain, and only its last advisor calls the model: every other advisor is part of the harness. The chain also connects the harness to what lies outside it, such as tools, MCP servers, the session store and vector stores.

Agent = Model + Harness An agent is a model plus a harness, everything that isn't the model. For an agent built on a ChatClient, the harness is the client's advisor chain and what it calls. ToolCallingAdvisor runs the loop and the tools, and for each tool round the rest of the chain runs again. SessionTurnAdvisor runs once per turn, outside the loop: it stores the turn in the session store and compacts the session. SessionMemoryAdvisor adds the history on every round. Recall tools let the model search the session. Your own advisors add hooks such as guardrails, retrieval and logging. StructuredOutputValidationAdvisor checks the output. ChatModelCallAdvisor, the last advisor, calls the chat model, which is outside the harness. The community project Spring AI Agent Utils adds more tools and advisors: Agent Skills, file system, shell, sandbox, sub-agents and long-term memory. Agent = Model + Harness Harness: everything that isn't the model the advisor chain of a ChatClient SessionTurnAdvisoronce per turn: stores the turn, compacts ToolCallingAdvisorthe loop: runs the tools the model asks for SessionMemoryAdvisormemory: the history, on every round Your advisorshooks: guardrails, retrieval, logging StructuredOutputValidationAdvisorverification: checks the output ChatModelCallAdvisorcalls the model for each tool round what the chain calls Session storethe event log of each conversation Tools and MCP servers@Tool methods, MCP, recall tools Vector store, moderation modelfor retrieval and guardrails Spring AI Agent Utils (Community) Agent Skills, file system, shell, sandbox, sub-agents, long-term memory: more tools and advisors for the chain ChatModel Model

Building an agent on a ChatClient therefore means choosing its advisors and its tools. The following table maps the responsibilities of a harness to Spring AI:

Harness responsibility In Spring AI

The loop

The tool calling loop, run by ToolCallingAdvisor, executes the tools the model asks for and sends the results back, until the model answers without asking for a tool.

Tools

Tools defined as Java methods, and MCP tools provided by MCP servers. Tool search keeps the prompt small when an agent has many tools.

Context and memory

Session memory keeps the conversation, including tool calls, across requests, compacts it when it grows, and lets the model search it.

Hooks

Your own advisors, which run around every call, or around every round of the loop, depending on their order.

Permissions

Tool call confirmation pauses the loop so that a person can approve a tool call.

Guardrails and verification

Guardrails check the input with SafeGuardAdvisor, or the input and the answer with a decision or moderation model. Schema validation calls the model again when an answer does not match its schema. Recursive advisors, the mechanism behind schema validation, are available for your own self-correcting loops.

Hand-off between steps

Structured output lets one step hand typed data to the next.

Recording

Observability: each advisor and each tool call is a span in the trace of the call.

Agent Skills, file system, shell, sandbox, sub-agents, long-term memory

Community: Spring AI Agent Utils, described in the next section.

Ready-Made Agentic Blocks

Community: Spring AI Agent Utils

Spring AI Agent Utils is a good place to start when you build an agent today. It is a community-maintained library of agentic blocks that you add to a ChatClient: its tools are ordinary Spring AI tools, and its advisors are ordinary advisors.

Agent Utils brings the capabilities of coding agents such as Claude Code to Java applications:

  • File, code search, shell and web tools, and task lists that let the model plan and track its work.

  • Agent Skills: instructions, scripts and reference files that the model loads only when a task needs them.

  • Long-term memory that keeps facts across conversations and consolidates them in the background.

  • Sub-agents with their own context window, run locally or through A2A.

  • Sandboxed execution, and control of the loop: stop a running agent and observe every tool call.

A Minimal Coding Agent puts them together in a few lines.

Workflow Pattern Examples

Anthropic’s Building Effective Agents describes five workflow patterns: chain, routing, parallelization, orchestrator-workers and evaluator-optimizer. Workflow Pattern Examples shows how to apply each of them with a ChatClient. The examples are a starting point for learning the patterns, with their code in the spring-ai-examples repository, not a library to add to an application.

Agents and Protocols

An agent rarely works alone. Three open protocols connect it to the rest of the system: to its tools, to other agents, and to the editor or command line that a person works in.

An agent client talks ACP to several agents; the agents talk A2A to each other and MCP to their MCP servers
Protocol Connects In Spring AI

Model Context Protocol (MCP)

An agent and its tools, resources and prompts.

Part of Spring AI: MCP clients and servers, for both generations of the protocol.

Agent2Agent (A2A)

An agent and other agents, whatever framework or language they are built with.

The community project Spring AI A2A exposes a ChatClient agent as an A2A server.

Agent Client Protocol (ACP)

An editor or command-line client and the agents it drives.

Community projects: ACP Spring Boot Autoconfiguration makes a Spring AI agent an ACP server, and the Spring AI ACP Harness Client lets a Spring application drive coding agents that speak ACP.

The agents in the diagram can be Spring AI applications or agents built with other stacks: the protocols are what lets them work together.

Workshops

AWS maintains two workshops that build agents with Spring AI step by step, one of them with Amazon Bedrock AgentCore. They are listed, with other workshops, in Samples and Workshops.