LangChain Agent 入门实战从报错到跑通带记忆的交互式智能体初学者保姆级教程作者风吹夏回适合人群零基础接触 LangChain Agent 的初学者全程附可运行代码 踩坑解决方案写在前面大家好我是风吹夏回。今天正式开始学习 LangChain 中的 Agent 智能体从最开始的配置报错、无输出一步步踩坑调试最终跑通了带记忆能力的交互式对话 Agent。这篇文章完全以初学者视角记录整个学习过程所有代码都经过实测可直接运行同时把我踩过的坑全部标注了出来大家跟着抄代码就能复现效果不用再走弯路。本次学习使用的技术栈大模型火山方舟豆包doubao-seed-2.0-lite框架LangChain LangGraph运行环境Python 虚拟环境 Windows 系统一、前置准备环境与依赖先把基础环境搭好建议全程用虚拟环境避免依赖冲突。1. 安装核心依赖包pipinstalllangchain langchain-openai langchain-core langgraph python-dotenv2. 配置 .env 文件在项目根目录新建.env文件填入你的模型配置# 你的火山方舟API密钥 DEEPSEEK_API_KEYark-你的密钥 # 注意必须是标准大模型接口不能用coding接口 DEEPSEEK_BASE_URLhttps://ark.cn-beijing.volces.com/api/v3⚠️ 第一个坑预警火山方舟的api/coding/v3是代码专属接口不支持工具调用Function Calling一定要用/api/v3标准路径否则Agent会没有任何输出。二、第一阶段第一个Agent的诞生最开始我直接照着教程写一运行就报错先带大家把坑踩完再跑通最简版本。踩坑1TavilySearch 密钥缺失报错最开始的代码里加了 Tavily 搜索工具运行直接报 Pydantic 校验错误ValidationError: Did not find tavily_api_key, please add an environment variable TAVILY_API_KEY原因Tavily 是第三方联网搜索工具必须单独注册申请密钥。初学者解决方案先不用第三方工具用自定义的本地工具先把 Agent 主流程跑通获得正反馈最重要。最简可运行 Agent 完整代码我们先实现一个「天气查询工具」让 Agent 自主判断什么时候调用它。fromlangchain.agentsimportcreate_agentfromlangchain_openaiimportChatOpenAIfromlangchain_core.toolsimporttoolfromdotenvimportload_dotenv,find_dotenvimportos# 加载环境变量dotenv_pathfind_dotenv()load_dotenv(dotenv_path,overrideTrue)api_keyos.getenv(DEEPSEEK_API_KEY)base_urlos.getenv(DEEPSEEK_BASE_URL)# 1. 初始化大模型llmChatOpenAI(modeldoubao-seed-2.0-lite,api_keyapi_key,base_urlbase_url,temperature0.7,)# 2. 定义自定义工具天气查询tooldefget_weather(city:str)-str:查询指定城市的实时天气情况输入为城市名称如北京、上海returnf{city}今日天气晴转多云24-31℃东南风2级# 工具列表tools[get_weather]# 3. 创建 Agentagentcreate_agent(modelllm,toolstools,system_prompt你是一个智能助手请根据用户的需求调用合适的工具来帮助他们。,)if__name____main__:print(开始测试Agent...)# 一次性调用查看完整执行链路resultagent.invoke({messages:[{role:user,content:北京今天天气怎么样}]})print(\n 完整执行链路 )formsginresult[messages]:print(f[{msg.type}]:{msg.content})ifhasattr(msg,tool_calls)andmsg.tool_calls:print(f 工具调用:{msg.tool_calls})运行后你会看到输出会清晰展示 Agent 的完整工作循环user用户提问ai模型推理决定调用get_weather工具参数为北京tool工具执行返回天气结果ai模型根据工具结果生成自然语言最终回答这就是 Agent 最核心的「感知→推理→行动→回复」循环全程没有我们手动控制流程完全是模型自主决策。三、第二阶段给Agent加上记忆跑通基础版后你会发现每次调用都是“失忆”的上一轮说过的话下一轮就忘了。这显然不符合真实使用场景接下来我们给 Agent 加上记忆能力。核心概念Checkpointer记忆存储器自动保存每一轮的对话消息Thread ID会话标识同一个ID对应同一份记忆不同ID完全隔离用来区分不同用户带记忆的 Agent 完整代码只需要在之前的代码上新增3行核心代码即可fromlangchain.agentsimportcreate_agentfromlangchain_openaiimportChatOpenAIfromlangchain_core.toolsimporttoolfromdotenvimportload_dotenv,find_dotenvimportos# 新增导入内存存储器fromlanggraph.checkpoint.memoryimportInMemorySaver dotenv_pathfind_dotenv()load_dotenv(dotenv_path,overrideTrue)api_keyos.getenv(DEEPSEEK_API_KEY)base_urlos.getenv(DEEPSEEK_BASE_URL)llmChatOpenAI(modeldoubao-seed-2.0-lite,api_keyapi_key,base_urlbase_url,temperature0.7,)tooldefget_weather(city:str)-str:查询指定城市的实时天气情况输入为城市名称如北京、上海returnf{city}今日天气晴转多云24-31℃东南风2级tools[get_weather]# 新增创建记忆存储器checkpointerInMemorySaver()agentcreate_agent(modelllm,toolstools,system_prompt你是一个智能助手请根据用户的需求调用合适的工具来帮助他们。,# 新增传入记忆存储器checkpointercheckpointer,)if__name____main__:# 同一个 thread_id 代表同一场对话config{configurable:{thread_id:user_001}}print(*50)print(第1轮对话)print(*50)result1agent.invoke({messages:[{role:user,content:你好我叫小明在北京}]},configconfig)print(AI回复,result1[messages][-1].content)print(\n*50)print(第2轮对话相同thread_id有记忆)print(*50)result2agent.invoke({messages:[{role:user,content:我叫什么名字我所在的城市今天天气怎么样}]},configconfig)print(AI回复,result2[messages][-1].content)print(\n*50)print(第3轮对话换thread_id无记忆)print(*50)result3agent.invoke({messages:[{role:user,content:我叫什么名字}]},config{configurable:{thread_id:user_002}})print(AI回复,result3[messages][-1].content)效果验证第2轮Agent能准确说出你的名字并且自动调用天气工具查询北京天气 → 记忆生效第3轮更换 Thread ID 后Agent表示不知道你的名字 → 会话完全隔离 小提示InMemorySaver是内存存储程序重启后记忆会清空适合开发调试。生产环境可以换成SqliteSaver、RedisSaver做持久化存储。四、第三阶段升级交互式对话到这里功能都跑通了但每次都要改代码输入问题太麻烦。我们把它改造成实时聊天模式像跟微信聊天一样和 Agent 对话体验感直接拉满。交互式对话完整代码输入退出、exit即可结束程序全程保留记忆还能看到 Agent 的思考和工具调用过程。fromlangchain.agentsimportcreate_agentfromlangchain_openaiimportChatOpenAIfromlangchain_core.toolsimporttoolfromdotenvimportload_dotenv,find_dotenvimportosfromlanggraph.checkpoint.memoryimportInMemorySaver# 加载环境变量dotenv_pathfind_dotenv()load_dotenv(dotenv_path,overrideTrue)api_keyos.getenv(DEEPSEEK_API_KEY)base_urlos.getenv(DEEPSEEK_BASE_URL)# 初始化大模型llmChatOpenAI(modeldoubao-seed-2.0-lite,api_keyapi_key,base_urlbase_url,temperature0.7,)# 自定义工具tooldefget_weather(city:str)-str:查询指定城市的实时天气情况输入为城市名称如北京、上海returnf{city}今日天气晴转多云24-31℃东南风2级tools[get_weather]# 记忆配置固定会话ID全程保留记忆checkpointerInMemorySaver()config{configurable:{thread_id:chat_session_001}}# 创建 Agentagentcreate_agent(modelllm,toolstools,system_prompt你是一个智能助手请根据用户的需求调用合适的工具来帮助他们。,checkpointercheckpointer,)# 交互式对话主程序if__name____main__:print(*60)print( Agent 交互式对话已启动)print( 输入问题即可对话输入 退出/exit/quit 结束)print(*60\n)whileTrue:# 获取用户输入user_inputinput( 你).strip()# 退出判断ifuser_input.lower()in[退出,exit,quit]:print(\n 对话已结束再见)break# 空输入跳过ifnotuser_input:continueprint(-*60)# 流式执行展示完整过程forstep_index,stepinenumerate(agent.stream({messages:[{role:user,content:user_input}]},configconfig),start1):# 兼容不同版本的返回结构messagesstep.get(messages,[])ifnotmessages:forkeyinstep:ifisinstance(step[key],dict)andmessagesinstep[key]:messagesstep[key][messages]breakifnotmessages:continuelast_msgmessages[-1]# 模型决定调用工具iflast_msg.typeaiandlast_msg.tool_calls:print(f [思考中] 决定调用工具)fortool_callinlast_msg.tool_calls:print(f └─ 工具{tool_call[name]}参数{tool_call[args]})# 工具执行返回结果eliflast_msg.typetool:print(f [工具执行] 返回结果{last_msg.content})# 最终回复eliflast_msg.typeaiandnotlast_msg.tool_calls:print(f\n Agent{last_msg.content})print(-*60\n)推荐体验流程大家可以按这个顺序测试完整感受记忆 工具调用的能力第一轮输入我叫小明我在长沙第二轮输入我叫什么名字第三轮输入我所在的城市今天天气怎么样第四轮输入刚才我们聊了什么五、今天踩过的坑总结作为初学者这几个坑非常容易踩特意整理出来帮大家避坑报错/问题原因解决方案TavilySearch 报 value_error 缺少密钥没有配置 Tavily 的 API Key初学者先移除第三方工具用自定义工具先跑通主流程程序正常退出但没有任何输出用了 coding 专属接口不支持工具调用把 base_url 改成标准路径/api/v3记忆不生效调用时没传 config 和 thread_id每次 invoke/stream 都必须传入带 thread_id 的 config流式输出什么都不打印返回结构和判断条件不匹配先打印原始 step 的键名再适配结构六、下一步学习规划今天把 Agent 的核心基础都跑通了接下来的学习路线消息压缩中间件解决长对话 Token 膨胀的问题人工审核中间件给高风险操作加上人类确认环节MCP 协议标准化接入第三方工具服务综合项目做一个完整的智能客服 Agent后续我会继续更新学习笔记把每一步的实战代码和踩坑记录都分享出来。最后作为初学者学习 Agent 不用一开始就堆很多功能先跑通最小 Demo理解核心的「自主决策循环」再一步步加能力是最稳妥的学习方式。如果这篇文章对你有帮助欢迎点赞收藏~ 有问题也可以在评论区交流我们一起进步