1. 从零开始构建你的第一个AI智能助手
作为一名长期从事AI应用开发的工程师,我发现很多初学者对Agent这个概念既好奇又困惑。今天我就用最直白的方式,带大家用LangChain快速搭建一个能真正"干活"的AI助手。不同于只会聊天的普通大模型,这个Agent将具备调用外部工具的真实能力。
我们先看一个实际场景:当用户询问"明天天气如何"时,传统大模型只能根据训练数据猜测回答,而Agent可以主动调用天气API获取实时数据。这种"思考+行动"的组合,正是AI应用落地的关键突破点。
2. 环境准备与工具定义
2.1 基础环境配置
在开始之前,请确保你的Python环境版本≥3.8。我推荐使用conda创建一个干净的虚拟环境:
bash复制conda create -n langchain-demo python=3.10
conda activate langchain-demo
接着安装必要的依赖库:
bash复制pip install langchain langchain-community
注意:如果你使用通义千问模型,还需要安装额外的适配器:
pip install dashscope
2.2 定义第一个工具函数
工具(Tool)是Agent能力的核心载体。下面我们定义一个最简单的天气查询工具:
python复制from langchain_core.tools import tool
@tool(description="查询指定城市的天气情况")
def get_weather(city: str) -> str:
"""实际项目中这里应该调用天气API"""
print(f"正在查询{city}的天气...") # 模拟API调用
return f"{city}今天晴天,气温25℃"
关键点解析:
@tool装饰器将普通Python函数转换为Agent可识别的工具description参数至关重要,它帮助AI理解工具的用途- 函数应包含清晰的类型注解和docstring
避坑指南:工具函数的描述(description)要具体明确。我曾遇到过因为描述模糊导致AI错误调用工具的情况。比如"查询天气"就不如"查询指定城市未来三天的天气预报"来得准确。
3. 构建你的第一个Agent
3.1 模型初始化
我们使用通义千问作为底层大模型:
python复制from langchain_community.chat_models.tongyi import ChatTongyi
model = ChatTongyi(
model="qwen3-max",
temperature=0.3 # 控制创造性,任务型应用建议0.3以下
)
参数说明:
model:指定模型版本,qwen3-max是当前较强的版本temperature:影响输出的随机性,数值越低结果越确定
3.2 Agent组装
将模型和工具组合成完整的Agent:
python复制from langchain.agents import create_agent
agent = create_agent(
model=model,
tools=[get_weather],
system_prompt="""你是一个专业的天气助手,专门回答与天气相关的问题。
当用户询问天气时,你必须调用get_weather工具获取准确信息。"""
)
系统提示词(system_prompt)的设计技巧:
- 明确角色定位
- 说明工具使用条件
- 避免过于宽泛的指令
4. Agent的完整工作流程
4.1 发起请求示例
python复制response = agent.invoke({
"messages": [
{"role": "user", "content": "上海明天天气怎么样?"}
]
})
4.2 解析响应结果
Agent的响应是一个包含多轮交互的复杂对象:
python复制for msg in response["messages"]:
if msg["role"] == "assistant":
print(msg["content"])
典型输出可能包含:
- 思考过程:"用户询问上海天气,我需要调用get_weather工具"
- 工具调用:"调用get_weather(上海)"
- 最终回答:"上海明天晴天,气温25℃"
4.3 执行流程详解
- 问题解析:模型理解用户意图
- 工具匹配:根据描述选择最合适的工具
- 参数提取:从问题中提取工具所需参数
- 执行调用:运行工具函数获取结果
- 结果整合:将工具返回数据处理成自然语言
调试技巧:在开发初期,建议打印完整的response对象。这能帮助你理解Agent的决策过程,我在排查一个参数传递问题时就是通过这种方式发现的。
5. 增强你的Agent能力
5.1 添加更多工具
一个实用的Agent应该具备多种能力:
python复制@tool(description="计算两个数的加减乘除")
def calculator(a: float, op: str, b: float) -> float:
ops = {"+": add, "-": sub, "*": mul, "/": truediv}
return ops[op](a, b)
@tool(description="查询城市人口数据")
def get_population(city: str) -> str:
# 模拟数据查询
return f"{city}人口约1000万"
agent = create_agent(
model=model,
tools=[get_weather, calculator, get_population],
system_prompt="你是多功能助手,能处理天气、计算和人口查询"
)
5.2 处理复杂查询
Agent可以处理需要多个工具协同的复杂请求:
python复制response = agent.invoke({
"messages": [
{"role": "user", "content": "上海人口是杭州的几倍?"}
]
})
在这种情况下,Agent会:
- 调用get_population获取上海人口
- 调用get_population获取杭州人口
- 调用calculator计算两者比值
5.3 错误处理机制
在实际应用中,必须考虑工具调用失败的情况:
python复制@tool(description="查询天气")
def get_weather(city: str) -> str:
try:
# 模拟API调用可能失败
if city == "不存在的城市":
raise ValueError("城市不存在")
return f"{city}天气晴朗"
except Exception as e:
return f"查询失败:{str(e)}"
6. 生产环境部署建议
6.1 性能优化技巧
- 工具缓存:对频繁调用的工具结果进行缓存
- 批量处理:合并相似请求减少API调用
- 超时设置:为每个工具设置合理的超时时间
python复制from functools import lru_cache
@lru_cache(maxsize=100)
@tool(description="查询天气")
def get_weather(city: str) -> str:
# 实现带缓存的天气查询
6.2 安全注意事项
- 输入验证:所有工具参数必须进行验证
- 权限控制:限制敏感工具的调用权限
- 日志审计:记录所有工具调用详情
python复制@tool(description="查询天气")
def get_weather(city: str) -> str:
if not isinstance(city, str) or len(city) > 50:
raise ValueError("城市名称不合法")
# 后续逻辑...
6.3 监控与维护
- 记录工具调用成功率
- 监控响应时间指标
- 设置自动告警机制
我在实际项目中使用Prometheus+Grafana搭建了完整的监控体系,这对保证Agent的稳定性至关重要。
7. 常见问题排查
7.1 工具未被调用
可能原因:
- 工具描述不够清晰
- 系统提示词限制过多
- 模型温度参数过高
解决方案:
- 检查工具描述是否准确反映功能
- 调整system_prompt给予更多自主权
- 降低temperature值至0.3以下
7.2 参数传递错误
典型表现:
- 工具收到None或错误类型的参数
- 关键参数缺失
调试方法:
- 打印完整的Agent思考过程
- 在工具函数中添加参数日志
- 使用更明确的参数名称
7.3 性能瓶颈
优化方向:
- 减少不必要的工具调用
- 实现异步并发调用
- 对耗时工具进行预处理
python复制# 异步工具示例
import asyncio
@tool(description="查询天气")
async def async_get_weather(city: str) -> str:
await asyncio.sleep(0.5) # 模拟网络请求
return f"{city}天气数据"
经过这几个月的实践,我发现构建一个可靠的Agent系统远比想象中复杂。但只要你掌握了这些核心要点,就能避开我踩过的大多数坑。记住:好的Agent不是一蹴而就的,需要持续迭代和优化。