Python 开发转 Agent 开发教程系列

面向 Python 开发者的 AI Agent 开发实战教程。使用 LangChain、LangGraph、FastAPI 等主流 Python 工具栈。

🎯 定位

从传统 Python 后端开发升级到 AI Agent 开发，掌握：

• LLM API 调用与 Prompt Engineering
• Tool Calling / Function Calling
• RAG（检索增强生成）与向量数据库
• Agent 工作流编排
• 评估、监控与生产部署

📚 教程目录

教程路线（01-07 已完成）

教程	时间	核心内容	实战项目
01. LLM API 与 Prompt 基础	1-2周	API 调用、流式输出、结构化输出、Prompt 工程	文本分类器、信息抽取工具
02. Tool Calling 工具调用	1-2周	工具定义、参数校验、安全控制、人工确认	客服 Agent、订单查询工具
03. RAG 检索增强生成	2-3周	文档解析、向量化、混合检索、引用溯源	企业知识库问答系统
04. Agent 工作流编排	2-3周	ReAct、Plan-Execute、LangGraph 状态机	工单处理 Agent
05. LangChain 深入实践	1-2周	LCEL、会话历史、Callback、自定义组件	多轮对话系统
06. 评估与可观测性	1-2周	数据集、自动评估、Trace、监控与回归门禁	Agent 评估框架
07. 生产部署与优化	1-2周	FastAPI、并发韧性、SSE、容器、Kubernetes	生产级 Agent 服务

不知道某个文件负责什么，或想直接找到测试、示例和部署入口，可查看 项目目录与文件说明。

🛠️ 技术栈

核心框架

• LangChain - Agent 开发框架
• LangGraph - 工作流编排
• FastAPI - 高性能 Web 框架
• Pydantic - 数据验证

LLM 服务

• OpenAI API - GPT-4、GPT-3.5
• Anthropic Claude API - Claude 3
• 本地模型 - Ollama

向量数据库

• Chroma - 轻量级本地向量库
• pgvector - PostgreSQL 扩展
• Qdrant - 生产级向量数据库

辅助工具

• LangSmith - 可观测性平台
• Jupyter Notebook - 交互式开发
• pytest - 测试框架

🚀 快速开始

1. 环境准备

# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# 安装依赖
pip install -r requirements.txt

2. 配置 API Key

# 创建 .env 文件
cat > .env << EOF
OPENAI_API_KEY=sk-xxx
ANTHROPIC_API_KEY=sk-ant-xxx
EOF

3. 运行第一个示例

cd examples/01-basic-chat
python simple_chat.py

📖 学习路径

第一阶段：基础（1-2周）

目标： 掌握 LLM API 调用和 Prompt 工程

• 完成教程 01：LLM API 与 Prompt 基础
• 实战：构建文本分类器
• 实战：实现结构化信息抽取
• 验收： 能稳定调用 LLM API，理解 token 成本控制

第二阶段：工具与知识（2-4周）

目标： 让 Agent 能调用真实业务能力和知识库

• 完成教程 02：Tool Calling
• 完成教程 03：RAG
• 实战：客服 Agent（工具调用 + 知识库）
• 验收： 能封装业务函数为工具，能构建向量检索系统

第三阶段：工作流（2-3周）

目标： 构建复杂的多步骤 Agent

• 完成教程 04：Agent 工作流编排
• 完成教程 05：LangChain 深入实践
• 实战：工单处理 Agent
• 验收： 能设计状态机，能处理分支和循环

第四阶段：生产化（2-3周）

目标： 部署生产级 Agent 应用

• 完成教程 06：评估与可观测性
• 完成教程 07：生产部署与优化
• 实战：完整的 Agent 服务
• 验收： 能部署、监控、评估 Agent 应用

💡 学习建议

Python 开发者的优势

• ✅ Python 是 AI/ML 生态的第一语言
• ✅ LangChain、LangGraph 等主流框架都是 Python 优先
• ✅ 快速原型开发和迭代
• ✅ 丰富的数据处理库（pandas、numpy）

常见挑战

• ⚠️ LLM 的非确定性需要适应
• ⚠️ Token 成本需要持续关注
• ⚠️ 异步编程需要熟练掌握（asyncio）
• ⚠️ 向量检索与传统数据库不同

实践建议

1. 先理解再编码 - Agent 开发需要理解 LLM 的工作原理
2. 小步迭代 - Prompt 需要反复调优
3. 关注成本 - 每次调用都在花钱，做好 token 预算
4. 保存日志 - Agent 行为需要可追溯
5. 测试驱动 - 构建测试集，持续评估质量

🎓 推荐实战项目

入门级

1. 智能文档问答 - 上传 PDF，自动回答问题
2. 邮件分类助手 - 自动分类和标记邮件
3. 代码注释生成器 - 为代码自动生成文档注释

进阶级

4. 客服 Agent - 多工具协作，查询订单、物流、知识库
5. 内容审核 Agent - 多维度审核用户内容
6. 数据分析助手 - 自动生成数据分析报告

高级项目

7. 工单自动处理 - 工作流状态机，自动分类、路由、解决
8. 代码审查 Agent - 分析代码质量，提供改进建议
9. 研究助手 - 多步骤信息收集、分析、报告生成

📊 学习检查点

Checkpoint 1：基础能力（2周后）

• 能用 Python 调用 OpenAI/Anthropic API
• 理解 temperature、top_p、max_tokens 参数
• 能设计结构化输出的 Prompt
• 能处理流式响应
• 了解 token 计费方式

Checkpoint 2：工具与知识（6周后）

• 能封装 Python 函数为 LLM 工具
• 能解析文档并切分
• 能使用向量数据库检索
• 能实现混合检索（向量 + 关键词）
• 能追溯答案来源

Checkpoint 3：工作流（9周后）

• 理解 ReAct Agent 工作原理
• 能使用 LangGraph 构建状态机
• 能实现条件分支和循环
• 能持久化 Agent 状态
• 能实现 Human-in-the-loop

Checkpoint 4：生产级（12周后）

• 能用 FastAPI 部署 Agent 服务
• 能实现异步调用和并发控制
• 能构建自动化评估体系
• 能集成监控和告警
• 能优化 token 成本

🔧 开发工具推荐

IDE 与编辑器

• VS Code + Python 插件
• PyCharm Professional
• Cursor - AI 代码编辑器

调试工具

• Jupyter Notebook - 交互式开发
• LangSmith - Agent 行为追踪
• Postman - API 测试

版本控制

• Git - 代码管理
• DVC - 数据版本控制
• MLflow - 实验追踪

📚 参考资料

官方文档

• LangChain Documentation
• LangGraph Documentation
• OpenAI API Reference
• Anthropic Claude API

学习资源

• Prompt Engineering Guide
• LangChain Cookbook
• OpenAI Cookbook

社区

• LangChain Discord
• r/LangChain

🤝 贡献

欢迎提交 Issue 和 Pull Request。开始前请阅读 贡献指南；安全问题请按 安全策略 私密报告。

📝 更新日志

• v1.6.0 (2026-07-13)
  • 完成教程 07：Agent 生产部署与优化
  • 新增 FastAPI、异步韧性、SSE、容量规划和容器部署示例
  • 七篇教程全部完成，项目进度达到 7/7
• v1.5.0 (2026-07-13)
  • 完成教程 06：Agent 评估与可观测性
  • 新增 5 个数据集、指标、裁判、Trace 与回归门禁示例
  • 新增完全离线的 10 组验证
• v1.4.0 (2026-07-10)
  • 完成教程 05：LangChain 深入实践
  • 新增 5 个 LCEL、History、Callback 与自定义组件示例
  • 新增多轮客服系统及 10 组验证
• v1.3.0 (2026-07-10)
  • 完成教程 04：Agent 工作流编排
  • 新增 5 个递进示例和离线验证脚本
  • 新增 LangGraph 分支、循环、状态持久化与人工介入
• v1.0.0 (2026-07-09)
  • 建立教程路线、基础示例和项目结构

⚖️ 许可

本项目采用 MIT License 开源。

---

开始你的 Agent 开发之旅吧！ 🚀