The designing-real-world-ai-agents-workshop Repo: Two MCP Servers, a Skeleton, and a Self-Imposed Blindfold
Hands-on workshop: Build a multi-agent AI system from scratch — Deep Research Agent + Writing Workflow served as MCP servers. Includes code, slides, and video
At a glance
- What is it?
- This repository packages a conference workshop as runnable code: a Deep Research Agent and a LinkedIn Writing Workflow, both exposed over the Model Context Protocol. Its most interesting design decision is not the agents but the implement_yourself folder, which forces you to rebuild the system without seeing it.
- Who is it for?
- Adopt this if you already write Python and want a working reference for MCP server design, Gemini search grounding, and an evaluator-optimizer loop you can read end to end. Skip it if you need a supported library, a published package, or production hardening guidance, because none of that is in the material.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 105 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
What the Workshop Actually Ships, and Who It Is Built For
The repository is the companion code for a talk given at AI Engineering Conference Europe, and it is organized around three consumption modes rather than around a library API. You can watch the recording and read the slides, which the README estimates at about two hours. You can run the finished code, which the README estimates at about thirty minutes. Or you can rebuild the system yourself from a stripped-down skeleton, which the README estimates at two to four hours.
The audience is therefore narrow and specific: a Python developer who already understands what an LLM tool call is, wants to see a multi-agent system assembled rather than described, and is willing to work inside someone else's harness. The README frames the workshop itself as a taste of a longer paid course, and the repository links to that course repeatedly. That is worth knowing before you invest an afternoon, because the free material is a demonstration, not a maintained framework.
The concrete deliverables are two MCP servers. The Deep Research Agent takes a topic and produces research.md. The LinkedIn Writing Workflow takes research.md plus a guideline and produces post.md plus a generated image. Everything else in the repo exists to support those two artifacts.
The Two Pipelines, Step by Step
The README gives both data flows in a compact notation, and they are worth reading literally. The research pipeline is written as: user topic, then deep_research called N times, then analyze_youtube_video if URLs are present, then a deep_research gap-fill pass, then compile_research, ending in research.md. The gap-fill stage is the part that distinguishes this from a single search call. The agent is expected to notice what the first round missed and issue more queries before compiling.
The writing pipeline is written as: research.md plus a guideline, then generate post, then a review and edit cycle repeated N times, ending in post.md, followed by image generation. That review and edit cycle is the evaluator-optimizer loop the README names as one of the taught patterns. The loop count is not fixed in the diagram; N appears in both pipelines, which means the termination condition is something you inspect in the code rather than something the README specifies.
Both servers register tools, resources, and prompts through FastMCP, and both are meant to be driven by an MCP-compatible harness such as Claude Code or Cursor. The README also lists the supporting patterns: grounded search through Gemini with Google Search grounding, structured output validated by Pydantic schemas, and LLM-as-judge scoring through Opik. The example post embedded in the README shows the pipeline's own output arguing that most teams over-build multi-agent systems, which is a slightly awkward position for a multi-agent workshop repo to publish, and also the most honest thing in it.
Getting It Running: What the README Specifies and What It Leaves Open
The README points to a Getting Started section and a Running the Code section as the canonical install path, and it names the components you will be running: the MCP servers, the skills, and the evaluation pipeline. It does not reproduce the individual shell commands in the material available here, so treat the repository's own Getting Started section as the source of truth rather than any command you might reconstruct from the description.
What the material does establish is the shape of the setup. You install the project, start two MCP servers, and then point a harness at them. The harness is not bundled; Claude Code and Cursor are named as examples, and the architecture diagram describes the servers as connecting to a harness of that kind. That means your first real configuration step is editing your harness's MCP server list, and the repository does not ship that configuration for you.
Two environment-level dependencies are implied by the described features rather than spelled out. Gemini with Google Search grounding backs the research pipeline, so a Google API credential is required somewhere in the config. Opik backs the LLM-as-judge evaluation, so that service needs to be reachable as well. If you are evaluating this repo for a locked-down environment, those two external dependencies are the first thing to check, and the README as supplied does not tell you how they are wired.
The implement_yourself Folder Is the Real Product
The most distinctive part of the repository is implement_yourself/, described as a self-contained skeleton with 25 pre-groomed tickets and a custom /implement Claude Code skill. The skill orchestrates SWE and Tester agents in a loop, working ticket by ticket until the skeleton directory matches src/.
The isolation is deliberate and enforced by working directory rather than by permissions. The README instructs you to open your harness directly inside implement_yourself/ rather than at the repository root, so the agents' working directory is scoped to the skeleton and they cannot see, grep, or read the reference implementation in ../src/. The README calls this no cheating by design. Whether the isolation holds depends on your harness honoring the working directory, which is an assumption the repository makes rather than a guarantee it enforces. A harness that resolves paths outside its working directory, or an agent that decides to look upward, would break the premise. That is a real limitation worth testing on the first ticket rather than on the twentieth.
The pedagogical payoff is genuine, though. Reading a finished multi-agent system teaches you what the code looks like. Rebuilding one ticket by ticket teaches you which decisions were load-bearing. The 25-ticket decomposition is the actual curriculum here, and it is more interesting than the finished src/ tree.
Where the Material Runs Thin
The README is a workshop landing page, not reference documentation. Several things you would want before adopting any of this are simply absent from the supplied material. There is no changelog, no release history, and no version pinning guidance. The repository has no published releases, so there is no tagged artifact to depend on. If you build on this, you are tracking the main branch.
The loop counts are the sharpest gap. Both pipelines show N iterations without stating what N defaults to, whether it is configurable, or what stops the loop. For the evaluator-optimizer cycle specifically, the stopping rule matters more than the generation step, because an unbounded review-and-edit loop is the classic way these systems burn tokens without improving output. The README does not describe a convergence check or a maximum iteration count, and the LLM-as-judge scoring through Opik is presented as evaluation rather than as the loop's termination signal. Do not assume those are connected.
Cost and latency are also unaddressed. The research pipeline issues multiple grounded search calls plus YouTube analysis plus a gap-fill round, and the writing pipeline layers an iterative loop on top. The README gives time estimates for the human, not for the machine. Anyone planning to run this against a large topic set should measure that themselves rather than infer it from the workshop's pacing.
How This Differs From LangGraph or CrewAI
The obvious comparison is a multi-agent framework such as LangGraph or CrewAI, and the difference is architectural rather than stylistic. Those frameworks give you an in-process orchestration layer: you define agents and edges in Python, and the framework runs the graph inside your application. This repository inverts that. The agents are servers, and the orchestrator is an external harness that speaks MCP.
That inversion has consequences. You do not write the control flow; the harness's model decides which registered tools to call and when. The README names this pattern directly as tool-use agents, letting the LLM decide which tools to call and when. You get less determinism than a hand-written graph and more flexibility in what can drive the system, since any MCP-compatible client can attach to the same servers.
The trade-off is that debugging moves. With LangGraph you can step through a graph in a debugger. Here, the reasoning that selects tools lives in the harness, outside your code, and your server only sees the calls that arrive. If a research run goes wrong, you are reconstructing intent from tool invocation logs rather than from a graph state you control. For a workshop that is a fine trade. For a system you operate, it is the thing to think hardest about.
Licence and the Cost of Keeping Up
The repository is MIT licensed, which permits commercial use, modification, and redistribution provided the copyright notice and permission notice are preserved. That is a permissive licence and it does not impose copyleft obligations on your own code. It applies to this repository's code; the models and services the pipelines call (Gemini, Opik, and whichever harness you attach) carry their own terms, and nothing in the MIT grant changes those. This is a description of the licence text, not legal advice, and if you plan to ship something derived from this, read the actual LICENSE file and the terms of the services you connect.
Maintenance cost is the harder question, and the material points to the answer indirectly. There are no releases, so upgrades mean pulling main and reconciling whatever changed. The project depends on FastMCP, Pydantic schemas, a Google-grounded model, and Opik, and each of those moves on its own schedule. A workshop repo is typically maintained around the event it was written for, and the last push date is the only signal available here about ongoing activity. There is no deprecation policy, no migration guide, and no stated support window. Budget for reading diffs yourself, or pin to a commit and accept that you are frozen.
Editorial conclusion
Adopt this if you already write Python and want a working reference for MCP server design, Gemini search grounding, and an evaluator-optimizer loop you can read end to end. Skip it if you need a supported library, a published package, or production hardening guidance, because none of that is in the material. Before you start, open implement_yourself/README.md and confirm the ticket count and the /implement skill still match the src/ layout, and check the install steps in Getting Started against the Python and dependency versions your machine actually has.
Community notes