real-world-ai-agents-workshop

这是什么？适合谁？

Designing Real-World AI Agents Workshop（MIT，Python 3.12+）是 Paul Iusztin（Towards AI / Decoding AI 联合创始人）在 AI Engineering Conference Europe 现场讲授的多 Agent 系统实战 Workshop，完整代码、2 小时视频、幻灯片全部开源。你将亲手搭出两个 MCP server：

• Deep Research Agent：user topic → deep_research × N → analyze_youtube_video → gap-fill 补查 → compile_research → research.md——用 Gemini + Google Search grounding 做事实性研究，还能原生分析 YouTube 视频内容，最终产出约 2 万 token 的带来源结构化研究简报。
• LinkedIn Writing Workflow：research.md + guideline → 生成草稿 → [review → edit] × N → post.md → generate image——评估器-优化器循环（evaluator-optimizer loop）跑 3 轮评审修改，v0 冗长草稿到 v3 紧凑成稿的全过程在 README 里有真实对照示例。

这不是又一个「调用一下 API」的 demo，而是一套生产级模式的可运行教学件，覆盖六个核心 pattern：

1. Tool-use agents——LLM 自己决定调哪个工具、何时调
2. Evaluator-optimizer loop——生成/评审/编辑循环改进
3. Grounded search——Gemini + Google Search grounding 防编造
4. Structured LLM output——Pydantic schema 类型安全响应
5. MCP server design——FastMCP 注册 tools/resources/prompts
6. LLM-as-judge evaluation——Opik 自动化质量评分

适合谁：想从「会调 API」进阶到「会设计 Agent 系统」的 AI 工程师；正在选型多 Agent 架构、想看真实权衡（单 Agent + 工具 vs 多 Agent）的技术负责人；想给团队找一套有代码、有视频、有作业的 Agent 培训教材的团队长。

不适合谁：零编程基础学习者（要求 working Python 知识 + LLM 基础概念）；想找开箱即用产品的人（这是教学仓库不是产品）；不想配 Google API Key 的人（所有 LLM 调用走 Gemini，必需）。

使用前提：Python 3.12+（uv 可代装）、uv 0.7+、GNU Make、Google API Key（aistudio.google.com/apikey 免费申请）；Opik 账号可选（评估环节用）。

准备工作

1. 环境：Python 3.12+、uv 0.7+（curl -LsSf https://astral.sh/uv/install.sh | sh）、GNU Make（Windows：choco install make）
2. 获取：git clone https://github.com/iusztinpaul/designing-real-world-ai-agents-workshop.git
3. 成本：仓库 MIT 免费；Google AI Studio 有免费额度，跑完整 workshop 的 Gemini 调用费用极低（研究+写作+配图一轮估算在免费额度量级，具体以你的账单为准）；Opik 有免费档
4. 时间：三种模式任选——看视频 2 小时 / 跑现成代码 30 分钟 / 自己从零实现 2-4 小时（25 张预梳理工单）
5. 前置知识：Python 熟练；知道 LLM、prompt、tool calling 是什么；最好用过 Claude Code 或 Cursor（MCP harness 部分）
6. 替代方案：LangChain 官方教程（框架绑定较深）、Anthropic MCP 官方示例（无完整教学叙事）、各家 agent 框架的 getting started（缺评估器循环与 LLM-as-judge 实践）

快速上手（3 步）

第一步：克隆并配置

git clone https://github.com/iusztinpaul/designing-real-world-ai-agents-workshop.git
cd designing-real-world-ai-agents-workshop
cp .env.example .env    # 填入 GOOGLE_API_KEY（+ 可选 OPIK_API_KEY）
uv sync

预期产出：依赖装完（uv 会自动处理 Python 版本）。

第二步：端到端验证

make test-end-to-end    # 跑通 research + writing 全管线

预期产出：命令无报错完成，证明 API Key、依赖、管线全部就绪。

第三个任务：在 Claude Code / Cursor 里完成第一次深度研究

仓库的 .mcp.json 已预配置——直接在 Claude Code 或 Cursor 里打开项目，两个 MCP server（deep-research / linkedin-writer）自动启动。调用 MCP prompt research_workflow，给它一个你关心的主题（例如「AI Agent 架构：什么时候该用多 Agent」），它会引导你走完整个流程；也可以用预置斜杠命令：

• /research <主题> → 产出 outputs/{topic-slug}/research.md
• /write-post → 从已有研究生成 post.md + post_image.png
• /research-and-write → 全管线一条龙

预期产出：outputs/ 下出现带来源的 research.md、经 3 轮评审修改的 post.md 和 AI 生成配图——与 README 里 Phil Tobaloo 的示例输出同构。

常见踩坑（症状 → 原因 → 解决）

1. uv sync 报 Python 版本错误。原因：本机 Python < 3.12。解决：uv python install 3.12 再重跑 uv sync——uv 会托管该版本，不污染系统 Python。
2. Gemini 调用报 429/配额不足。原因：免费档 rate limit 较紧，深度研究会并发多轮 deep_research 调用。解决：等窗口重置；或升级付费档；研究主题太大时分两步跑（先核心问题再 gap-fill）减少单轮查询数。
3. Windows 上 make 命令不存在。原因：仓库所有入口都封装在 Makefile 里。解决：choco install make，或直接读 Makefile 找到对应 uv run / python 命令手动执行；WSL 体验最顺。
4. MCP server 在 harness 里不自动启动。原因：.mcp.json 的自动加载依赖 harness 版本（Claude Code / Cursor 对项目级 MCP 配置的支持策略不同）。解决：确认 harness 是较新版本；或按「Manual server start」用 make run-research-server / make run-writing-server（stdio 传输）手动起，再在 harness 里接。
5. 评估环节跑不起来。原因：make eval-* 系列依赖 Opik 账号与 OPIK_API_KEY，且首次会自动上传数据集。解决：跳过评估不影响主线学习；要用就在 .env 补 OPIK_API_KEY，先 make upload-eval-dataset 验证连通。
6. implement_yourself/ 模式下 Agent 直接抄了答案。原因：在仓库根目录打开 harness，Agent 能看到 ../src/ 参考实现。解决：README 明确要求直接在 implement_yourself/ 文件夹里打开 harness，让工作目录被限定在骨架内——agent 看不到、grep 不到参考实现，这才是设计好的「无作弊」体验。

初级用法

• Streamlit UI 一键演示：make run-ui 起一个本地聊天界面，丢进一个主题（或上传 .md/.txt 种子文件），全程可视化看进度：搜索计数、来源收集数、评估器-优化器循环轮次、配图生成——不需要任何 harness。
• 研究种子写法：参照 README 的 seed 格式——2-3 个关键问题 + 参考链接，比一句话主题的产出质量高得多。
• 写作 guideline 写法：Topic/Angle/Target Audience/Key Points/Tone 五段式 guideline 直接决定成稿方向，README 有完整模板可抄。

高级玩法

• 1:1 复刻挑战：implement_yourself/ 是剥空的骨架 + 25 张预梳理工单 + 自定义 /implement Claude Code skill（编排 SWE Agent 和 Tester Agent 循环，一张工单一张工单推进直到目录与 src/ 一致）——用 Agent 工程的方式学 Agent 工程，2-4 小时。
• LLM-as-judge 评估管线：datasets/ 目录带预构建的 LinkedIn 帖子数据集（seeds/guidelines/research/ground truth/生成输出），make eval-dev / eval-test / eval-online 用 LLM 按结构、语气、准确性打分并上传 Opik 追踪——把「感觉输出变好了」变成可量化的回归测试。
• 批量数据集跑批：make run-dataset-writing 对全数据集跑研究+写作+配图（-no-image 版更快），适合调参后批量对比。
• 架构判断力训练：README 的示例输出本身就是一堂「何时该用多 Agent」的课——单 Agent + 工具在紧耦合任务上赢了 12-Agent 设计、「context rot」（超 10-20 个工具 LLM 选择能力退化）等结论都有真实案例支撑。
• 接自己的 harness：两个 MCP server 遵循标准 Model Context Protocol，任何 MCP 兼容 harness（不止 Claude Code/Cursor）都能编排它们——把 research → write 管道嵌进自己的工作流。

小技巧

1. 先看视频再动手（2 小时）——MCP server 设计的「为什么」比「怎么写」更值钱，视频里讲了架构决策过程。
2. examples/ 目录有完整端到端样本（seed → research → 各版草稿 → review → final post + image），跑之前先看样本，知道每步的合格产出长什么样。
3. deep_research 的 gap-fill 阶段是精髓：首轮研究后自动识别信息缺口再补查——自己写研究 Agent 时把这个两阶段模式抄走。
4. evaluator-optimizer 循环轮数 N 是可调的，3 轮之后边际收益骤减（README 的 v0→v3 对照可证），别盲目加轮数烧 token。
5. Pydantic schema 定义在 src/*/models/——读这两个目录是理解「structured LLM output」最直接的教材。

常见问题 FAQ

Q1: 这是免费课程还是导流课的广告？

A: 仓库本身（代码/视频/幻灯片/骨架）MIT 开源免费。README 中部有 Towards AI 的付费 Agentic AI Engineering Course 推广（34 课/3 项目/证书），属于明确的商业导流，但 workshop 内容完整自足、不买课也能学完全部六个 pattern。

Q2: 必须用 Gemini 吗？能换 OpenAI/Claude 吗？

A: 当前代码通过 google-genai SDK 深度绑定 Gemini——grounded search 和 YouTube 视频分析用到 Gemini 原生能力，直接换模型会丢这两个特性。想换模型需要自己改 src/*/utils/ 里的客户端封装，工作量不小。

Q3: 和 LangChain / CrewAI 官方多 Agent 教程比学哪个？

A: 定位不同：框架教程教你「用某框架干活」，本 workshop 教「不依赖重型框架的系统设计」（FastMCP + Pydantic + 原生 SDK，无 LangChain/CrewAI 依赖）——学完理解的是模式本身，可迁移到任何栈。有框架经验者反而收获更大。

Q4: 没有生产场景，学了怎么用？

A: 六个 pattern 全部直接可迁移：evaluator-optimizer 循环用在任何迭代改进型生成任务（文案/代码/报告）；LLM-as-judge 用在上线前的自动质检；MCP server 设计用在把自己团队内部工具暴露给 Agent。仓库的 implement_yourself/ 模式本身就是一套「用 Agent 学 Agent」的方法论。

Q5: workshop 时长和难度？

A: 三档：看视频约 2 小时、跑现成代码约 30 分钟、自实现 2-4 小时（25 工单）。难度定位为「有 Python + LLM 基础的中级开发者」，advanced 门槛主要在 MCP 概念与系统设计思维，不在代码量。

Q6: 项目还在更新吗？

A: 仓库最近 push 2026-06-03（本站核验 2026-09-16，约 3 个月前 ⚠️），属 workshop 材料的常态——内容完成度高（代码/视频/幻灯片/数据集/骨架全齐），主要风险是 Gemini API 演进后示例代码可能需要小修。

免责声明

本文基于公开资料整理（GitHub README 全文、仓库结构与 API 元数据，核验日期 2026-09-16），AI 辅助生成，未在本站环境实际运行该 workshop 或验证管线产出质量。课程推广链接已按中立原则处理（身份源为 GitHub 仓库，非推广 UTM 链接）；「rated 5/5 by 300+ students」等课程宣传数字未独立核实。仓库数据：GitHub API 实测 2026-09-16，★507/🔱139，MIT，创建于 2026-03-27，最近 push 2026-06-03。

参考链接

• GitHub 仓库 iusztinpaul/designing-real-world-ai-agents-workshop
• 2 小时 Workshop 完整视频（YouTube）
• Workshop 幻灯片
• 自实现骨架指南 implement_yourself/
• Model Context Protocol 官网