Multi-Agent AI Tutorial 2026: LangGraph + MCP + A2A End-to-End for Beginners

Q: What exactly is an "AI agent" in this tutorial, and how is it different from just calling an LLM API?

An AI agent in the sense this tutorial uses the term is a software component that does three things a one-shot LLM API call does not. It has a goal it pursues across multiple steps rather than a single prompt-and-response — the curriculum planner has a goal (produce a study plan), the explainer has a goal (write a clear explanation), the supervisor has a higher-level goal (run a study session to completion). It can decide what to do next based on intermediate results — when the explainer reads a note file via MCP and discovers the learner already wrote about the topic, it folds that into the explanation rather than ignoring it; when the supervisor receives the learner's answer it decides whether to advance or revise. It can use tools — invoking external capabilities (filesystem, APIs, other agents) rather than only producing text. A LangGraph agent makes those three properties explicit through state (the shared notepad that travels with the conversation), nodes (the steps the agent takes), edges (the rules that decide which step comes next), and tool bindings (the capabilities the agent has access to). The mental shift from "calling an LLM" to "running an agent" is the shift from a single round-trip to a small program where the LLM is one of several active components.

Q: Why this combination of LangGraph, MCP and A2A specifically — what does each one give me that the others do not?

The three technologies answer three different questions and the value of using them together is that they compose without overlap. LangGraph answers "how does my agent decide what to do next, and how does it remember things across steps?" — its primitives are state, nodes, edges, conditional edges, and the checkpointer; it is the orchestration layer that gives your agent shape and memory. MCP answers "how does my agent use tools that already exist in the world without writing custom integration code per tool?" — its primitives are tools, resources and prompts, exposed through a JSON-RPC server that any agent in any framework can connect to; it is the tool layer that gives your agent capability without bespoke glue. A2A answers "how do my agents call each other across processes, machines, or frameworks?" — its primitives are the agent card, the message lifecycle and the task store; it is the inter-agent layer that gives your agents the ability to compose with peers regardless of the framework used to build them. A useful test of whether you have understood the boundaries is to ask which protocol you would reach for to add a feature: tool access for one agent → MCP; cross-process delegation to another agent → A2A; orchestration logic, memory, or pause-and-resume → LangGraph.

Q: Why does this tutorial use a free Gemini key by default rather than running a local LLM with Ollama?

Because the goal of a beginner tutorial is to remove every preventable obstacle between the learner and the moment the system actually runs. Local LLM setup adds a layer of friction that is genuinely off-putting on day one — you have to install Ollama (or LM Studio, or llama.cpp), pull a multi-gigabyte model file, configure your environment to find it, deal with quantisation choices that affect output quality, and accept latency and quality that is meaningfully worse than what hosted free-tier providers deliver. Gemini 2.0 Flash on the free tier needs no credit card, no install, no model file, and one environment variable to enable; the same code path works with Groq (also free, very fast inference) and OpenAI (paid, cheap) by changing the same environment variable. The provider-switch pattern in `llm_factory.py` is designed precisely so that swapping in a local model later is a one-line change — once you have understood the agent patterns, you can drop in `langchain-ollama` and point at a local server with no other code changes. The architectural lesson is that the LLM call site should be a single replaceable component, not scattered through your agent code.

Q: What is human-in-the-loop in LangGraph, and how does the `interrupt()` primitive actually work?

Human-in-the-loop is the pattern where an agent pauses execution to let a human supply input — an answer to a question, an approval of a proposed action, a clarification of intent — and then resumes from exactly the point it paused at. LangGraph provides the `interrupt(value)` primitive specifically for this: when a node calls `interrupt({"question": "...", "options": [...]})`, the graph freezes execution, the interrupt value is returned to whoever invoked the graph, and the graph waits. The caller is then responsible for collecting the human input and resuming the graph by calling it again with `Command(resume=value)`. The crucial property is that `interrupt()` is not an exception, not a sleep, and not a callback — it is a graph primitive backed by the checkpointer. Because the entire graph state is checkpointed when the interrupt fires, you can wait minutes, hours, or days before resuming, and the resumption restores the exact state the graph was in. This is what enables approval-gate workflows in production agents: the supervisor proposes an action, calls `interrupt()` with the proposal, the proposal is shown to a human reviewer in a UI, the reviewer approves or rejects whenever they get to it, and the agent picks up where it left off. The same pattern underpins clarifying-question flows, document review flows, and any workflow where the agent and the human need to take turns.

Q: What does LangGraph checkpointing actually buy me, and when should I move from SQLite to Postgres?

Checkpointing is the property that turns an agent from a script into a durable conversation. After every node executes, LangGraph serialises the entire graph state and writes it to the checkpointer's storage backend, indexed by a `thread_id` you supply. When you re-invoke the graph with the same thread id, LangGraph rehydrates the state and continues from the last completed node. The benefits compose. Crash recovery: if your process dies between two nodes the next invocation picks up from the last successful node rather than from the beginning. Pause-and-resume: this is what makes `interrupt()` work — the graph state is on disk between the pause and the resume. Multi-session memory: a thread id that maps to a user means that user's conversation persists across sessions, runs and machines. Time-travel debugging: LangGraph exposes the checkpoint history so you can inspect any past state, branch from a past state, or roll back to a past state. SQLite via `AsyncSqliteSaver` is perfect for laptops, prototypes and single-process apps; the file is local, the latency is microseconds, the operational burden is zero. Move to Postgres via `AsyncPostgresSaver` when you have multiple worker processes that need to share state (so the checkpoint store is shared infrastructure rather than a per-process file), when you need backups, replication and the operational tooling Postgres gives you, or when you have a write-heavy production workload that exceeds what a SQLite file can absorb.

Q: What is the agent card in A2A and why does it matter to make my agent discoverable that way?

The agent card is a small JSON document hosted at the well-known URL `/.well-known/agent-card.json` on every A2A-compliant server. It declares the agent's name, description, version, the URL endpoints it serves, the input and output modes it supports (text, audio, image), and the skills it offers (named capabilities with descriptions and example payloads). It matters because it is the discovery contract that turns ad-hoc HTTP calls between agents into a standardised, introspectable network of cooperating agents. Three concrete benefits. Cross-framework interoperability: a LangGraph supervisor can discover and call a CrewAI agent (or AutoGen, or vendor X) without knowing anything about the framework on the other side — the agent card describes the contract, the JSON-RPC message lifecycle implements it. Self-documenting capability: the skills listed on the card are designed for both human reading (so a developer browsing your agent fleet can see what each agent does) and machine reading (so a router or supervisor can decide which agent to call based on capability metadata). Operational hygiene: versioning the agent card makes capability evolution explicit — when an agent gains a new skill, the card update is the formal announcement; when a skill changes contract, the version bump is the signal to clients. The pattern is the same one OpenAPI / Swagger established for REST APIs, adapted to the agent context where capability is more semantically rich than endpoint paths.

Q: How do I add a fifth agent to this system — what is the recipe, and what should I avoid?

The recipe depends on which slot the new agent fits into. If the new agent is a standalone capability the supervisor needs (a Source Finder that searches the web, a Spaced-Repetition Scheduler that decides when to reintroduce a topic, a Sentiment Analyser that gauges the learner's frustration), package it as an A2A server in its own process — copy `quiz_server.py`, change the skills, change the executor logic, run on a different port — and add a call from the supervisor using the same `httpx`-based pattern the coach uses for the quiz agent. If the new agent is a tool-using specialist that fits inside the supervisor's graph (a Note-Taking agent that writes the session summary into the notes folder), add it as a new node in `coach.py` with its own LangGraph subgraph or function. If the new agent is a peer to the existing four with its own decision logic and state, package it as its own LangGraph supervisor with its own checkpointer and expose it over A2A; the existing supervisor calls it as a peer. Avoid three traps. The first is overloading existing agents with new responsibilities — if the explainer also has to schedule reviews, you have lost the specialisation benefit; resist the urge and add a new agent. The second is making everything an A2A server — process boundaries cost latency, ops complexity and debuggability, and only earn their keep when you genuinely need the boundary (different team owns it, different language, different deployment cadence). The third is creating circular dependencies between supervisors — keep the call graph a DAG so failure modes and traces stay tractable.

Q: What are the most common beginner mistakes when wiring LangGraph + MCP + A2A together for the first time?

Five mistakes catch almost everyone the first time. Returning the wrong shape from a node — LangGraph nodes return a dict containing only the keys you want to update, not the entire state; returning the entire state usually works by accident but makes future debugging harder. Forgetting `bind_tools` after configuring tools — the LLM does not know about tools you have not bound; you can have the perfect MCP server running and a perfectly capable LLM and watch the LLM never call a single tool because you bound the tools to the wrong model instance. Confusing `add_messages` reducer behaviour — fields annotated with `add_messages` are appended to, not replaced; if you return `{"messages": [single_msg]}` you append one message; if you return `{"messages": full_history}` you append the full history again, doubling the context every turn. Mixing `async` and sync incorrectly — `MultiServerMCPClient` is async; if you accidentally call it from a sync context you will get the wrong thing or a deadlock; pick one mode (we used async in the explainer and supervisor) and be consistent. Forgetting the quiz server is a separate process — running the coach without first starting the quiz server gives a confusing `httpx.ConnectError`; the lesson generalises to any A2A topology, and the operational discipline is to start your peer agents (or your service-mesh equivalent) before the supervisor that calls them.

Q: Should I use LangGraph for everything, or are there cases where the framework is overkill?

LangGraph earns its keep when your agent has any of these properties: more than one logical step, a need to remember state across steps, branching logic that depends on intermediate results, tool calling with retry or recovery logic, human-in-the-loop pauses, a need to inspect or replay past executions. If your use case has *none* of those — you are calling the LLM exactly once with a fixed prompt and returning the response to the user — LangGraph is overkill and a simple `model.invoke(prompt)` call is the right answer. The interesting middle ground is the case where you have a single LLM call but you want observability, retries, or eventual extension; for those, the overhead of a one-node LangGraph (which is genuinely small) is usually worth it because you keep the door open for adding state, tools or a second step later without rewriting the call site. The pattern we use in `agents/planner.py` — a one-node LangGraph wrapping a single structured-output LLM call — is exactly that compromise: it is barely more code than a direct call, but it slots cleanly into the supervisor graph and benefits from the same tracing, checkpointing and structure as everything else.

Q: What should I read or build next once this tutorial works on my laptop?

Three concrete progressions, in increasing order of architectural ambition. Replace the in-memory pieces with persistence and observability — swap the SQLite checkpointer for Postgres, add the official MCP memory server alongside the filesystem server so the explainer remembers facts across sessions, ship Langfuse traces to a shared project so the whole team sees what the agents are doing. The lesson at this stage is that a multi-agent system with persistent state and shared traces starts to feel like a real product rather than a demo. Add a second A2A peer and feel the topology grow — a Source Finder that searches the web, a Slide Generator that turns explanations into slide outlines, a Spaced-Repetition Scheduler that decides what to revisit and when. The supervisor pattern composes naturally with two, three, four peers; at five or six peers you start to want a real router and a real capability registry. Move the evaluation discipline up the maturity curve — add DeepEval test cases for every agent, run them in CI on every commit, add red-team prompts to the test corpus, set quality thresholds that block merges. The cumulative effect of these three progressions is the production-shape architecture covered in our [agent mesh architecture](https://appscale.blog/blog/ai-agent-mesh-architecture-multi-agent-coordination-2026), [agent memory tiers](https://appscale.blog/blog/agent-memory-architecture-episodic-semantic-procedural-the-three-tier-pattern-2026) and [LLM gateway](https://appscale.blog/blog/enterprise-llm-gateway-architecture-routing-rate-limiting-observability-2026) articles, each of which picks up where this tutorial leaves off and walks one architectural axis in detail.