最近开始学习大模型 Agent，准备采用“阅读官方文档、跑通示例、修改代码、记录问题”的方式逐步入门。本文记录我在 Windows 本地使用 LangChain 和 DeepSeek API 创建第一个工具调用 Agent 的完整过程，以及实际遇到的额度和网络代理问题。

目录

前言

一、LangChain概述

二、本次示例要完成什么

三、环境搭建

四、获取并配置 DeepSeek API Key

五、编写完整的 Agent 代码

六、运行并理解输出

七、实际遇到的问题与处理

八、跑通后可以做的三个小实验

九、本次学习总结

参考来源

---

前言

学习 LangChain 框架对于大模型应用开发非常重要。它是一个开源框架，它简化了和大型语言模型（LLM）的集成，可以帮助你快速构建复杂的 AI 应用。你可以先了解 LangChain 的核心概念，如提示词管理、链的定义和管理等，这些是构建应用的基础。接着，深入学习 LangChain 的核心组件，包括 Chat Models 和 LLMs 的区别、模型 I/O 封装、数据连接、Memory 记忆封装以及链（Chain）的使用。这些组件是 LangChain 的精髓，掌握它们将使你能够灵活地构建和优化应用。学习过程中，不用死磕底层，先跑通几个Demo（比如本地知识库问答），再慢慢深入。学到能独立用LangChain接API、处理数据、搭出可用的AI工具就够用了，细节可以边做边补。

---

一、LangChain概述

LangChain 是用于构建大模型应用的开源框架，为模型、工具等组件提供统一接口，帮助开发者组织模型调用与任务执行流程；本文从当前官方文档中的 create_agent 入口开始学习。LangChain 官方概览

对于这个入门示例，可以先理解下面的关系：

Agent = Model（模型）+ Harness（围绕模型运行的配套机制）

Model 根据问题和上下文决定下一步，Harness 提供提示词、工具和中间件，并组织模型与工具之间的交互。Agent 官方说明

LangChain 生态中几个常见名称的用途如下：

名称	主要用途
LangChain	组合模型、工具等组件来构建 Agent
LangGraph	控制流程、状态和执行过程，也是 LangChain Agent 的底层基础
Deep Agents	集成规划、文件操作、子 Agent 等常用能力
LangSmith	查看调用记录、调试和评估 Agent

这些工具的关系可参考官方概览中的说明；现阶段先掌握模型、提示词、工具和消息，再逐步学习记忆与更复杂的流程。

---

二、本次示例要完成什么

用户询问旧金山天气，Agent 选择并调用 get_weather 工具，程序执行函数，再让模型根据工具结果生成回答。

用户提问 → 模型选择工具和参数 → 程序执行工具 → 结果返回模型 → 模型组织回答。

这个流程中，模型负责提出工具调用，Python 程序负责执行函数，LangChain 负责组织循环；需要时，模型也可以继续调用工具。工具调用说明

本例中的天气工具返回固定的模拟数据，没有接入真实天气服务；学习目标是理解工具调用过程。

官方概览提供了不同模型服务商的示例；我最初尝试 OpenAI，遇到账户没有可用额度、充值条件受限等问题，最终改用 DeepSeek 完成运行。

---

三、环境搭建

1. 确认 Python 版本

以下命令都在 Windows PowerShell 中执行；本文电脑已有 Python 3.10，先检查它是否可用：

py -3.10 --version

本文实际输出为：

Python 3.10.4

LangChain 安装文档要求 Python 3.10 或以上；尚未安装 Python 时，可从 Python 官方下载页面 安装合适的版本，如果安装的是 3.11，后续创建环境的命令对应改用 py -3.11。LangChain 安装要求

2. 创建项目目录

本文使用下面的目录，读者可以替换为自己的路径：

New-Item -ItemType Directory -Force "D:\Documents\Agent学习\01-first-agent"
cd "D:\Documents\Agent学习\01-first-agent"

3. 创建虚拟环境

为本项目创建名为 langchain 的虚拟环境：

py -3.10 -m venv langchain

这条命令各部分的含义如下：

部分	含义
py -3.10	选择 Python 3.10
-m venv	运行 Python 自带的虚拟环境工具
最后的 langchain	环境所在的文件夹名称，可以自定义

虚拟环境用于隔离项目依赖；这里的文件夹名 langchain 和后面安装的 LangChain 框架包是两个概念。

本文直接使用环境里的 Python，因此不需要执行激活命令：

.\langchain\Scripts\python.exe --version

4. 安装依赖

本文跑通时的主要版本如下：

依赖	版本	用途
langchain	1.4.8	创建和运行 Agent
langchain-deepseek	1.1.1	接入 DeepSeek 模型
httpx	0.28.1	配置 HTTP 客户端和网络连接方式

为便于对照本文，安装这些版本：

.\langchain\Scripts\python.exe -m pip install "langchain==1.4.8" "langchain-deepseek==1.1.1" "httpx==0.28.1"

langchain-deepseek 是 LangChain 的 DeepSeek 集成包，安装后可以使用 ChatDeepSeek 创建模型对象。集成文档

安装完成后，检查依赖能否导入：

.\langchain\Scripts\python.exe -c "from langchain.agents import create_agent; from langchain_deepseek import ChatDeepSeek; import httpx; print('依赖导入成功')"

看到“依赖导入成功”，即可继续编写示例；后续正常运行无须重复安装。

---

四、获取并配置 DeepSeek API Key

1. 登录开放平台

打开 DeepSeek 开放平台，注册或登录账号，按页面提示完成必要设置。

2. 创建 API Key

进入 API Keys 页面，创建密钥，名称可以填写 langchain-learning，然后复制并自行保存；密钥是调用服务的凭证，不应写入公开博客或代码仓库。官方首次调用说明

3. 确认可用额度

进入余额页面，检查是否有可用额度；如需充值，可按页面提示使用支付宝或微信，金额与可用支付方式以实际页面为准。官方常见问题

创建密钥与获得调用额度是两件事，拿到 API Key 后仍需确认账户能够正常付费调用。

4. 在 PowerShell 中配置密钥

在准备运行程序的同一个 PowerShell 窗口中执行，将占位文字替换为真实密钥：

$env:DEEPSEEK_API_KEY = "替换成你的DeepSeek密钥"

这项设置只对当前终端及它启动的程序生效，关闭终端后需重新配置；代码通过 os.environ.get("DEEPSEEK_API_KEY") 读取它。

---

五、编写完整的 Agent 代码

在项目目录中新建 demo.py，以 UTF-8 编码保存下面的代码，注意文件名不要变成 demo.py.txt。

这个示例展示了如何用自定义工具创建一个简单的 LangChain 代理：

# LangChain 入门：使用 DeepSeek 和模拟天气工具创建 Agent。
import os
import httpx
from langchain.agents import create_agent
from langchain_deepseek import ChatDeepSeek


def get_weather(city: str) -> str:
    # Get simulated weather for a given city.
    print(f"[工具调用] get_weather(city={city!r})", flush=True)
    return f"It's always sunny in {city}!"


def main() -> None:
    api_key = os.environ.get("DEEPSEEK_API_KEY")
    if not api_key:
        raise SystemExit("请先在当前 PowerShell 窗口中设置 DEEPSEEK_API_KEY，再运行本程序。")

    # 国内接口直接连接，避免继承系统或环境变量中的代理。
    with httpx.Client(trust_env=False, timeout=60) as http_client:
        model = ChatDeepSeek(
            model="deepseek-flash",
            api_key=api_key,
            base_url="https://api.deepseek.com",
            http_client=http_client,
            # 入门天气示例使用非思考模式，减少等待和输出。
            extra_body={"thinking": {"type": "disabled"}},
            max_tokens=512,
            timeout=60,
            max_retries=0,
        )

        agent = create_agent(
            model=model,
            tools=[get_weather],
            system_prompt="You are a helpful assistant",
        )

        print("正在请求 DeepSeek 模型，请稍候……", flush=True)
        result = agent.invoke(
            {"messages": [{"role": "user", "content": "What's the weather in San Francisco?"}]}
        )
        print("\n[最终回答]")
        print(result["messages"][-1].content_blocks)


if __name__ == "__main__":
    main()

本次使用的模型名是 deepseek-flash，接口地址为 https://api.deepseek.com；这些配置以写作时的 DeepSeek 官方文档为准，之后复现时如遇模型变更，应查看服务商最新说明。

主要代码的作用如下：

代码部分	作用
get_weather(city: str) -> str	定义模拟天气工具，输入城市名称，返回字符串
函数中的文档字符串	描述工具用途，帮助模型理解何时使用它
ChatDeepSeek(...)	配置模型名称、密钥、接口地址与调用参数
extra_body={"thinking": {"type": "disabled"}}	使用非思考模式完成这个简单示例
max_tokens=512	限制单次模型响应的最大输出 token 数，不是整次 Agent 任务的总 token 预算
timeout=60	设置网络请求超时参数，不代表整个 Agent 必须在 60 秒内完成
max_retries=0	关闭模型客户端的自动重试，方便入门时直接观察报错
create_agent(...)	组装模型、工具和系统提示词
tools=[get_weather]	将函数交给 Agent 使用，本例无需额外添加 @tool
agent.invoke(...)	传入用户消息，启动 Agent 的执行流程
result["messages"][-1]	取本次运行返回的最后一条消息
.content_blocks	以内容块形式查看消息内容

非思考模式的配置可参考官方工具调用示例；函数传入、系统提示词和 invoke 的使用方式可参考 LangChain Agent 文档。

代码中使用 httpx.Client(trust_env=False, timeout=60)，是因为我在本机运行时遇到了代理连接问题，具体排查过程见后文；它会让该客户端忽略代理等环境配置，并没有关闭 HTTPS 证书校验。HTTPX 环境变量说明

完成后的主要目录结构为：

01-first-agent/
├── langchain/          # Python 虚拟环境
└── demo.py             # Agent 示例

---

六、运行并理解输出

1. 执行程序

确认终端位于项目目录、当前窗口已经配置密钥，然后运行：

.\langchain\Scripts\python.exe demo.py

如果重新打开了终端，完整操作为：

cd "D:\Documents\Agent学习\01-first-agent"
$env:DEEPSEEK_API_KEY = "替换成你的DeepSeek密钥"
.\langchain\Scripts\python.exe demo.py

2. 实际运行结果

我本次运行得到的输出如下，其他运行的措辞可能不同：

正在请求 DeepSeek 模型，请稍候……
[工具调用] get_weather(city='San Francisco')

[最终回答]
[{'type': 'text', 'text': 'The weather in San Francisco is sunny — perfect weather! ☀️\n\n(Though longtime locals know to still bring a light jacket for that famous fog!)'}]

这段输出表明：模型选择了 get_weather 工具，给出的参数是 San Francisco，程序实际执行函数后，模型根据返回结果生成了最终回答。

3. 为什么回答外面有列表和字典

因为打印的是 .content_blocks，其中 type: 'text' 表示文本内容块，text 字段保存具体回答，属于正常的数据结构。

本例如果只想直接查看回答内容，可以把最后一行改为：

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

4. 这次调用到底做了什么

在这个成功的执行路径中，程序先请求模型获取工具调用，再执行本地天气函数，随后带着工具结果再次请求模型，得到最终回答；因此，一个 agent.invoke(...) 可以包含多次模型 API 调用。

看到 [工具调用] 是确认函数确实执行过的关键证据，单看最终回答里出现“晴天”还不够。

5. 回答中的内容都可信吗

天气函数固定返回 It's always sunny in San Francisco!，所以“晴天”来自模拟数据；“带薄外套、防雾”则是模型自行补充的内容，工具并未提供这些信息。

这个结果提醒我：工具调用成功，只能说明流程跑通，还需要检查工具数据是否真实、回答有没有超出工具提供的依据。

---

七、实际遇到的问题与处理

1. OpenAI 返回 429：账户没有可用额度

最初运行 OpenAI 版本时，我遇到下面的错误：

Error code: 429 - You have no credits remaining.

错误内容指向账户没有可用额度；应核对密钥所属组织的 API 余额与计费设置，反复运行代码无法补足额度。OpenAI 官方错误说明

结合自己的充值条件，我改用 DeepSeek API；切换服务时，密钥、模型名称和接口地址需要配套更换。

2. DeepSeek 连接失败：WinError 10054

切换后又遇到下面的错误：

[WinError 10054] 远程主机强迫关闭了一个现有的连接。
OpenAIConnectionError: Connection error.

排查发现，本机程序继承了 127.0.0.1:7890 的代理设置；经过代理时连接被断开，直连 DeepSeek 时则能收到接口响应，所以最终使用 httpx.Client(trust_env=False) 创建客户端，并传给 ChatDeepSeek 的 http_client 参数。

HTTPX 默认读取环境中的代理配置，trust_env=False 可以忽略这些配置；这是本文机器上验证有效的处理方式，其他网络环境应根据连通性结果选择是否使用。HTTPX 官方说明

报错堆栈里出现 openai 或 langchain_openai，是因为相关集成复用了兼容客户端；本例请求的实际接口仍是代码中配置的 DeepSeek 地址。

3. 其他常见问题

现象	优先检查
提示设置 DEEPSEEK_API_KEY	是否在运行程序的同一个 PowerShell 窗口设置密钥
ModuleNotFoundError	安装依赖和执行代码是否都使用 langchain\Scripts\python.exe
DeepSeek 返回 401	密钥是否正确，是否误填成其他平台的密钥
DeepSeek 返回 402	账户可用余额是否充足
DeepSeek 返回 429	是否达到请求速率或并发限制

DeepSeek 的 401、402、429 含义见官方错误码文档；不同服务商即使返回相同状态码，具体原因也需要结合错误消息判断。

---

八、跑通后可以做的三个小实验

每次只修改一个地方、运行一次并记录结果，方便对比，也能控制模型调用次数。

1. 修改问题中的城市：将 San Francisco 改为 Beijing，观察 [工具调用] 中的城市参数是否对应变化。
2. 修改工具返回值：将固定的“晴天”改为“雨天”，观察最终回答是否使用新的工具结果。
3. 更换问题类型：改问 What is 1 + 1?，观察模型是否直接回答，以及是否仍出现天气工具调用。

这些行为由模型根据问题、提示词和工具描述决定；记录实际结果，再解释可能原因，不应把某一次输出当成所有模型都会遵守的固定规则。

---

九、本次学习总结

通过这次运行，我理解了模型选择工具、程序执行函数、结果返回模型这条基本流程，也学会了创建虚拟环境、配置 API Key，以及根据报错区分额度问题和网络问题。下一步，可以准备学习工具描述、消息结构和多轮对话记忆，并尝试把模拟天气函数替换成真实的数据查询工具。

---

参考来源

[1] 维基百科 - LangChain

[2] LangChain 官方文档：概述

[3] DeepSeek 官方文档：首次调用 API

[4] HTTPX 官方文档：环境变量与代理配置

[5] OpenAI 官方文档：错误码说明