Agent Craft 智能体教程
用可运行的 Python 示例系统学习智能体全栈开发。
按维度查看评分与理由
least_privilege=1：仅说明大多数 API Key 按需配置，但未展示工具、网络、文件或 MCP 权限的最小化策略。user_confirmation=1：课程包含 Human-in-the-Loop，但没有证据表明所有产生外部影响的示例都要求确认。data_flow_transparency=1：模块表概述了 LLM、RAG、LangSmith、MCP 等数据路径，却没有逐项说明发送的数据、接收方、存储和保留方式。sensitive_data_handling=1：提供 .env 模板和占位密钥，未给出日志脱敏、密钥轮换、泄漏响应或提交防护说明。dependency_security=1：多数依赖固定版本，但部分使用下限范围，CI 没有漏洞扫描、锁文件校验或更新策略，并采用较旧的 checkout/setup-python 主版本。external_effects=1：明确涉及工具调用、公共 MCP、地图和远程 API，但未给出副作用分类、授权边界或安全默认值。rollback=0：没有撤销工具操作、恢复状态或补偿事务的说明。source_attribution=2：README 清楚链接各模块、配套博客和第三方框架，LICENSE 标明版权人；但没有更完整的第三方来源清单或已验证的维护主体信息。
self_consistency=2：README、依赖清单和 CI 基本对应 Python 3.10–3.12 与所述技术栈；扣分点是模块 13 的详细内容仍列出 Swarm/Handoff，而非其表格所述 Streamlit 内容，且 OPENAI_API_KEY 示例被描述为 DeepSeek 密钥。dependency_availability=2：提供集中依赖文件、明确安装命令和三版本 CI 安装检查；但缺少锁文件，两个依赖仅设最低版本，CI 使用 legacy resolver，可能造成环境漂移。failure_messages=0：提供材料没有展示面向用户的异常分类、诊断信息或恢复建议。
audience_and_scenarios=3：明确面向从概念学习到 API 实践的初学者，并按难度、目标和 Prompt、工具、RAG、图、多智能体、MCP、UI 等场景组织课程。capability_boundaries=2：教育用途、已开放 01–13、未完成 14–15 和可选密钥均有说明；但没有系统描述各示例不适用的生产环境、安全边界或性能边界。trigger_precision=1：章节和工具主题划分清晰，也提到人工审批，但未提供统一的 Agent 触发条件、工具选择约束或歧义处理规则。environment_fit=2：列出 Python、Node.js 版本、安装和环境变量要求；未说明操作系统差异、硬件资源、容器化配置或外部服务兼容矩阵。
information_architecture=3：15 模块总览、难度、学习目标、渐进路径和快速开始形成完整且易导航的教学结构。install_notes=2：克隆、依赖安装、editable 安装、密钥配置和首个运行命令齐全；缺少虚拟环境、常见安装故障及平台特定说明。naming_stability=2：编号目录和主题命名整体稳定；LangChain/LangGraph/RAG 的大小写不统一，模块 13 的详细内容与标题存在复制式错配。examples_and_faq=2：声称每章有独立代码和说明，并给出首个示例及大量学习建议；所给材料没有 FAQ、预期输出或故障排查示例。known_limitations=1：明确 14–15 尚未完成且其他密钥按需，但没有安全、成本、质量、规模或生产适用性限制清单。license=3：包含完整 MIT 许可证、版权声明、授权条件和免责声明。versioning_changelog=0：没有发布版本、变更日志、迁移说明或兼容性历史。maintenance_responsibility=1：提供 Issue/PR、博客和个人联系方式，并声明持续更新；但维护者身份未经验证，也没有维护周期、支持承诺或安全报告渠道。
output_usability=2：模块化、可独立运行的示例与 Streamlit 实战方向使学习产物具备普通教学用途；但材料未展示典型输出、验收标准或生产化交付物。marginal_value=2：把 LangChain、RAG、LangGraph、MCP 和 Agents SDK 串成渐进课程，相比孤立片段有明确增量价值；尚未完成综合项目和部署章节限制了端到端价值。cost_benefit=1：代码与 MIT 许可降低采用门槛，也说明仅一个 LLM 密钥为刚需；但多个远程服务、模型调用、向量依赖及本地资源的费用和性能成本没有估算。
claim_traceability=2：功能主张可追溯到具体编号模块、依赖清单、博客入口和 CI 文件；但“可运行”“一键复现”等较强主张仅有编译检查，缺少针对行为的静态测试证据。cross_source_corroboration=2：README 所述技术栈与 requirements、CI 和 MIT LICENSE 大体互相印证；CI 只做安装、编译和有限 lint，不能充分佐证功能性主张。fact_inference_separation=1：未虚构执行结果，也标注了未完成章节；但宣传性陈述、计划内容和已验证能力之间缺少清晰标记，CI 徽章容易被误读为功能测试证据。
- 该评估仅基于所给静态文件，未运行示例、测试 API 调用或验证第三方服务行为。
- 在使用工具调用、公共 MCP、LangSmith、地图或模型 API 前，应检查实际传输的数据、权限范围、日志记录和副作用，并为写操作增加明确确认。
- 不要将当前 CI 徽章视为功能正确性证明：工作流主要验证依赖安装、语法编译和有限 lint，没有行为测试。
- 应使用隔离环境并审查依赖；最低版本约束、legacy resolver 和缺少锁文件可能导致不同时间安装出不同环境。
- 将真实密钥仅保存在未提交的本地环境中，并补充泄漏检测、日志脱敏、轮换和撤销流程。
- 模块 14–15 尚未完成，模块 13 的详细说明与标题不一致；采用前应逐个核对目录内容和预期输出。
这个 Agent 能做什么，适合哪些场景？
Agent Craft 是一个面向初学者的 Python 教学仓库，按照从模型调用到完整智能体应用的路径组织内容。当前开放的 13 个模块覆盖 Prompt、LLM API、Function Calling、LangChain、RAG、LangGraph、MCP、Agents SDK、Swarm 和 Streamlit。示例涉及多轮记忆、外部函数调用、FAISS 与 Chroma 检索、Reranker、ReAct、人工审批、图工具化及多智能体编排。MCP 部分分别演示基于 FastMCP 的服务器，以及使用 langchain-mcp-adapters、Stdio 和 Streamable HTTP 的客户端连接。最终已开放模块使用 Streamlit 对接 Agents SDK，构建带异步事件流和会话持久化的智能客服界面；综合项目与部署总结仍未完成。
学习流程从 m01_agent_introduction/Agent-demo.py 的首次模型调用开始，逐步加入 Prompt、多轮上下文记忆和 Function Calling。LangChain 模块使用 LLM、Prompt、Chain、Memory、@tool、ReAct、SQL Agent、缓存与流式输出构建可调用工具的智能体。RAG 模块加载并切分文本，生成 Embedding，将向量写入 FAISS 或持久化 Chroma，再通过 LCEL RAG 链检索知识；进阶内容还加入 Reranker 和 RAG 工具化。LangGraph 模块把状态、节点和流程控制显式组织为图，结合 LangSmith 调试、持久化记忆、提示词安全注入、Human-in-the-Loop、Graph-as-a-Tool 与 Multi-Agent 编排。MCP 模块创建支持 Stdio 和 Streamable HTTP 的 FastMCP 服务器，并通过 langchain-mcp-adapters 与 AsyncExitStack 构建可流式输出的客户端。Agents SDK 与 Swarm 示例使用 Handoff 和 Context_variables 组织多智能体客服，Streamlit 模块则通过 st.chat_message、异步事件流和会话持久化提供交互界面。
- 刚开始学习智能体开发的 Python 用户，希望按顺序完成从环境配置、首次 API 调用到工具调用的练习。
- 会调用模型 API、但尚未理解 Agent 工作机制的开发者，希望通过 ReAct、状态图和 Handoff 示例观察决策与执行流程。
- 需要为私有资料构建问答原型的开发者，希望练习文本分块、Embedding、FAISS、Chroma、Reranker 和 LCEL RAG 链。
- 准备接入 MCP 的工程师，希望分别实现 FastMCP 服务端及支持 Stdio、Streamable HTTP 的客户端。
- 需要探索复杂工作流的团队，希望练习 Human-in-the-Loop、Graph-as-a-Tool 和 Multi-Agent 编排。
- 希望快速制作智能客服界面的开发者，可参考 Agents SDK、Swarm 与 Streamlit 联通示例。
这个 Agent 有哪些优点和局限？
- 课程路径从最小 LLM 调用延伸到 RAG、LangGraph、MCP、多智能体和 Streamlit，覆盖范围连续且模块化。
- 每个已开放模块可独立运行，并配有注释、说明和对应的 CSDN 原理文章，便于边实践边理解。
- RAG 同时涉及 FAISS、Chroma 和 Reranker，LangGraph 同时覆盖调试、持久化、人工审批和多智能体编排。
- MCP 同时演示 FastMCP 服务端与 langchain-mcp-adapters 客户端，并覆盖 Stdio 和 Streamable HTTP 两种通信方式。
- 15 个规划模块中目前只开放 01–13，综合实战项目和部署总结尚未完成。
- 首次运行至少需要一个 LLM API Key；部分练习还依赖 LangSmith、高德地图或 ChatGPT 凭据及相应外部服务。
- 环境同时要求 Python 3.10–3.12 和 Node.js v20+，对只想阅读单个 Python 示例的用户也构成额外环境准备成本。
- 现有资料没有提供生产部署、稳定性指标、测试覆盖情况或运行成本基准，不能据此判断生产可用性。
如何安装或部署这个 Agent？
运行环境要求 Python 3.10–3.12 和 Node.js v20+。执行：
git clone https://github.com/Annyfee/agent-craft.git
cd agent-craft
pip install -r requirements.txt
pip install -e .随后执行 cp .env.example .env，至少配置 OPENAI_API_KEY；按所运行的示例，可再配置 LANGCHAIN_API_KEY、AMAP_MAPS_API_KEY 和 CHATGPT_API_KEY。这些示例调用外部服务时需要网络连接。
如何使用这个 Agent？
完成安装和 .env 配置后，运行首个示例：
python "m01_agent_introduction/Agent-demo.py"之后可按 m01_agent_introduction 至 m13_streamlit 的目录顺序学习。每个已开放模块都有独立代码、说明和示例；涉及 LangSmith、高德地图或 ChatGPT 的内容需要相应可选密钥。模块 14“综合实战项目”和模块 15“部署上线与项目总结”尚未开放，因此当前资料没有给出完整综合项目或生产部署命令。
常见问题
必须一次配置所有 API Key 吗？
OPENAI_API_KEY 是 LLM 调用的必需项，LANGCHAIN_API_KEY、AMAP_MAPS_API_KEY 和 CHATGPT_API_KEY 可按示例需要配置。