从一次天气查询开始，彻底搞懂 LangChain Agent 的工作闭环

李福春

发布于 2026-07-27 14:18:28

1290

文章被收录于专栏：AI技术体系搭建过程AI技术体系搭建过程

很多人第一次学 LangChain，都是从一张“全家桶”架构图开始的。

模型、提示词、工具、记忆、检索、LangGraph、LangSmith……名词看了一晚上，第二天真让他写一个 Agent，编辑器里只剩一个孤零零的光标。

这不是你理解能力差，而是学习顺序反了。

我是老李。今天不搭知识库，不接数据库，也不做花哨的网页。我们只做一个命令行天气助理：用户问“杭州今天适合跑步吗”，Agent 自己判断要不要查天气，调用本地工具拿到结果，再组织成一句靠谱的建议。

项目很小，闭环却是完整的。

只要把这个最小闭环跑通，你就能真正理解 LangChain 到底替我们做了什么，也知道下一步该往哪里加能力。

01、为什么看懂教程，还是写不出 Agent

大多数入门教程有两个极端。

一种只讲概念：Agent 是“大脑”，Tool 是“手脚”，Memory 是“记忆”。比喻很好懂，可一打开代码，你还是不知道消息从哪里进、工具为什么会被调用、最终答案又藏在哪里。

另一种一上来就做“企业级智能客服”：向量数据库、网页检索、多轮记忆、流式输出、监控平台全部装上。代码跑不起来时，你甚至无法判断问题来自模型、工具、网络，还是某个版本已经变了。

学习框架最怕的不是简单，而是变量太多。

所以这次我们主动砍掉所有非核心变量：

不调用真实天气接口，天气数据放在本地字典里；
只有一个工具，避免模型在十几个工具之间选错；
只做单轮对话，暂时不引入持久化记忆；
只用命令行，先不让前端抢走注意力。

最终留下的，正好就是 Agent 最重要的骨架：模型负责判断，工具负责取数，框架负责循环，消息负责传递状态。

02、Agent 到底是什么

普通聊天程序的路径很短：

用户问题 → 模型 → 文本答案

Agent 多了一个关键分支：

用户问题 → 模型判断
              ├─ 信息足够 → 直接回答
              └─ 信息不足 → 选择工具 → 执行工具 → 读取结果 → 再回答

这就是 Agent 的本质：模型不只生成文字，还能根据目标决定下一步动作。

在我们的项目里，用户问“杭州今天适合户外跑步吗”。模型本身不知道示例天气数据，于是生成一次工具调用，参数是“杭州”。LangChain 接住调用，执行 query_weather，把“小雨，25℃，建议携带雨具”作为工具消息交还给模型。模型再结合系统规则，给出最终建议。

请注意，真正查询天气的不是模型，真正执行 Python 函数的也不是模型。模型只负责做两次判断：

我需要调用哪个工具，参数是什么？
拿到工具结果后，我应该如何回答用户？

把这条边界想清楚，Agent 就不再神秘。

03、为什么第一个项目要选天气助理

天气助理看起来普通，却非常适合入门。

第一，问题天然需要外部信息。用户问天气，模型不能只靠训练记忆作答，因此工具调用不是为了展示语法，而是业务上的真实需要。

第二，输入输出足够直观。城市是输入，天气文本是工具结果，出行建议是最终答案。链路任何一处出错，人眼都能马上发现。

第三，它很容易扩展。今天的数据来自本地字典，明天可以换成真实天气 API；今天只有天气工具，后面可以增加空气质量、路线规划和日程查询。Agent 的主体代码几乎不用推倒重来。

这里也要纠正一个常见误区：Agent 不是工具越多越高级。

工具越多，模型需要阅读的描述越多，选择错误的概率也越高。第一版只给一个工具，反而能让我们清楚观察“工具描述如何影响模型决策”。等最小闭环稳定，再增加第二个工具，学习效率最高。

04、五个零件，拼出完整闭环

这个项目只有五个核心零件。

零件	在项目中的职责	你应该观察什么
模型	理解问题、选择工具、组织答案	为什么决定调用工具
工具	根据城市返回本地天气	名称、参数和说明是否清楚
系统提示词	规定先查天气、禁止编造	如何约束 Agent 行为
消息	承载用户问题、工具结果和最终回答	每一轮新增了什么
Agent 循环	在模型与工具之间调度	什么时候继续、什么时候结束

LangChain 1.x 的 create_agent 会把这套流程构造成一个基于 LangGraph 的执行图。你不必先学习图的全部细节，只要记住两个关键节点：model 节点负责调用模型，tools 节点负责执行工具。

一次请求大致经历四步：

用户消息进入 model；
模型返回工具调用；
tools 执行函数并追加工具消息；
新状态回到 model，模型输出最终答案后结束。

框架真正有价值的地方，正是替我们处理了这段容易出错的循环。否则你要自己解析工具参数、匹配函数、执行调用、封装结果，还要判断是否继续下一轮。

05、从零跑通第一个 LangChain Agent

准备一个 Python 3.10 以上环境，然后安装三个依赖：

python -m pip install "langchain>=1.0,<2.0" \
  "langchain-openai>=1.0,<2.0" \
  "python-dotenv>=1.0,<2.0"

接着设置模型密钥和模型名。真实密钥只放在本机环境变量或 .env，不要写进代码，更不要提交到仓库。

OPENAI_API_KEY=你的密钥
LANGCHAIN_MODEL=openai:gpt-5.4

模型名不是框架知识的重点。项目把它放进环境变量，就是为了以后可以替换成账户中可用、支持工具调用的模型，而不用修改 Agent 结构。

第一段核心代码是工具：

from langchain.tools import tool

WEATHER_DATA = {
    "北京": "晴，26℃，适合户外活动。",
    "杭州": "小雨，25℃，建议携带雨具。",
    "深圳": "雷阵雨，30℃，不建议长时间户外活动。",
}

@tool
def query_weather(city: str) -> str:
    """查询中国城市的示例天气。参数 city 必须使用中文城市名。"""
    return WEATHER_DATA.get(city, f"暂时没有“{city}”的示例天气数据。")

@tool 做了两件事：把普通函数包装成 Agent 可调用的工具，并根据函数签名生成参数结构。函数名、参数类型和文档字符串都会告诉模型“这个工具能做什么、应该怎么传参”。

然后创建 Agent：

import os
from langchain.agents import create_agent

agent = create_agent(
    model=os.getenv("LANGCHAIN_MODEL", "openai:gpt-5.4"),
    tools=[query_weather],
    system_prompt=(
        "你是一个简洁的中文出行助理。"
        "遇到天气问题必须先调用 query_weather，"
        "再结合工具结果给出具体建议；不知道的信息不要编造。"
    ),
)

最后，把用户问题包装成消息交给 Agent：

result = agent.invoke({
    "messages": [
        {"role": "user", "content": "杭州今天适合户外跑步吗？"}
    ]
})

print(result["messages"][-1].content)

在不发送真实模型请求的情况下，也可以先检查执行图。成功构建后应该看到 model 和 tools 两个核心节点。

最终消息可能是：“杭州今天有小雨，不太适合长时间户外跑步。如果一定要跑，建议缩短距离并携带轻便雨具。”

文字本身并不稀奇，重要的是它建立在工具返回的数据上，而不是模型凭空猜测。

第一次运行时，建议故意做两个小实验。先把城市改成数据里不存在的“成都”，观察 Agent 是否忠实表达“暂无数据”；再把问题改成“帮我写一句早安问候”，观察它是否跳过天气工具直接回答。前者验证模型有没有编造事实，后者验证 Agent 不是见到任何问题都机械调用工具。能通过这两个检查，才说明提示词、工具描述和执行循环真正配合起来了。