跳到正文
阿里雲開發者社區 AI·· 2026-10-23AI 評分56

LangChain 快速上手:從零構建天氣查詢 Agent,逐步理解每一步的設計原因

LangChain 快速上手:从零到一个会查天气的 Agent,每一步都有为什么

AI 導讀

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")

为什么不直接写在代码里?三个理由,每个都对应真实事故:

  1. 泄漏——代码进 Git,Key 就进了版本历史。哪怕后来删掉,历史里还在;
  2. 切换——测试用测试 Key、生产用生产 Key,硬编码意味着每次切换都要改代码;
  3. 协作——同事拿到的代码跑不起来,因为 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 → 发起调用 → 打印结果。

工具定义注意两件事:

  1. 类型注解 city: str 不是装饰——框架靠它生成工具的参数 Schema,模型据此填参;
  2. docstring """获取给定城市的天气。""" 也不是注释——它是给模型看的使用说明,直接决定调用准确率。

七、看懂输出:messages 里藏着 Agent 的完整决策

运行后你会拿到一个 messages 列表,四条消息,每条都有名字:

HumanMessage   content='查询北京的天气'

AIMessage      content='我来帮您查询北京的天气。'
               tool_calls=[{'name': 'get_weather',
                            'args': {'city': '北京'}}]

ToolMessage    content='北京 天气晴朗!'
               name='get_weather'

AIMessage      content='根据查询结果,北京今天的天气是晴朗的!'

这四条消息就是 Agent 循环的完整轨迹:

  1. HumanMessage:用户提问进入;
  2. AIMessage(第一次):模型决定调用工具——证据在 tool_calls 字段里,模型自己写好了工具名和参数;
  3. ToolMessage:工具执行完毕,结果回流进对话;
  4. 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 的工程结构对你来说就不再是新东西,只是换了语法。


十、小结:五步之后往哪走

五步跑通只是起点。接下来的路线按优先级排:

  1. 换真实工具——把模拟天气换成真实 API,体验 docstring 对准确率的影响;
  2. 加结构化输出——response_format 挂 Pydantic Schema,让输出可被程序消费;
  3. 加记忆——checkpointer 让对话能续上,这是对话类应用的底线能力;
  4. 接观测——LangSmith 追踪每次调用的 token、延迟、工具命中,没有观测就没有调优。

从 15 行代码到生产系统,距离不在代码量,而在这些工程决策。每一步都从一个小改动开始。


本文基于 Notion LangChain 课程 1.4 节与 LangChain v1.0 官方文档整理,代码在 Python 3.13 + langchain 1.2.0 环境下验证通过。

來源:阿里雲開發者社區 AI · developer.aliyun.com