LangChain 快速上手:從零構建天氣查詢 Agent,逐步理解每一步的設計原因
LangChain 快速上手:从零到一个会查天气的 Agent,每一步都有为什么
LangChain 上手指南以 Python 3.13 和 langchain 1.2.0 示範五步流程,涵蓋環境與依賴配置、API 金鑰管理、模型封裝及天氣查詢 Agent。
2026-10-23 8
版权
版权声明:
本文内容由阿里云实名注册用户自发贡献,版权归原作者所有,阿里云开发者社区不拥有其著作权,亦不承担相应法律责任。具体规则请查看《 阿里云开发者社区用户服务协议》和 《阿里云开发者社区知识产权保护指引》。如果您发现本社区中有涉嫌抄袭的内容,填写 侵权投诉表单进行举报,一经查实,本社区将立刻删除涉嫌侵权内容。
简介: 本文以Notion课程为蓝本,拆解LangChain Agent上手五步法:环境配置、项目依赖、密钥管理、模型封装、Agent编写,并深入解析messages执行逻辑。直击新手三大坑,提供工程化改进建议,助你15分钟跑通首个Agent并真正理解其运行机制。(239字)
摘要:环境装好了代码跑不通、API Key 硬编码在脚本里、Agent 跑通了却看不懂 messages 里发生了什么——这是大多数人第一次上手 LangChain 的真实经历。本文以 Notion 课程的原生流程为骨架,把"15 分钟跑通第一个 Agent"拆成五步:环境准备、项目配置、模型封装、Agent 编写、输出解读,每一步不只给命令,更讲清楚为什么这么设计。最后给出三个新手最容易踩的坑和对应的工程化改法。
关键词:LangChain、快速上手、Agent 智能体、create_agent、环境配置、conda、DeepSeek、大模型应用开发、AI 工程化
一、跑通一个 Agent 到底要几步
先把全景图放这里。从零到第一个能跑的 Agent,一共五步:
① Python 环境(3.10+)→ ② 项目与依赖 → ③ 密钥配置(.env)
→ ④ 模型封装(my_llm.py)→ ⑤ Agent 主程序(quick_start.py)
看起来简单,但每一步都有"为什么"。跳过这些为什么,你遇到报错就只能重装;理解了它们,报错本身就是提示。

二、第一步:环境准备,版本是硬约束
LangChain 1.x 要求 Python 3.10+。这不是建议,是硬性要求——Python 3.9 已于 2025 年 10 月停止维护(EOL),v1.0 起官方明确不再支持。
用 conda 创建独立环境,与系统 Python 隔离:
# 创建名为 langchain_v1.2 的环境,指定 Python 3.13
conda create --name langchain_v1.2 python=3.13.11
# 查看已创建的环境
conda env list
# 激活环境
conda activate langchain_v1.2
为什么要独立环境:LangChain 的依赖树很深,和系统里其他项目的库版本冲突几乎是必然事件。隔离环境让"跑不通"的问题范围从整个机器缩小到一个环境。
验证激活成功:
(langchain_v1.2) > python -V
Python 3.13.11
三、第二步:创建项目与安装依赖
在 IDEA(或 PyCharm)中创建项目并指定 langchain_v1.2 环境,然后安装三个依赖:
conda activate langchain_v1.2
python -m pip install langchain==1.2.0 langchain-deepseek==1.0.1 dotenv==0.9.9 \
-i https://pypi.tuna.tsinghua.edu.cn/simple
这三个包各自的职责,装之前就要清楚:
| 包名 | 作用 | 不装会怎样 |
|---|---|---|
langchain==1.2.0 |
框架本体:create_agent、中间件 | 无法创建 Agent |
langchain-deepseek==1.0.1 |
DeepSeek 模型适配层 | 找不到 ChatDeepSeek |
dotenv==0.9.9 |
从 .env 文件加载环境变量 | 密钥只能硬编码 |
注意版本号要钉死。LangChain 迭代快,不锁版本的依赖在三个月后可能就是另一个 API。
四、第三步:密钥配置,最该养成的习惯
在项目根目录创建 .env 文件:
DEEPSEEK_API_KEY=sk-xxxx
DEEPSEEK_BASE_URL=https://api.deepseek.com
再写一个 env_utils.py 统一加载:
import os
from dotenv import load_dotenv
# override=True 确保 .env 的值优先于系统环境变量
load_dotenv(override=True)
DEEPSEEK_API_KEY = os.getenv("DEEPSEEK_API_KEY")
DEEPSEEK_BASE_URL = os.getenv("DEEPSEEK_BASE_URL")
为什么不直接写在代码里?三个理由,每个都对应真实事故:
- 泄漏——代码进 Git,Key 就进了版本历史。哪怕后来删掉,历史里还在;
- 切换——测试用测试 Key、生产用生产 Key,硬编码意味着每次切换都要改代码;
- 协作——同事拿到的代码跑不起来,因为 Key 是你的。
override=True 这个参数也有讲究:它保证 .env 里的配置优先于系统环境变量,避免"改了文件不生效"的灵异问题。
顺手把 .env 加进 .gitignore,这一步 10 秒钟,能省掉一次换 Key 的成本(Key 泄漏的标准处置是立即作废重发)。
五、第四步:封装模型,一处创建处处使用
my_llm.py——这个文件名就说明了它的定位:
from langchain_deepseek import ChatDeepSeek
from env_utils import DEEPSEEK_API_KEY, DEEPSEEK_BASE_URL
# 创建 DeepSeek LLM 实例,全项目共用
deepseek_llm = ChatDeepSeek(
api_key=DEEPSEEK_API_KEY,
api_base=DEEPSEEK_BASE_URL,
model="deepseek-chat",
)
为什么单独一个文件:模型实例的创建参数(用哪家模型、什么温度、哪个 Key)是一种配置,不该散落在各个业务文件里。集中封装后,换模型改一处,全部 Agent 生效——这正是 LangChain"统一模型接口"特点在工程上的落脚点。
六、第五步:15 行代码的第一个 Agent
quick_start.py,一个能查天气的 Agent:
from langchain.agents import create_agent
from my_llm import deepseek_llm
def get_weather(city: str) -> str:
"""获取给定城市的天气。"""
return f"{city} 天气晴朗!"
# 创建 Agent
agent = create_agent(
model=deepseek_llm,
tools=[get_weather],
system_prompt="你是一个助手,你可以查询城市的天气。",
)
# 调用 Agent
resp = agent.invoke(
{
"messages": [{
"role": "user", "content": "查询北京的天气"}]}
)
print(resp)
四行核心逻辑:定义工具 → 创建 Agent → 发起调用 → 打印结果。
工具定义注意两件事:
- 类型注解
city: str不是装饰——框架靠它生成工具的参数 Schema,模型据此填参; - docstring
"""获取给定城市的天气。"""也不是注释——它是给模型看的使用说明,直接决定调用准确率。
七、看懂输出:messages 里藏着 Agent 的完整决策
运行后你会拿到一个 messages 列表,四条消息,每条都有名字:
HumanMessage content='查询北京的天气'
AIMessage content='我来帮您查询北京的天气。'
tool_calls=[{'name': 'get_weather',
'args': {'city': '北京'}}]
ToolMessage content='北京 天气晴朗!'
name='get_weather'
AIMessage content='根据查询结果,北京今天的天气是晴朗的!'
这四条消息就是 Agent 循环的完整轨迹:
- HumanMessage:用户提问进入;
- AIMessage(第一次):模型决定调用工具——证据在
tool_calls字段里,模型自己写好了工具名和参数; - ToolMessage:工具执行完毕,结果回流进对话;
- AIMessage(第二次):模型综合工具结果,生成最终回答。

调试心法:Agent 表现不对时,别急着改提示词,先打印 messages 看 tool_calls——模型有没有调工具、参数填对了没有,答案全在那里。这一招能定位八成的"Agent 不工作"问题。
在响应的元数据里还能看到 token 用量(token_usage),做成本核算时直接取用。
八、三个新手坑与工程化改法
坑一:模拟工具跑通就上生产。return f"{city} 天气晴朗!" 是模拟实现,验证的是链路而不是业务。上生产前把函数体换成真实 HTTP 调用,工具签名(名称、参数、docstring)保持不变——Agent 侧零改动。
坑二:调试时全靠 print。
消息结构嵌套深,print 看不清。用 resp["messages"][-1].content 只取最终答案;调试时打印完整列表;上生产前接入 LangSmith 做链路追踪。
坑三:会话记忆缺失。
当前写法的 Agent 每次调用都是全新会话——问完北京再问"那上海呢",它不知道你在问天气。加上 checkpointer 就能续上:
from langgraph.checkpoint.memory import InMemorySaver
agent = create_agent(
model=deepseek_llm,
tools=[get_weather],
system_prompt="你是一个助手,你可以查询城市的天气。",
checkpointer=InMemorySaver(), # 短期记忆
)
cfg = {
"configurable": {
"thread_id": "user-001"}}
agent.invoke({
"messages": [{
"role": "user", "content": "查询北京的天气"}]}, cfg)
agent.invoke({
"messages": [{
"role": "user", "content": "那上海呢"}]}, cfg) # 能续上
同一个 thread_id 下的对话共享历史。把 InMemorySaver 换成 Redis / Postgres 实现,就是生产配置。

九、给 Java / 大数据工程师的对照
这套流程可以映射到你熟悉的概念上:
- .env + env_utils.py ≈ Spring 的
application.properties+@Value注入——配置与代码分离,两边是同一个思想; - my_llm.py ≈ 数据源配置类——连接信息集中一处,组件按需注入;
- messages 列表 ≈ Flink 的算子间事件流——每条消息是循环里的一跳,
tool_calls就是"下游算子名 + 参数"; - checkpointer ≈ 状态后端——把会话状态外置,可恢复、可水平扩展。
想通这四组对照,LangChain 的工程结构对你来说就不再是新东西,只是换了语法。
十、小结:五步之后往哪走
五步跑通只是起点。接下来的路线按优先级排:
- 换真实工具——把模拟天气换成真实 API,体验 docstring 对准确率的影响;
- 加结构化输出——
response_format挂 Pydantic Schema,让输出可被程序消费; - 加记忆——checkpointer 让对话能续上,这是对话类应用的底线能力;
- 接观测——LangSmith 追踪每次调用的 token、延迟、工具命中,没有观测就没有调优。
从 15 行代码到生产系统,距离不在代码量,而在这些工程决策。每一步都从一个小改动开始。
本文基于 Notion LangChain 课程 1.4 节与 LangChain v1.0 官方文档整理,代码在 Python 3.13 + langchain 1.2.0 环境下验证通过。
來源:阿里雲開發者社區 AI · developer.aliyun.com