最近开始学习大模型 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组合模型、工具等组件来构建 AgentLangGraph控制流程、状态和执行过程也是 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.4LangChain 安装文档要求 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-agent3. 创建虚拟环境为本项目创建名为langchain的虚拟环境py -3.10 -m venv langchain这条命令各部分的含义如下部分含义py -3.10选择 Python 3.10-m venv运行 Python 自带的虚拟环境工具最后的langchain环境所在的文件夹名称可以自定义虚拟环境用于隔离项目依赖这里的文件夹名langchain和后面安装的 LangChain 框架包是两个概念。本文直接使用环境里的 Python因此不需要执行激活命令.\langchain\Scripts\python.exe --version4. 安装依赖本文跑通时的主要版本如下依赖版本用途langchain1.4.8创建和运行 Agentlangchain-deepseek1.1.1接入 DeepSeek 模型httpx0.28.1配置 HTTP 客户端和网络连接方式为便于对照本文安装这些版本.\langchain\Scripts\python.exe -m pip install langchain1.4.8 langchain-deepseek1.1.1 httpx0.28.1langchain-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 Key1. 登录开放平台打开 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}), flushTrue) return fIts 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_envFalse, timeout60) as http_client: model ChatDeepSeek( modeldeepseek-flash, api_keyapi_key, base_urlhttps://api.deepseek.com, http_clienthttp_client, # 入门天气示例使用非思考模式减少等待和输出。 extra_body{thinking: {type: disabled}}, max_tokens512, timeout60, max_retries0, ) agent create_agent( modelmodel, tools[get_weather], system_promptYou are a helpful assistant, ) print(正在请求 DeepSeek 模型请稍候……, flushTrue) result agent.invoke( {messages: [{role: user, content: Whats 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_tokens512限制单次模型响应的最大输出 token 数不是整次 Agent 任务的总 token 预算timeout60设置网络请求超时参数不代表整个 Agent 必须在 60 秒内完成max_retries0关闭模型客户端的自动重试方便入门时直接观察报错create_agent(...)组装模型、工具和系统提示词tools[get_weather]将函数交给 Agent 使用本例无需额外添加toolagent.invoke(...)传入用户消息启动 Agent 的执行流程result[messages][-1]取本次运行返回的最后一条消息.content_blocks以内容块形式查看消息内容非思考模式的配置可参考官方工具调用示例函数传入、系统提示词和invoke的使用方式可参考 LangChain Agent 文档。代码中使用httpx.Client(trust_envFalse, timeout60)是因为我在本机运行时遇到了代理连接问题具体排查过程见后文它会让该客户端忽略代理等环境配置并没有关闭 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.py2. 实际运行结果我本次运行得到的输出如下其他运行的措辞可能不同正在请求 DeepSeek 模型请稍候…… [工具调用] get_weather(citySan 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. 回答中的内容都可信吗天气函数固定返回Its 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_envFalse)创建客户端并传给ChatDeepSeek的http_client参数。HTTPX 默认读取环境中的代理配置trust_envFalse可以忽略这些配置这是本文机器上验证有效的处理方式其他网络环境应根据连通性结果选择是否使用。HTTPX 官方说明报错堆栈里出现openai或langchain_openai是因为相关集成复用了兼容客户端本例请求的实际接口仍是代码中配置的 DeepSeek 地址。3. 其他常见问题现象优先检查提示设置DEEPSEEK_API_KEY是否在运行程序的同一个 PowerShell 窗口设置密钥ModuleNotFoundError安装依赖和执行代码是否都使用langchain\Scripts\python.exeDeepSeek 返回 401密钥是否正确是否误填成其他平台的密钥DeepSeek 返回 402账户可用余额是否充足DeepSeek 返回 429是否达到请求速率或并发限制DeepSeek 的 401、402、429 含义见官方错误码文档不同服务商即使返回相同状态码具体原因也需要结合错误消息判断。八、跑通后可以做的三个小实验每次只修改一个地方、运行一次并记录结果方便对比也能控制模型调用次数。修改问题中的城市将San Francisco改为Beijing观察[工具调用]中的城市参数是否对应变化。修改工具返回值将固定的“晴天”改为“雨天”观察最终回答是否使用新的工具结果。更换问题类型改问What is 1 1?观察模型是否直接回答以及是否仍出现天气工具调用。这些行为由模型根据问题、提示词和工具描述决定记录实际结果再解释可能原因不应把某一次输出当成所有模型都会遵守的固定规则。九、本次学习总结通过这次运行我理解了模型选择工具、程序执行函数、结果返回模型这条基本流程也学会了创建虚拟环境、配置 API Key以及根据报错区分额度问题和网络问题。下一步可以准备学习工具描述、消息结构和多轮对话记忆并尝试把模拟天气函数替换成真实的数据查询工具。参考来源[1] 维基百科 - LangChain[2] LangChain 官方文档概述[3] DeepSeek 官方文档首次调用 API[4] HTTPX 官方文档环境变量与代理配置[5] OpenAI 官方文档错误码说明
