1. 引言：从 API 到对话式助手

调用天气 API 并不难，但要让用户能用自然语言询问“今天北京热不热”“上海会下雨吗”，并自动查询、返回友好回答——这就是 LangChain 大显身手的场景。本文带你用不到 50 行代码，从零搭建一个可对话的天气查询助手，无需前端、无需复杂配置，只需 Python 和一个本地 LLM。

读完你将掌握：

• 如何将任意 API 封装成 LangChain 的 tool
• 如何使用 create_agent 快速构建一个智能体
• 如何用 system_prompt 精细化控制助手行为

2. 准备工作

2.1 环境依赖

确保已安装以下 Python 包：

pip install langchain langchain-ollama requests pandas

• langchain：主体框架
• langchain-ollama：Ollama 模型集成
• requests：调用天气 API
• pandas：读取城市代码映射表

2.2 天气 API 与城市映射

天气数据来自第三方 API，需要准备以下两项：

1. 城市代码映射文件 city.csv：包含 province、city、district、areacode/城市ID 等字段，用于根据城市名查找接口所需的城市代码。
2. API 令牌：在请求头中携带 X-APISpace-Token 进行鉴权。

文中使用的 API 及 Token 仅供参考示例，实际使用时请替换为你自己的接口和密钥。

3. 核心实现

3.1 城市代码查询

首先实现一个辅助函数，根据用户输入的城市名称（如“北京”“上海浦东”）匹配到对应的城市代码。

import pandas as pd

def get_city_code(city_name: str):
    """
    根据城市名称获取城市代码
    参数：city_name: 城市名称，如北京、上海浦东等
    """
    city_df = pd.read_csv("city.csv")

    # 按区县精确匹配
    match = city_df[city_df['district'] == city_name]
    if not match.empty:
        return match.iloc[0]['areacode/城市ID']

    # 按城市名匹配
    match = city_df[city_df['city'] == city_name]
    if not match.empty:
        return match.iloc[0]['areacode/城市ID']

    # 按省份模糊匹配
    match = city_df[city_df['province'].str.contains(city_name, na=False)]
    if not match.empty:
        return match.iloc[0]['areacode/城市ID']

    # 兜底返回默认城市代码（北京）
    return 101010100

匹配优先级为：区县 > 城市 > 省份，未匹配时返回默认代码。

3.2 封装天气工具

使用 @tool 装饰器，将天气查询函数封装为 LangChain 工具，让智能体能够自动识别并调用它。

import requests
from langchain.tools import tool

@tool
def get_weather(city: str):
    """
    获取实时天气信息，返回温度及天气状况
    参数：city: 城市名称，如北京
    """
    url = "https://api.example.com/weather"
    city_code = get_city_code(city)
    payload = {"areacode": city_code}

    headers = {
        "X-APISpace-Token": "your_token_here"
    }

    response = requests.request("GET", url, params=payload, headers=headers)
    data = response.json()
    temp = data.get("result").get("realtime").get("temp")
    wd = data.get("result").get("realtime").get("text")
    return f'{city}的实时天气：{temp}°C，{wd}'

@tool 装饰器会根据函数签名和 docstring 自动生成工具描述，智能体正是通过这个描述来判断何时调用该工具。

3.3 创建并运行助手

最后，用 create_agent 把语言模型和工具组合成一个天气查询助手。

from langchain.agents import create_agent
from langchain_ollama import ChatOllama

llm = ChatOllama(model="deepseek-r1:1.5b")

tools = [get_weather]

prompt = "你是天气查询助手，请根据用户的问题调用天气工具。"
# 创建智能体
agent = create_agent(
    model=llm,
    tools=tools,
    system_prompt=prompt
)
# 调用智能体
response = agent.invoke({
    "messages": [
        {
            "role": "user",
            "content": "北京天气如何"
        }
    ]
})
print(response["messages"][-1].content)

至此，天气查询助手就搭建完成了。用户输入自然语言问题，智能体会自动判断何时调用天气工具，并将 API 返回的数据整合成自然语言回复。

4. 运行结果示例

当你运行上述代码时，会得到类似如下的输出：

北京今天的天气是 26°C，晴。很适合出门活动哦！

你也可以自由提问，比如：

response = agent.invoke({
    "messages": [
        {
            "role": "user",
            "content": "上海和深圳哪个更热？"
        }
    ]
})

助手会自动多次调用 get_weather 工具，分别查询两座城市的天气，然后对比回答。

5. 进阶优化方向

本文实现的助手虽然基础，但已经具备了智能体的核心能力。你可以从以下方向继续优化：

• 错误处理：当 API 请求失败或城市不存在时，添加友好的提示信息。
• 系统提示词优化：精细化 system_prompt，比如让助手在回复时附带穿衣建议、出行提醒等。
• 工具扩展：添加更多工具（如空气质量查询、未来天气预报），让助手能力更全面。
• 记忆与上下文：加入对话记忆组件，让助手能记住你上一轮问的城市，实现多轮对话。
• 切换模型：将 ChatOllama 替换为 ChatOpenAI 或其他兼容接口，接入更强大的模型。

6. 总结

本文完整演示了使用 LangChain 构建天气查询助手的全过程：

1. 封装外部 API 为工具（@tool）
2. 编写辅助函数处理城市代码映射
3. 用 create_agent 组合模型与工具
4. 设置系统提示词定义助手行为

整个流程不超过 50 行代码，却实现了从自然语言输入到自然语言输出的完整闭环。这个模式不仅适用于天气查询，也可以快速迁移到股票查询、新闻播报、快递跟踪等任何需要连接外部 API 的场景——关键是，你几乎不需要写任何业务逻辑的胶水代码。