📄️ Overview: GraphQL for AI Agents (Beyond MCP)
GraphQL schemas as agent tool contracts: auto-generated tool definitions, LangChain4j, LangGraph4j, and Spring AI integration, persisted-query allow-lists for agents, and cost accounting per agent run.
📄️ Class 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, and the partial-result property.
📄️ Class 2: Auto-Generating Tool Definitions from a Schema
Walk the schema with graphql-java, translate operations into JSON Schema tool definitions, decide what agents may see with a reviewable allow-list, and wire the result into Spring AI's ToolCallback contract, proven against the running Movie Database service.
📄️ Class 3: Schema Navigation at Scale
Build a search layer over a 72,000-line GraphQL schema with two swappable retrieval backends, Lucene BM25 and a GraphQL-tuned embedding model running on your laptop, measure both against the AI Working Group's proposed benchmark data, and watch an agent navigate the schema on a token budget.
📄️ Class 4: Safety: Approval Gates, Budgets, and the Server's Last Word
Put the safety controls where execution happens: a real login the model cannot choose, an approval gate on every write, hard run budgets, and the server-side caps that hold even when everything above them fails, all verified against the running Movie Database service.
📄️ Class 5: LangChain4j Integration
Drive the same generated catalog with LangChain4j: the agent-as-interface programming model, the bridge from tool definitions to ToolSpecification and ToolExecutor, and what changes (and what must not) when the framework owns the loop.
📄️ Class 6: LangGraph4j Integration
Draw the agent loop: the same catalog as a LangGraph4j state machine, with typed state, a budget the routing edge reads, and the approval gate reborn as a checkpointed interrupt.
📄️ Class 7: Spring AI Integration
Finish the framework track in Spring AI: the ChatClient API, the advisor chain that runs the tool loop in Spring AI 2.0, tool registration without a bridge, tool search for large catalogs, and streaming answers while tools run.
📄️ Class 8: Structured Output via Fragments
Make the agent's answers as typed as its tools: GraphQL fragments as the shape contract, Java records as their mirror, Spring AI's entity terminal, and the hallucination that perfect typing cannot prevent.
📄️ Class 9: Streaming and Incremental Delivery on the JVM
Separate the three things called streaming: model-output streaming that works today, subscriptions as GraphQL's production push channel, and where @defer and @stream stand on the JVM, shown with a runnable command.
📄️ Class 10: Cost Accounting per Agent Run
Turn provider-reported token usage into per-run dollars and per-tenant Micrometer metrics, so the runaway agent becomes an alert instead of an invoice, with prices as configuration and caching economics understood.
📄️ Class 11: Testing Agent-Driven Queries
Turn the behaviours this course built into tests: the translation rules as unit tests, the catalog pinned against drift in CI, the safety controls checked against a stub server, and how to test the parts a model decides.
📄️ Class 12: Beyond Tool Calls: Code Execution as an Alternative
Anthropic's 'Code Execution with MCP' pattern dropped one workload's token usage from 150,000 to 2,000. The pattern applies beyond MCP, and it suggests a different shape for how agents call GraphQL. What it would mean for the agent we built, and which parts of it would still be worth having.