6、Agent最佳实践

前面五章我们学习了Agent的概念和各项能力。在实际项目中，光会用API还不够——工具怎么设计、提示词怎么写、出了问题怎么排查，这些"怎么用好"的经验往往决定了Agent的实际表现。

6.1 工具设计原则

工具是Agent与外部世界的接口。工具设计得好，LLM就能准确调用；设计得不好，LLM就会选错工具、传错参数，甚至根本不知道什么时候该用它。

五条核心原则：

原则	为什么重要	正面示例	反面示例
单一职责	LLM更容易理解功能明确的工具	get_weather、get_forecast 各做一件事	handle_weather_and_forecast_and_alert 一个工具做太多事
描述清晰	LLM完全依赖描述来决定何时用、怎么用	"获取指定城市今天的实时天气，返回温度和天气状况"	"查天气"
参数具体	减少LLM猜测参数格式的可能	date: str = Field(description="日期，格式YYYY-MM-DD")	date: str（没有格式说明）
错误友好	LLM可以根据错误信息调整策略	返回 "城市名'北精'无法识别，你是否指'北京'？"	抛出 KeyError: '北精'
幂等安全	避免Agent重试时产生副作用	get_user(id=123) 调用多次结果相同	create_order() 调用多次会创建多个订单

经验法则： 如果一个工具的docstring超过3句话才能描述清楚它做什么，说明这个工具承担了太多职责，应该拆分。

6.2 提示词优化

系统提示词是你给Agent的"工作手册"。一个好的系统提示词应该告诉Agent它的角色、可用的工具、工作流程和注意事项。

# ✅ 好的系统提示词：结构清晰，指导明确
GOOD_PROMPT = """你是一个专业的数据分析助手。

你的工作流程：
1. 理解用户的分析需求
2. 使用 search 工具获取相关数据
3. 使用 calculate 工具进行计算
4. 用简洁的语言呈现分析结果

注意事项：
- 计算结果保留2位小数
- 如果数据不足以得出结论，主动告知用户
- 不要编造数据，所有数据必须来自工具查询
"""

# ❌ 差的系统提示词：太模糊，没有指导价值
BAD_PROMPT = """你是一个AI助手，帮助用户解决问题。"""

提示词优化的关键点：

要素	作用	示例
角色定位	约束Agent的回答风格和专业度	"你是一个专业的数据分析助手"
工作流程	引导Agent按合理顺序操作	"先搜索数据，再计算，最后呈现"
约束条件	避免Agent犯常见错误	"不要编造数据"
输出格式	统一回复的格式和质量	"计算结果保留2位小数"

6.3 调试技巧

Agent的执行过程是动态的、不确定的，出了问题比固定流程的Chain更难排查。以下是三个层次的调试手段：

第一层：开启日志（快速定位）

import logging
logging.basicConfig(level=logging.DEBUG)

开启后可以在控制台看到每次LLM调用的输入输出、每次工具调用的参数和结果。

第二层：使用LangSmith（可视化追踪）

import os
os.environ["LANGSMITH_TRACING"] = "true"
os.environ["LANGSMITH_API_KEY"] = "your-key"
os.environ["LANGSMITH_PROJECT"] = "my-agent-debug"

LangSmith会把Agent的每一步执行记录下来，在Web界面上以时间线的形式展示，可以清晰地看到：LLM每次推理的输入输出、选择了哪个工具、传了什么参数、工具返回了什么、共执行了多少轮循环。

第三层：流式输出排查（观察中间过程）

# 用stream替代invoke，实时观察每一步
for chunk in agent.stream(
    {"messages": [{"role": "user", "content": "你的测试问题"}]}
):
    print(chunk, end="\n\n")

调试经验： 大多数Agent问题的根源可以归为三类——工具描述不够清晰（LLM选错工具）、系统提示词引导不足（LLM执行顺序混乱）、工具返回值格式不规范（LLM无法解读结果）。遇到问题时优先从这三个方向排查。

6.4 性能优化

问题	优化方法	效果
响应慢	只加载当前任务必需的工具，避免给LLM太多选择	减少LLM决策时间
Token消耗高	使用SummarizationMiddleware压缩历史消息	降低每次调用的Token用量
工具调用次数多	优化工具设计，一次返回尽量完整的信息	减少循环轮次
吞吐量不足	使用ainvoke异步调用，支持并发处理多个请求	提高吞吐量

6.5 本章小结

好的Agent不仅仅是能跑起来，更重要的是跑得准、跑得快、出了问题能排查。核心经验是：工具描述要像"说明书"一样清晰，系统提示词要像"工作手册"一样具体，调试时善用LangSmith可视化追踪。

---

7、课程总结

7.1 本课知识回顾

本课程围绕Agent展开，按照"是什么 → 怎么造 → 怎么用好"的逻辑，逐步构建了一个具备完整能力的Agent：

章节	核心问题	学到了什么
一、Agent介绍	Agent是什么？和Chain有什么区别？	Agent = LLM + 自主决策 + 工具调用，通过循环完成动态任务
二、工具定义与使用	怎么让Agent能"做事"？	@tool定义工具，create_agent组装Agent
三、MCP工具	怎么接入别人已有的工具？	MCP统一工具接入标准，MultiServerMCPClient接入远程工具
四、记忆	怎么让Agent"记住"对话？	checkpointer + thread_id 实现多会话记忆
五、中间件	怎么控制Agent的执行过程？	消息压缩（SummarizationMiddleware）、人工审核（HumanInTheLoopMiddleware）
六、最佳实践	怎么把Agent做好？	工具设计原则、提示词优化、调试技巧
七、完整实例	所有知识怎么组合？	智能客服Agent：综合运用工具+记忆+中间件

7.2 技术栈定位

7.3 常见问题解答

Q1: Chain和Agent如何选择？

任务流程确定时用Chain（简单可靠），任务需要动态判断时用Agent（灵活但复杂度更高）。两者可以结合——Agent内部的某些子任务可以用Chain实现。

Q2: RAG和Agent可以结合吗？

可以，而且非常常见。典型做法是把RAG检索封装成一个工具，Agent在需要时自主调用它。本课第七章的query_knowledge_base工具就是一个简化版的RAG。

Q3: 如何优化Agent的响应速度？

四个方向：只加载必需的工具（减少LLM决策开销）、用SummarizationMiddleware压缩长对话（减少Token）、使用异步调用ainvoke（支持并发）、优化工具的返回值格式（减少循环轮次）。

Q4: 什么时候需要LangGraph？

当你需要多个Agent协作、需要复杂的条件分支和循环逻辑、或需要比create_agent更精细的流程控制时，就需要LangGraph。LangGraph是Agent的进阶编排工具，将在后续课程中详细讲解。

7.4 下一步建议

• 动手实践： 选择一个实际场景（如个人知识库问答、自动化数据分析），用本课学到的知识构建一个Agent
• 深入LangGraph： 学习状态图、条件边、多Agent协作，构建更复杂的工作流
• 关注AI生态： 关注社区动态可以快速扩展Agent的能力

推荐资源：

• LangChain官方文档：https://docs.langchain.com/
• LangSmith调试追踪：https://www.langchain.com/langsmith
• LangGraph文档：https://docs.langchain.com/oss/python/langgraph
• GitHub示例库：https://github.com/langchain-ai/langgraph/tree/main/examples

---