AI Agents

This content was generated with the assistance of AI and should be verified against the official documentation of each tool and framework before being relied on in production.

This section’s bibliography lists the reference material consulted while preparing these pages.

Examples across this sub-section target Python 3.12 with LangChain 1.4.2, langchain-core 1.6.5, LangGraph 1.2.12 (langgraph-checkpoint 4.2.0) and langchain-ollama 1.1.0; Java 21 with LangChain4j 1.20.2 (its agentic modules at 1.20.2-beta30); and Spring Boot 4.1 with Spring AI 2.0.1 — the same Spring baseline as LLM Foundations & Prompting. Individual pages add the A2A Python SDK 1.1.5, langgraph-swarm 0.1.0, agentevals 0.0.9 and the community spring-ai-agent-utils 0.12.0 and spring-ai-a2a-server 0.3.0 where they use them. Every example runs DocsAssistant's own models — Ollama llama3.1:8b for chat and nomic-embed-text for embeddings — and any of the hosted models used elsewhere in this AI section (claude-sonnet-5, claude-opus-5-5, claude-haiku-4-5, claude-fable-5-1, gpt-6-sol) is a drop-in replacement. Protocol pages describe A2A 1.0 (released 2026-03-12) and the Model Context Protocol revision 2026-07-28. Every version was read from PyPI, Maven Central and the other package registries on 2026-09-28; the LangGraph/LangChain and LangChain4j numbers are this AI section’s first stated baseline for those frameworks, which the LangChain sub-section restates. The ai-catalog excerpt on Multi-Agent Systems is pinned to commit 58fb709, the tip of that repository’s main branch on the same date. If a page and this baseline ever disagree after a later update, this baseline is the one to trust.

What an agent is

An agent is a system in which a language model decides, step by step, what to do next — which tool to call, with what arguments, and when the task is finished — and the runtime carries those decisions out and feeds the results back, in a loop, until the model stops or a limit stops it. The defining property is that the path is chosen by the model at run time, not written in advance by a developer.

This sub-section treats agents as an engineering discipline independent of any one framework: each concept is explained once and then shown in three stacks — LangGraph / LangChain 1.x (Python), LangChain4j (Java without Spring) and Spring AI (Spring Boot) — with an "In other frameworks" table for the OpenAI Agents SDK, the Claude Agent SDK, Microsoft Agent Framework and CrewAI. Framework-specific depth (every API, configuration and deployment detail) belongs to the LangChain and Spring AI sub-sections; building MCP servers belongs to the Model Context Protocol (MCP) sub-section; and agentic retrieval is already covered by Agentic RAG, which these pages link rather than repeat.

Every example extends DocsAssistant, the running example of the Vector Databases & RAG section and of LLM Foundations & Prompting, into an agent: it answers questions about this site, searches the docs as a tool, opens a GitHub issue when a page is wrong — a write action that needs human approval — and hands proposed fixes to a reviewer agent.

Workflows vs. agents, and when not to build an agent

A workflow composes model calls and tools along paths the developer wrote in code; an agent lets the model choose the path. Workflows are predictable, cheaper, faster and easier to test; agents are flexible where the steps cannot be known in advance, at the cost of latency, tokens, and failure modes that are harder to foresee.

Do not build an agent when:

  • one well-prompted model call, with good retrieval, already does the job — most "chat with your docs" features are this;

  • the steps are known in advance — a fixed sequence, a classification followed by a fixed handler, a fan-out — which is a workflow (see Workflow Patterns);

  • mistakes are expensive and hard to undo, and a human cannot review each action;

  • the latency or cost budget cannot absorb a variable number of model calls;

  • you cannot yet measure whether it works (see Agent Evaluation).

Build an agent when the task is open-ended, the next step genuinely depends on what the last one found, the tools are safe or gated, and the value of solving the harder cases justifies the cost. Start with the simplest system that could work, measure it, and add autonomy only where it demonstrably helps.

The five components

The five components of an LLM agent: at the centre, the model, which reasons and decides; around it, the orchestration loop of perceive, reason, act and observe with its planning, routing, stop conditions and limits; on the left, instructions (role, goals, rules, output format) and memory (short-term thread state, long-term semantic, episodic and procedural memory); on the right, tools (read tools such as docs_search and an approval-gated write tool, github_open_issue); and below, the environment the agent acts in: users and reviewers, the documentation corpus, GitHub and other agents.
Figure 1. The five components of an LLM agent

  1. Model — the LLM that reasons and decides; its capability sets the ceiling of everything else (see Choosing a Model).

  2. Instructions — the role or persona, goals, rules and output format: the system prompt and anything that shapes behaviour before the first step.

  3. Tools — the actions the agent can take and the information it can fetch (see Tool Design).

  4. Memory — what the agent knows beyond the current prompt: the thread’s history, and long-term knowledge about users, past experiences and procedures (see Memory).

  5. Orchestration — the loop that ties them together: how the next step is chosen, how plans are made and revised, when to stop, and the limits that bound it (see Agent Loop & Architectures and Planning).

The model, tools, memory and orchestration split follows the component model in Albada’s Building Applications with AI Agents; making instructions (Lanham’s "profile / persona") a component of its own follows the five-part framing in Lanham’s AI Agents in Action — see the bibliography below.

The autonomy ladder

Autonomy is a dial, not a switch, and the right setting is usually different for each action an agent can take:

Level What the system does

Assist

The model drafts; a person decides and acts. (A chat assistant.)

Suggest (confirm before execute)

The agent proposes a concrete action; a person approves, edits or rejects it before it runs.

Act with oversight

The agent acts on its own and reports; a person can review, undo and stop it.

Autonomous

The agent acts on its own within budgets and policies, and escalates only on exceptions.

DocsAssistant acts on reads (searching the docs) and only suggests on its one write (opening an issue). Moving an action up the ladder should follow evidence — how often reviewers approve its suggestions unchanged — and moving it down must be a configuration change (see the autonomy slider).

What’s covered

Foundations

  • Agent Loop & Architectures — the perceive-reason-act-observe loop; reflex, ReAct, plan-and-execute, query decomposition, reflection/Reflexion and deep research; tree of thoughts and self-consistency as reasoning aids.

  • Workflow Patterns — prompt chaining, routing, parallelisation, orchestrator-workers and evaluator-optimizer in LangGraph, LangChain4j and Spring AI.

Tools and context

  • Tool Design — function-calling mechanics, designing tools for agents, least-privilege stateful tools, OpenAPI-generated tools, semantic tool selection and write-action safety.

  • Context Engineering for Agents — the per-step context budget, compaction, scratchpads, sub-agent isolation and just-in-time tool results.

Memory and planning

  • Memory — short- vs. long-term memory, the memory taxonomy, LangGraph checkpointers and stores, LangChain4j and Spring AI chat memory, and privacy and retention.

  • Planning — sequential vs. stepwise planning, re-planning, behaviour trees and back-chaining, reasoning models as planners, and failure modes.

Multi-agent

  • Multi-Agent Systems — when to add agents; supervisor, hierarchical, handoff, democratic and actor-critic topologies; shared vs. isolated state; distributed agents.

  • Agent-to-Agent Protocol (A2A) — Agent Cards, tasks, messages and artifacts, streaming, push notifications, signed cards, and MCP vs. A2A.

Humans and quality

  • Human-in-the-Loop — approval gates, interrupt and resume, escalation thresholds and the autonomy slider.

  • Agent Evaluation — component vs. end-to-end evals, trajectory evaluation, tool-call accuracy, LLM-as-judge rubrics and regression suites.

  • Agent Guardrails & Safety — the agent threat table, MAESTRO, the OWASP agentic Top 10, and policy layers, sandboxing, budgets, audit trails and kill switches.

  • Agent UX — sync vs. async interaction, streaming steps, communicating confidence, graceful failure, trust calibration and proactive behaviour.

  • Observability for Agents — traces and spans per step, the OpenTelemetry GenAI conventions, LangSmith/Langfuse/Phoenix, Spring AI observations, shadow deploys and canaries.

Landscape

  • The 2026 Agent Frameworks Landscape — a dated comparison of twelve frameworks, the 2026 deprecations, and how to choose.

  • Learning & Improvement — few-shot exemplars and Reflexion memories, fine-tuning with SFT, DPO and RLVR, feedback loops, and Thompson-sampling bandits.

Cheat sheet

  • Cheat Sheet (PDF) — a single-page, printable summary of every concept in this sub-section.

Related pages

Bibliography

The following sources were consulted while preparing this sub-section’s pages. Every class, method, field and protocol name was checked against the installed packages, the official source repositories or the specifications listed here on 2026-09-28 — never copied from a book.

Requester-provided books, consulted for concepts only and never the source of an example:

Official documentation

LangChain and LangGraph:

LangChain4j:

Spring AI:

Other agent frameworks:

Observability tools:

Other tools and APIs referenced:

Specifications and standards:

Papers and engineering articles:

Deprecations:

Security:

Worked example:

These books are consulted references, not the primary source of any example on this sub-section’s pages. On any discrepancy between a book and a framework’s own official documentation or a protocol’s specification, that documentation is authoritative.