An educational, open-source Java & Spring Boot mini-agent platform powered by LangChain4j 1.22, Google Gemini (gemini-3.8-flash), HTMX, and Bootstrap 5.
Designed specifically to demystify how AI agents work under the hood by exposing every micro-step of the ReAct reasoning cycle, parameter negotiation, local method reflection, observation injection, Model Context Protocol (MCP) wire traffic, token consumption, and disk auditing.
- Why This Project?
- Architecture & ReAct Flow
- Dual-Engine Modes
- Key Features & Components
- Quick Start
- Workshop Curriculum
- Hands-on Exercises Overview
- Observability & Disk Audit Logging
- Project Structure
- Running Tests
- License
Most agent frameworks and tools operate as opaque "black boxes," leaving engineers confused about:
- How does the LLM actually decide when and how to call a tool?
- What does the exact raw JSON payload sent to the LLM look like?
- How does context window growth, prompt caching, and token pricing accumulate during a multi-step task?
- How does the Model Context Protocol (MCP) decouple tools across processes using JSON-RPC 2.0?
- How do we audit and log every step to disk for compliance, determinism, and debugging?
This project provides a 100% transparent ("Glass-Box") engine with a real-time reactive UI, live SSE streams, and comprehensive disk logging.
flowchart TD
User(["User / Learner"]) -->|Query via HTMX UI| Web["Spring Boot Web Controller"]
Web --> Engine["Transparent Agent Engine"]
subgraph GlassBox ["Glass-Box Execution Loop"]
Engine -->|1. Context & Tool Schemas| Req["Raw Model Request Payload"]
Req -->|2. HTTP POST| Gemini["Google Gemini API (gemini-3.8-flash)"]
Gemini -->|3. Tool Execution Request| Reason["Agent Decision & JSON Args"]
Reason -->|4. Method Dispatch| Tools["Java Tools: Calc, Files, System, Web"]
Tools -->|5. Observation / Result| Memory["Chat Memory & Message List"]
Memory -->|6. Re-evaluate / Final Answer| Gemini
end
Engine -->|Real-Time SSE Events| UI["Live Stepper UI & Token Meter"]
Engine -->|Complete Audit Traces| Disk[("./logs/sessions/ Audit Trail")]
Switch between two execution paradigms with a single click in the navigation bar:
- Tools are standard Spring beans annotated with LangChain4j's
@Tool. - Parameter binding and method execution occur via Java reflection within the application JVM.
- Perfect for understanding the core ReAct loop, schema generation, and reflection dispatch.
- The agent acts as an MCP Client communicating over JSON-RPC 2.0.
- Tools are dynamically discovered via
tools/listand executed across isolated MCP servers:- Local MCP Server (
LocalMcpServer): Exposes mathematical calculation, system diagnostics, and file inspection over JSON-RPC. Also runnable as an external process over standard I/O (stdio). - Open-Meteo Weather MCP Server (
OpenMeteoWeatherMcpServer): Live global weather forecasting and geocoding via Open-Meteo REST APIs (zero API keys required). - Diagnostic Remote MCP Endpoint: Demonstrates cloud-hosted MCP endpoint monitoring and error isolation.
- Local MCP Server (
- Full JSON-RPC request/response payloads and sub-millisecond latencies are rendered in collapsible purple wire drawers in the UI.
| Component | Description |
|---|---|
| Two-Pane Glass-Box Dashboard | Left: Interactive Chat with prompt presets. Right: Live ReAct execution timeline, step-by-step inspector, and token meters. |
| Dual-Mode Engine Toggle | Switch seamlessly between Classic In-Process Agent and Model Context Protocol (MCP) Agent. |
| Interactive MCP Hub & Wire Inspector | Built-in modal dialog displaying active MCP servers, registered tool schemas (tools/list), and microsecond-level wire traffic (mcp_traffic.jsonl). |
| Real-Time Streaming (SSE) | Steps and wire events broadcast live from Java to browser via Server-Sent Events (/api/stream/{sessionId}). |
| Full Disk Audit Logging | Every turn is saved to ./logs/sessions/{sessionId}/ with summary.json, trace_events.jsonl, raw_payloads.json, mcp_traffic.jsonl, and human-readable transcript.md. |
| Extensible Tool Suites | Classic Java @Tool suite + Dual MCP Servers (Local System/Math/Files server + Live Open-Meteo Weather server). |
| Configurable Model & Thinking Budget | Defaults to gemini-3.8-flash with medium thinking budget. Also supports gemini-3.7-flash, gemini-3.5-flash-lite, gemini-3.1-flash-lite, gemini-2.5-pro, and an offline mock engine. |
- Java 21+ installed (
java -version) - Maven 3.9+ installed (
mvn -version) - A Google Gemini API Key (or run offline with the built-in Mock Agent!)
# Clone the repository
git clone https://github.com/xceptance/ai-mini-agent-workshop.git
cd ai-mini-agent-workshopConfigure your Gemini API key in any of the following ways (evaluated in priority order):
- Local File (Recommended for local dev): Create an
api.keyfile in the project root:echo "AIzaSy..." > api.key
- Environment Variable:
export GEMINI_API_KEY="AIzaSy..."
- Application Properties: Edit
src/main/resources/application.ymlor pass-Dgemini.api-key=... - Offline Mock Mode: If no key is detected, the application automatically launches in Offline Mock Mode, allowing you to explore the UI and execution lifecycle without external credentials!
mvn spring-boot:runOpen your browser to: http://localhost:8080
- Math & Date Tool Execution:
"What is 453 * 289, and what is the current date and time?"
- File System Inspection:
"Inspect pom.xml and tell me which version of LangChain4j is configured."
- Model Context Protocol (MCP Mode):
Switch to MCP mode in the navbar and ask: "What is the weather like in Tokyo right now?"
- Multi-Step Reasoning:
"Check the system memory and disk space, then calculate how many megabytes are free."
Comprehensive conceptual and practical guides are available in the docs/ directory:
- 01. What is an AI Agent? β Core theory, LLM vs. Agent, ReAct loop, context window mechanics, and prompt engineering.
- 02. How Tool Calling Works β JSON Schema generation, parameter binding, reflection dispatch, and observation injection.
- 03. LangChain4j Architecture β High-level
AiServicesdeclarative abstractions vs. low-level transparent Java loops. - 04. Observability & Token Logging β Inspecting disk traces, token meters, cache hits, cost accounting, and debugging loops.
- 05. Workshop Exercises & Solutions β 13 hands-on progressive coding challenges covering tools, OpenSpec SDD, AGENTS.md, mutation testing, and MCP servers.
- 06. Quality Work with Agents β The 4 Pillars of Agentic Quality: History, Context, Specs (OpenSpec), and Deterministic Engineering Workflows.
- 07. Model Context Protocol (MCP) β MCP architectural deep dive, JSON-RPC 2.0 wire protocol, tool negotiation, transports (
stdiovshttp), and building custom MCP servers in Java. - Workshop Master Planning & Catalog β Modular workshop profiles, master content catalog, open standards, and organizational playbooks.
The workshop includes practical, progressive exercises (detailed in docs/05_WORKSHOP_EXERCISES.md):
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β 1. THE WILD WEST (LRUClockMap) β
β Prompt an unconstrained agent on a zero-allocation hash map. Witness β
β flaky timing tests, broken cache locality, and deleted test assertions. β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β 2. DISCIPLINED ENGINEERING (AGENTS.md + TDD + Mutation Testing) β
β Apply strict guardrails, characterization tests, and JaCoCo / Pitest to β
β kill surviving mutants and guarantee high-assurance agent output. β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β 3. SPEC-DRIVEN APPLICATION ("CueCards" + OpenSpec + MCP) β
β Design and build a collaborative memory board with OpenSpec, expose it β
β over an MCP Server, and interact live with external agents via JSON-RPC. β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
Every agent run writes a full audit trail to ./logs/sessions/{sessionId}/:
logs/sessions/d921b714-3d96-4eb1-995c-7d9219df08f3/
βββ summary.json # Overall duration, total token usage, cached counts, and status
βββ transcript.md # Formatted, human-readable record of reasoning and dialogue
βββ trace_events.jsonl # Granular micro-step timeline with millisecond timestamps
βββ raw_payloads.json # Unedited HTTP request/response payloads exchanged with Gemini
βββ mcp_traffic.jsonl # Exact JSON-RPC 2.0 wire frames (requests, responses, latency)
Tip
You can inspect these logs directly inside the running application using the built-in Log Viewer Modal or open them in your IDE for offline auditing.
ai-mini-agent-workshop/
βββ pom.xml # Spring Boot 4.1 & LangChain4j 1.22 dependencies
βββ README.md # Workshop documentation & quick start guide
βββ api.key.example # Example Gemini API key template
βββ docs/ # In-depth educational guides & exercises
β βββ 01_WHAT_IS_AN_AGENT.md # ReAct loop, context window, agent theory
β βββ 02_HOW_TOOL_CALLING_WORKS.md # JSON Schemas, parameter binding, reflection
β βββ 03_LANGCHAIN4J_ARCHITECTURE.md # LangChain4j abstractions vs manual Java loop
β βββ 04_OBSERVABILITY_AND_LOGGING.md # Traces, tokens, cost accounting, debug techniques
β βββ 05_WORKSHOP_EXERCISES.md # 13 hands-on progressive coding exercises
β βββ 06_QUALITY_WORK_WITH_AGENTS.md # The 4 Pillars: History, Context, Specs, Determinism
β βββ 07_MODEL_CONTEXT_PROTOCOL_MCP.md # MCP Architecture, JSON-RPC 2.0 wire protocol
β βββ workshop-planning.md # Workshop profiles, master content catalog & playbooks
βββ src/main/java/com/workshop/agent/
β βββ MiniAgentWorkshopApplication.java # Spring Boot entry point
β βββ config/ # Gemini & ApiKey discovery configuration
β βββ engine/ # TransparentAgentEngine & McpAgentEngine ReAct loops
β βββ logging/ # Disk audit logger, Markdown transcripts, ANSI logs
β βββ mcp/ # Model Context Protocol implementation
β β βββ client/ # McpClientManager (discovery, schema mapping, dispatch)
β β βββ model/ # McpProtocolMessage, McpWireRecord, McpServerConfig
β β βββ server/ # LocalMcpServer & OpenMeteoWeatherMcpServer
β βββ model/ # Events, Session state, Token metrics, DTOs
β βββ tools/ # Java @Tool components & reflection registry
β βββ util/ # MarkdownRenderer and formatting helpers
β βββ web/ # HTMX endpoints, SSE streams, REST controllers
βββ src/main/resources/
β βββ application.yml # Agent properties, prompts & model configuration
β βββ logback-spring.xml # Logging configuration
β βββ static/ # Glass-box CSS styles and reactive JavaScript
β βββ templates/ # Thymeleaf & HTMX templates (modals, drawers, steps)
βββ logs/sessions/ # Generated disk audit traces per session
Run the complete test suite (unit tests, integration tests, MCP tests, mock validations):
mvn clean testAll 52 tests execute in under 20 seconds, validating tool reflection, JSON-RPC protocol serialization, session persistence, and agent reasoning cycles without requiring active network credentials.
This project is licensed under the MIT License. Created for AI Agent Workshops & Educational Demonstrations.