Build Your Own Deep Research Agent + Technical Writer Multi-Agent System

A hands-on workshop, presented at AI Engineering Conference Europe, building a multi-agent AI system with two MCP servers: a Deep Research Agent and a LinkedIn Writing Workflow. Both connected to a harness like Claude Code or Cursor.

🎬 Full workshop available on YouTube ↓

📑 Slides here.

---

Whenever You’re Ready, Here’s How to Go Deeper

This workshop is a 2–4 hour taste. If you want to go from zero to shipping production-grade AI agents, check out our Agentic AI Engineering Course, built with Towards AI.

34 lessons. Three end-to-end portfolio projects. A certificate. And a Discord community with direct access to industry experts and us.

Rated 5/5 by 300+ students. The first 6 lessons are free:

Start here →

---

How to Use This Repo

Three ways to use this repo. Pick the mode that fits the time you have. Or work through all three in order, since each builds on the last:

1. Watch the workshop and see the patterns end-to-end. Watch in ~2 hr. Start with the 2-hour YouTube workshop and the slides above. You’ll come away with a mental model of the full multi-agent system: tool-use agents, evaluator-optimizer loops, grounded search, structured LLM output, and MCP-server design.

2. Run the finished code. See it produce real artifacts. Run in ~30 min. Watch the system generate a research brief, draft a LinkedIn post through an evaluator-optimizer loop, and score itself with an LLM-as-judge. Follow the Getting Started and Running the Code sections to install the project and run the MCP servers, skills, and evaluation pipeline.

3. Implement it yourself with agentic coding. Build a 1:1 replica from scratch in ~2–4 hr. Open implement_yourself/, a stripped-down skeleton prepared with 25 pre-groomed tickets and a custom /implement Claude Code skill that orchestrates SWE and Tester agents in a loop, ticket by ticket, until the directory matches src/. See implement_yourself/README.md for the kickoff guide.

   No cheating, by design. implement_yourself/ is a self-contained project. Open your harness (Claude Code, Cursor, …) directly in that folder (not at the repo root) so its working directory is scoped to the skeleton. The agents can’t see the reference implementation in ../src/, can’t grep it, can’t read its files. You get a real build, not a copy-paste.

What You’ll Build Today

Deep Research Agent — An MCP server that runs deep research using Gemini with Google Search grounding and native YouTube video analysis:

user topic → [deep_research] × N → analyze_youtube_video (if URLs) → [deep_research gap-fill] → compile_research → research.md

LinkedIn Writing Workflow — An MCP server that generates LinkedIn posts with an evaluator-optimizer loop:

research.md + guideline → generate post → [review → edit] × N → post.md → generate image

Both servers expose tools, resources, and prompts via the Model Context Protocol, letting any MCP-compatible harness orchestrate the workflow.

Patterns and concepts you’ll learn:

• Tool-use agents — letting the LLM decide which tools to call and when
• Evaluator-optimizer loop — generate, review, edit in cycles
• Grounded search — Gemini with Google Search grounding for factual research
• Structured LLM output — Pydantic schemas for type-safe model responses
• MCP server design — registering tools, resources, and prompts with FastMCP
• LLM-as-judge evaluation — automated quality scoring with Opik

Example: End-to-End Workflow

Here’s a real run through the full pipeline — from a topic seed to a published-ready LinkedIn post with an AI-generated image.

Final output

---

We planned 12 AI agents and shipped 1. It worked better. Sounds crazy, right? But it’s a common story.

A client built an AI marketing chatbot. Their initial design had dozens of agents: orchestrator, validators, spam prevention. It failed.

A single agent with tools won. Tasks were tightly coupled. One brain maintained context. Tools were still specialized.

This is the core mistake. People jump to complex multi-agent setups too fast.

Think AI system design as a spectrum:

• Workflows: You control steps.
• Single Agent + Tools: Model decides flow.
• Multi-Agent: Multiple decision-makers.

…

A single agent works for most cases. But it has limits. Too many tools? You hit “context rot.” Past ~10-20 tools, LLMs degrade at tool selection. They get overwhelmed. Information gets lost in the middle.

So, when do you actually need multi-agent?

…

The simplest system that reliably solves the problem is always the best system. Don’t overengineer your AI agents. Build simple first.

What’s the most complex agent architecture you’ve simplified? Tell me below.

Read the full post

Browse more full examples (seed, research, post drafts, reviews, final post + image) in the examples/ directory.

Tech Stack

Getting Started

Assumes working Python knowledge and basic familiarity with LLMs.

Prerequisites

Installation

1. Clone and configure:

   git clone https://github.com/iusztinpaul/designing-real-world-ai-agents-workshop.git
   cd designing-real-world-ai-agents-workshop
   cp .env.example .env          # add your GOOGLE_API_KEY (+ optional OPIK_API_KEY)
   

2. Install dependencies:

   uv sync
   

   Note: If you don’t have Python 3.12+, uv can install it for you: uv python install 3.12, then re-run uv sync.

3. Verify the setup:

   make test-end-to-end          # runs research + writing pipeline end-to-end
   

   If it completes without errors, you’re good to go.

Running the Code

There are four ways to run the workflows:

MCP Servers (recommended)

Connect the servers to an MCP-compatible harness (Claude Code, Cursor) for interactive use. This is the primary way to use the workshop.

Setup: The .mcp.json file is pre-configured. Both servers start automatically when you open the project in Claude Code or Cursor.

Usage:

1. Open the project in Claude Code or Cursor
2. Invoke an MCP prompt (e.g., research_workflow) to get guided through the full workflow
3. Or call individual tools directly for fine-grained control

Manual server start (advanced):

make run-research-server    # stdio transport
make run-writing-server     # stdio transport

Skills

Pre-built slash commands that orchestrate the MCP tools with sensible defaults. All output goes to outputs/{topic-slug}/.

Example:

/research-and-write

The skill will ask you for a topic and guideline, then run the full pipeline end-to-end. Check examples/ to see what each step produces.

Streamlit UI

A standalone chat UI that orchestrates both MCP servers via FastMCP — no harness required. Drop in a topic (or upload a .md / .txt seed file) and watch the pipeline run end-to-end with live per-stage progress: search counters, sources collected, evaluator-optimizer loop, and image generation.

make run-ui

Outputs land in outputs/{topic-slug}/ (same layout as the skills).

Evaluation (requires Opik)

The workshop includes an LLM-as-judge evaluation pipeline. Instead of manually reviewing each generated post, an LLM scores them against quality criteria (structure, tone, accuracy). Opik tracks these scores across runs so you can measure whether prompt or pipeline changes actually improve output quality.

make eval-dev               # LLM judge on dev split
make eval-test              # LLM judge on test split
make eval-online            # Generate + judge posts on the fly

Each command automatically uploads the dataset to Opik before running. To upload without evaluating (e.g., to browse in the Opik UI), use make upload-eval-dataset.

Project Structure

├── src/
│   ├── research/              # Deep Research Agent MCP server
│   │   ├── server.py          # FastMCP entry point
│   │   ├── config/            # Settings, constants, prompt templates
│   │   ├── models/            # Pydantic schemas for structured LLM output
│   │   ├── app/               # Business logic handlers
│   │   ├── tools/             # MCP tool implementations
│   │   ├── routers/           # MCP tool, resource, and prompt registration
│   │   └── utils/             # Gemini client, file I/O, Opik, markdown helpers
│   └── writing/               # LinkedIn Writer MCP server
│       ├── server.py          # FastMCP entry point
│       ├── profiles/          # Shipped markdown profiles (structure, terminology, character, branding)
│       ├── config/            # Settings, constants, prompt templates
│       ├── models/            # Pydantic schemas (Post, Review, Profiles)
│       ├── app/               # Business logic handlers
│       ├── evals/             # LLM judge metric, dataset upload, evaluation harness
│       ├── tools/             # MCP tool implementations
│       ├── routers/           # MCP tool, resource, and prompt registration
│       └── utils/             # Gemini client, Imagen, Opik helpers
├── datasets/                  # LinkedIn posts dataset with labels and splits
├── examples/                  # Full end-to-end output samples (seed → research → posts → image)
├── scripts/                   # Entrypoints and test scripts
├── .mcp.json                  # MCP server configuration for harnesses
├── Makefile                   # Command center
└── .env.example               # Environment variable template

Next Steps

Contributors

License

MIT License. See LICENSE for details.

Copyright © 2026 Paul Iusztin, Towards AI Inc