1. LangChain 1.0 Agent开发入门指南
最近在开发一个智能客服系统时,我深入研究了LangChain 1.0的Agent机制。与旧版本相比,1.0版本带来了革命性的变化——从黑盒执行的AgentExecutor转向了基于状态机的LangGraph架构。这种转变让Agent的开发变得更加透明和可控。
1.1 新版Agent的核心变化
LangChain 1.0最大的突破在于将Agent建模为有向图结构。每个Agent现在本质上都是一个状态机,由节点(动作)和边(决策路径)组成。这种设计带来了几个关键优势:
- 执行过程可视化:可以清晰看到Agent的决策路径
- 状态持久化:支持中断和恢复执行
- 灵活定制:可以自由修改中间逻辑
在实际项目中,这种架构特别适合需要长时间运行或分步执行的复杂任务。比如我开发的客服系统就需要处理多轮对话,状态机模型完美匹配这种需求。
1.2 Agent的三大核心组件
构建一个1.0版本的Agent需要关注三个关键部分:
-
LLM(推理引擎):选择支持Tool Calling的模型,如GPT-4或本地部署的Qwen。这是Agent的"大脑",负责解析意图和决策。
-
Tools(能力集):通过
StructuredTool或@tool装饰器定义。在我的客服系统中,就包含了天气查询、订单检索、FAQ匹配等多个工具。 -
Prompt(指令集):明确Agent的角色定位和行为准则。好的提示词能显著提升Agent的表现。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 构建你的第一个Agent
2.1 基础环境搭建
首先需要准备Python环境和必要的依赖:
bash复制pip install langchain langgraph
对于本地模型部署,我推荐使用Ollama。它支持多种开源模型,部署简单:
bash复制ollama pull qwen3-next:80b-cloud
ollama serve
2.2 最小化Agent实现
下面是一个最基本的Agent实现代码:
python复制from langchain.agents import create_agent
from langchain.chat_models import init_chat_model
# 初始化聊天模型
model = init_chat_model(
model="ollama:qwen3-next:80b-cloud",
base_url="http://127.0.0.1:11434",
temperature=0.7,
timeout=30,
max_tokens=1024
)
# 创建Agent
agent = create_agent(model=model)
# 调用Agent
response = agent.invoke({
"messages": [{
"role": "user",
"content": "你好,今天北京天气如何?"
}]
})
print(response)
这个基础版本虽然功能有限,但已经包含了Agent的核心要素。执行后会看到模型返回的响应,但由于没有定义工具,它无法真正查询天气。
2.3 添加工具扩展能力
要让Agent真正有用,我们需要为其添加工具。下面是添加天气查询工具的完整示例:
python复制from typing import Annotated
from langchain.tools import tool
@tool
def get_weather(
city: Annotated[str, "要查询的城市名称"]
) -> str:
"""获取指定城市的天气信息"""
# 这里应该是调用天气API的代码
# 示例中我们返回模拟数据
return f"{city}的天气是晴朗的, 温度是25摄氏度"
# 创建带工具的Agent
agent = create_agent(
model=model,
tools=[get_weather]
)
# 现在Agent可以处理天气查询了
response = agent.invoke({
"messages": [{
"role": "user",
"content": "上海明天天气怎么样?"
}]
})
for msg in response["messages"]:
print(f"{msg['role']}: {msg['content']}")
关键点说明:
- 使用
@tool装饰器声明工具函数 - 类型注解中详细描述参数含义
- 函数文档字符串要清晰完整
- 工具注册到Agent时以列表形式传入
3. Agent执行流程深度解析
3.1 状态图执行过程
当调用Agent时,底层状态图的执行流程如下:
- 开始节点:初始化对话状态
- 模型节点:LLM分析用户意图
- 工具节点:执行具体的工具调用
- 决策节点:判断下一步动作
可以通过打印nodes属性查看图结构:
python复制print(agent.nodes)
# 输出:{'__start__': ..., 'model': ..., 'tools': ...}
3.2 消息流分析
一次完整的工具调用会产生4类消息:
- HumanMessage:用户原始输入
- AIMessage:模型决定调用工具
- ToolMessage:工具执行结果
- Final AIMessage:模型整合后的最终回复
消息结构包含丰富元数据,如:
- 唯一消息ID
- 模型使用情况(输入/输出token数)
- 执行耗时
- 模型提供商信息
3.3 流式输出实现
对于需要实时显示的场景,可以使用流式输出:
python复制# 消息级流式输出
for event in agent.stream(input=prompt, stream_mode="values"):
last_msg = event["messages"][-1]
print(f"{last_msg['role']}: {last_msg['content']}")
# Token级流式输出
for chunk in agent.stream(input=prompt, stream_mode="messages"):
print(chunk[0].content, end="", flush=True)
两种模式的区别:
values:每次返回完整消息messages:按token流式返回
4. 生产环境实践指南
4.1 工具开发最佳实践
- 功能单一化:每个工具只做一件事
- 参数验证:在工具内校验输入有效性
- 错误处理:捕获并格式化异常
- 性能监控:记录执行耗时
- 文档完整:包含示例和边界说明
改进后的天气工具示例:
python复制@tool
def get_weather(
city: Annotated[str, "城市名称,如'北京'"],
date: Annotated[str, "查询日期,格式YYYY-MM-DD"] = None
) -> str:
"""
获取城市天气信息
示例:
- get_weather(city="上海")
- get_weather(city="北京", date="2024-06-01")
返回格式:
{city} {date}的天气是{weather}, 温度{temp}℃
"""
try:
# 参数校验
if not city.strip():
raise ValueError("城市名称不能为空")
date = date or "今天"
# 这里应该是实际的API调用
return f"{city} {date}的天气是晴朗的, 温度是25℃"
except Exception as e:
return f"查询失败: {str(e)}"
4.2 提示词工程技巧
好的系统提示词应包含:
- 角色定义:明确Agent的身份
- 能力范围:列出可用工具
- 行为准则:设定回答风格
- 错误处理:指导异常情况应对
示例提示词:
python复制system_prompt = """你是一个专业的天气助手,能够查询全球城市天气信息。
可用工具:
- get_weather: 查询指定城市天气
行为准则:
1. 只回答与天气相关的问题
2. 对非天气问题礼貌拒绝
3. 温度统一使用摄氏度
4. 遇到技术错误时向用户道歉并建议重试
回答格式:
[城市] [日期]天气: [天气状况], [温度范围]
"""
4.3 性能优化策略
- 模型选择:根据场景平衡效果与成本
- 缓存机制:对相同查询缓存结果
- 超时设置:避免长时间阻塞
- 并发控制:限制并行请求数
- 日志监控:记录关键指标
优化后的模型初始化:
python复制model = init_chat_model(
model="ollama:qwen3-next:80b-cloud",
base_url="http://127.0.0.1:11434",
temperature=0.3, # 降低随机性
timeout=15, # 更短的超时
max_tokens=512, # 限制输出长度
max_retries=2 # 失败重试
)
5. 常见问题排查
5.1 工具未被调用
可能原因:
- 工具文档不完整
- 模型不支持tool calling
- 提示词未说明工具用途
解决方案:
- 检查工具函数的docstring
- 确认模型是否支持工具调用
- 在系统提示词中明确工具用途
5.2 流式输出不工作
排查步骤:
- 确认stream_mode参数正确
- 检查模型是否支持流式
- 测试网络连接是否稳定
5.3 响应速度慢
优化方向:
- 降低temperature减少随机性
- 设置合理的max_tokens
- 考虑更轻量级的模型
- 检查本地模型服务器的负载
6. 项目进阶路线
掌握了基础Agent开发后,可以进一步探索:
- 多工具协同:构建复杂工作流
- 记忆机制:实现多轮对话
- RAG集成:接入外部知识库
- 监控系统:记录和分析使用情况
- 评估体系:量化Agent性能
一个典型的电商客服Agent可能包含:
- 订单查询工具
- 退货处理工具
- 产品推荐工具
- FAQ检索工具
- 人工转接工具
通过LangGraph的可视化特性,可以清晰看到不同工具之间的调用关系和状态流转,这对调试复杂Agent非常有帮助。
