GraphQL for AI Agents (Beyond MCP)
Classes: 12 | Total time: ~9.5 hours | Difficulty: Advanced
What This Course Covers
Our MCP course covers the Model Context Protocol. This course covers the wider question: how to expose a GraphQL API safely to LLM agents. The agent can run on Spring AI, LangChain4j, LangGraph4j or a custom orchestrator. Along the way we add cost controls and persisted queries, and we build the tools from your existing schema descriptions.
The course covers, in order:
- the schema-as-tool-spec mental model, and auto-generating tool definitions from a GraphQL schema
- schema navigation at scale: retrieval over schemas too large to send whole, measured against the AI Working Group's proposed benchmark data
- the safety layers: an approval gate at the execution layer, run budgets, and the server-side caps underneath both
- the framework track across LangChain4j, LangGraph4j and Spring AI, with tool-call streaming
- structured output through fragments, and
@deferfor partial responses - cost accounting per agent run, and testing agent-driven queries
- a closing look at the code-execution alternative to tool calling
The course is Java throughout. The main line uses Spring Boot 4 and Spring AI 2.0. LangChain4j (1.19) and LangGraph4j (1.8.24, pinned) each get their own lesson in the framework track. Every hands-on chapter runs against local models through Ollama, so the whole course works without an API key.
Target Audience and Prerequisites
This course is for senior engineers who build agent features in production, such as chat assistants, research agents, and internal tools that act on a user's behalf. The typical reader has a GraphQL backend and wants to expose it as agent tools without a custom integration each time. The course requires working knowledge of GraphQL and Spring Boot, and familiarity with at least one agent framework, such as Spring AI or LangChain4j. It starts from that knowledge and does not teach agent basics.
You do not need to bring a GraphQL backend of your own. We use the Movie Database service, which began in our Spring GraphQL tutorial and gained extra domain objects for this course. It is the backend application that provides the data for our requests, and its GraphQL API is the one our agent queries.
Two repositories are involved, both public. graphQLMovieDB-agents holds that backend: you start it in a terminal and leave it running. graphQLBeyondMCP is the project we write the agent in, so that is the one to open in your IDE. Clone both, and begin on graphQLBeyondMCP's main branch, which carries the project skeleton and the schema snapshot these classes build on. Later lessons each have a branch of their own, agents_class_N, so you can join partway through. Class 2 gives the commands.
Bring a reading knowledge of GraphQL introspection, because Class 2 walks a schema in code. The course is self-contained, and two of our other courses are useful alongside it:
- MCP course is the closest one. This course covers any agent framework, MCP-aware or not. You can read either one first; reading the MCP course first gives a useful contrast for Class 1's framing.
- Designing for errors, in our GraphQL introduction, is the foundation for the typed errors that Classes 4 and 8 rely on. Its result-types and errors-as-data strategies are worth reading before Class 4 if your schema does not yet use union-typed errors.
Some chapters need background this site does not yet cover in course form, such as persisted-document manifests, complexity calibration, or incremental delivery internals. Those chapters explain what they need inline, and link the primary sources in their Further Reading section.
Chapter List
Classes 5 to 7 form the framework track: the same catalog driven by LangChain4j, LangGraph4j, and Spring AI. Pick the lesson matching your stack and read the others as comparison. Classes 8 to 12 write their code against Spring AI, since the examples need one framework to be written in, but what those classes teach applies to all three.
The lessons build on each other along one main line, with two exceptions. Class 3 uses its own project, graphQLSchemaNav, and you can read it whenever you meet the problem it solves. The framework track splits into three lessons, and the main line continues after them:
| # | Title | What it covers |
|---|---|---|
| 1 | The schema-as-tool-spec mental model | Why GraphQL schemas are unusually good as agent tool specs, the descriptions field as prompt material, the typed-arguments property, the partial-result property |
| 2 | Auto-generating tool definitions from a schema | Reading the schema introspection result, mapping types to JSON Schema for tool definitions, choosing which operations to expose, the field-by-field allow-list |
| 3 | Schema navigation at scale | Retrieval over schemas too large for any context window: corpus formats and why they matter, Lucene BM25 against a GraphQL-tuned embedding model running locally, the AI Working Group's proposed benchmark data, the context-budget dial, and the search/introspect/execute agent loop with live token accounting |
| 4 | Safety: approval gates, budgets, and the server's last word | The agent as an untrusted actor inside your authorization boundary, identity taken from a real login the model cannot choose, the approval gate placed where execution happens, hard run budgets, and the server-side validation and depth caps that hold when every layer above them fails |
| 5 | LangChain4j integration | The agent-as-interface AiServices model, bridging the generated catalog into ToolSpecification and ToolExecutor, and which safety controls survive a framework switch (and which move with the loop) |
| 6 | LangGraph4j integration | The agent loop as an explicit state machine: typed state channels, the budget as routing data, and the approval gate as a checkpointed interrupt with silent resumes for reads |
| 7 | Spring AI integration | The ChatClient and its advisor-owned tool loop, zero-bridge callback registration, provider-reported usage metadata, and streaming answers while tools execute mid-stream |
| 8 | Structured output via fragments | Fragments as shape contracts mirrored by Java records, the entity terminal, typed hallucination and the act-then-format remedy, and the page-wrapper curation lesson |
| 9 | Streaming and incremental delivery on the JVM | The three things called streaming: Flux-based model output with tools mid-stream, subscriptions as the push channel, and the current status of @defer and @stream on graphql-java and Spring for GraphQL, shown by running them |
| 10 | Cost accounting per agent run | Provider-reported usage priced into per-run dollars, tenant-tagged Micrometer counters and rate-based runaway alerts, prompt-caching economics, and budgets denominated in money |
| 11 | Testing agent-driven queries | Translation rules as unit tests, the catalog golden as a CI drift gate, safety behaviors proven against a stub server, and the three tiers of testing with a model in the loop |
| 12 | Beyond tool calls: code execution as an alternative | Anthropic's code-execution pattern and Cloudflare's code mode, translated to this course's frameworks; which parts of the architecture are reversible if the field moves that way (an epilogue; it produces analysis instead of new code) |