上一章节回顾在上个章节中完成了LangChain 1.2 环境搭建并编写了一个最简单的 Agent 天气查询 Demo。具体实现了以下内容环境准备创建并激活 Conda 环境langchain_v1.2安装了langchain1.2.0、langchain-deepseek、python-dotenv等核心依赖安全配置创建.env文件存放DEEPSEEK_API_KEY和DEEPSEEK_BASE_URL编写env_utils.py利用python-dotenv加载.env中的密钥与地址模型实例化编写my_llm.py通过ChatDeepSeek创建了一个指向 DeepSeek 官方的 LLM 实例第一个 Agent在quick_start.py中定义了一个模拟天气工具get_weather使用 LangChain 1.2 的create_agent快速构建了一个能查询天气的智能助手成功运行并观察到 Agent 自动调用工具、生成友好回复的完整消息流成果我们跑通了 LangChain 1.2 最基本的 Agent 工作流验证了模型与工具的联通性。不足所有代码堆在根目录的零散文件中配置、模型、工具、Agent 耦合在一起不利于扩展和维护。下面的内容将对这个 Demo 进行深度模块化重构构建一个结构清晰、可长期维护的项目模板。 LangChain 1.2 实战构建一个模块化的天气查询 Agent1.内容简介通过一个天气查询 Demo实现如何使用 LangChain 1.2 的create_agent新接口快速构建一个能够调用工具的智能助手。项目采用模块化设计将配置、模型、工具、Agent 分层解耦不仅易于理解更便于未来扩展和维护。目标如何搭建一个结构优雅的 Python AI 项目如何使用 LangChain 1.2 的create_agent一键创建能使用工具的 Agent如何设计可扩展的工具目录并让 Agent 自动调用为什么分层目录结构对长期项目至关重要2. 技术栈组件说明Python 3.10运行环境LangChain 1.2大模型应用开发框架langchain-openai提供 OpenAI 兼容接口用于连接 SiliconFlowpython-dotenv从.env文件加载敏感配置SiliconFlow国产大模型 API 中转平台兼容 OpenAI 接口3. 项目目录结构及其设计哲学deepseek_agent_project/ # 项目根目录一切从这里开始 ├── app/ # 核心应用包隔离业务代码 │ ├── __init__.py # 声明本目录为 Python 包 │ ├── config.py # 集中管理所有配置项 │ ├── llm.py # 负责实例化大模型 │ ├── agent.py # Agent 定义大脑 工具 │ └── tools/ # 工具包可为 Agent 增加各种能力 │ ├── __init__.py │ └── weather.py # 天气查询工具的实现 ├── .env # 敏感配置密钥、地址不提交 Git ├── .gitignore # 忽略本地文件 ├── main.py # 程序入口开箱即用 └── requirements.txt # 依赖声明一键安装为什么这样设计app/独立成包所有业务逻辑收拢在app内根目录保持清爽。未来若需部署为 Web 服务、编写测试、打包发布只需操作app包即可不会污染全局空间。config.py是唯一配置来源所有环境变量、路径定义集中在一处其余模块通过from app.config import ...获取方便切换环境开发/生产和运行时校验。llm.py只生产模型实例避免在多个地方重复初始化模型统一管理参数如temperature后续换模型仅需改这一个文件。tools/目录独立每个工具一个文件新增能力只需在此目录添加文件然后在agent.py中注册即可。工具模块与 Agent 实现彻底解耦可单独测试。.envpython-dotenv密钥与代码分离杜绝安全风险。通过pathlib绝对定位不管从哪个目录运行脚本都能正确加载配置。main.py作为演示入口简洁地展示如何调用 Agent同时证明各模块协作正常。用户可快速“看效果”。核心理念高内聚、低耦合、可扩展、可测试。4. 快速开始4.1 环境准备Python 3.10一个 SiliconFlow 账号获取 API Key可选PyCharm 或 VS Code4.2 克隆或创建项目按上述目录结构创建所有文件和文件夹或直接复制下文代码。4.3 安装依赖在项目根目录打开终端执行pipinstall-rrequirements.txt4.4 配置密钥编辑.env文件填入你的真实 API KeyDEEPSEEK_API_KEYsk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx DEEPSEEK_BASE_URLhttps://api.siliconflow.cn/v1 MODEL_NAMEdeepseek-ai/DeepSeek-V34.5 运行python main.py你会看到类似这样的输出用户: 北京今天天气怎么样 助手: 北京 天气2026-05-04 14:22:10 天气多云 温度19°C 湿度62% 风力4 级 建议注意增减衣物。5. 逐文件深度解析下面将依次展示每个文件的完整代码并解释其设计意图。5.1 项目骨架requirements.txt和.gitignorerequirements.txtlangchain1.2.0 langchain-openai python-dotenv声明了必要依赖使用1.2.0确保兼容本教程的create_agent接口。.gitignore.env __pycache__/ *.pyc .venv/保护密钥忽略临时文件。5.2 配置中心app/config.pyimportosfrompathlibimportPathfromdotenvimportload_dotenv# 定位项目根目录config.py 的上两级目录PROJECT_ROOTPath(__file__).resolve().parent.parent# 加载 .env 文件绝对路径不受执行目录影响load_dotenv(PROJECT_ROOT/.env)# 读取必要配置DEEPSEEK_API_KEYos.getenv(DEEPSEEK_API_KEY)ifnotDEEPSEEK_API_KEY:raiseValueError(⚠️ .env 中缺少 DEEPSEEK_API_KEY请检查)DEEPSEEK_BASE_URLos.getenv(DEEPSEEK_BASE_URL,https://api.siliconflow.cn/v1)MODEL_NAMEos.getenv(MODEL_NAME,deepseek-ai/DeepSeek-V3)设计解读使用Path(__file__).resolve().parent.parent确保无论从哪个目录启动程序都能找到.env。缺少关键配置时会立即抛出异常避免在深层调用时才报错。提供默认值如模型名让新用户开箱即用同时保留修改空间。5.3 模型实例化app/llm.pyfromlangchain_openaiimportChatOpenAIfromapp.configimportDEEPSEEK_API_KEY,DEEPSEEK_BASE_URL,MODEL_NAME deepseek_llmChatOpenAI(openai_api_keyDEEPSEEK_API_KEY,openai_api_baseDEEPSEEK_BASE_URL,modelMODEL_NAME,temperature0,)为什么用ChatOpenAI而不是ChatDeepSeekSiliconFlow 的 API 完全遵守 OpenAI 的接口规范使用langchain-openai的ChatOpenAI可以避免不同版本langchain-deepseek参数变动带来的兼容性问题稳定性更高。temperature0意味着模型输出确定性最强适合演示和测试。5.4 工具实现app/tools/weather.pyimportrandomfromdatetimeimportdatetimedefget_weather(city:str)-str:获取指定城市的实时天气信息模拟。 参数: city: 城市名称例如 北京。 返回: 包含天气状况、温度、湿度、风力及查询时间的字符串。 # 模拟天气类型conditions[晴天,多云,阴天,小雨,雷阵雨,雾霾,大风]temperaturerandom.randint(-5,38)humidityrandom.randint(30,90)wind_speedrandom.randint(1,10)conditionrandom.choice(conditions)nowdatetime.now().strftime(%Y-%m-%d %H:%M:%S)# 根据天气给出生活建议if雨incondition:advice记得带伞elif晴incondition:advice适合户外活动。elif霾incondition:advice请佩戴口罩。else:advice注意增减衣物。return(f{city}天气{now}\nf 天气{condition}\nf 温度{temperature}°C\nf 湿度{humidity}%\nf 风力{wind_speed}级\nf 建议{advice})LangChain 1.2 的增强体验工具函数不需要tool装饰器或复杂的BaseTool子类。只要满足以下条件有清晰的类型注解city: str有 Docstring帮助 Agent 理解函数的用途返回字符串Agent 就能自动识别并调用它这使得定义工具的门槛降到最低。模拟数据的巧思采用随机值模拟天气变化每次查询结果不同让 Demo 更生动、更像真实 API。同时返回结构化信息温度、湿度、风力、建议增强实用性。5.5 Agent 大脑app/agent.pyfromlangchain.agentsimportcreate_agentfromapp.llmimportdeepseek_llmfromapp.tools.weatherimportget_weather# 使用 LangChain 1.2 的一键创建接口agentcreate_agent(modeldeepseek_llm,tools[get_weather],system_prompt你是一个助手你可以查询城市的天气。,)这里体现了 LangChain 1.2 最大的简化旧版写法 (LangChain 0.x/1.0)新版 (LangChain 1.2)需要定义ChatPromptTemplate手动放置{agent_scratchpad}等占位符只需一个system_prompt字符串必须额外构建AgentExecutor实例create_agent直接返回可调用的 Agent 实例调用时传入{input: ...}调用格式为标准消息列表{messages: [{role: user, content: ...}]}输出通过result[output]提取输出是完整的消息列表最后一条消息的content即为助手回答新接口的调用方式respagent.invoke({messages:[{role:user,content:北京天气怎么样}]})final_answerresp[messages][-1].content这种消息列表格式与底层 LLM 的交互完全对齐更加透明和标准化。5.6 程序入口main.pyfromapp.agentimportagentif__name____main__:queries[北京今天天气怎么样,上海适合户外运动吗,]forqinqueries:print(f用户:{q})respagent.invoke({messages:[{role:user,content:q}]})final_messageresp[messages][-1]print(f助手:{final_message.content}\n)入口文件极端精简仅展示如何调用 Agent。你可以将其替换为 FastAPI 路由、命令行工具等无需改动核心逻辑。6. 技术架构与 LangChain 1.2 特性剖析6.1 整体架构┌──────────┐ │ main.py │ (表示层) └────┬─────┘ │ 调用 ┌────▼─────────────────────────────┐ │ agent.py │ (Agent 层) │ create_agent(model, tools, │ │ system_prompt) │ └────┬────────────┬────────────────┘ │ │ ┌────▼─────┐ ┌──▼──────────────┐ │ llm.py │ │ tools/weather.py│ (能力层) │模型实例化│ │ 工具函数 │ └────┬─────┘ └─────────────────┘ │ ┌────▼─────┐ │config.py │ (配置层) │ .env加载 │ └──────────┘配置层为所有层提供敏感参数。能力层llm tools是“大脑”和“手脚”由 Agent 层统一调度。Agent 层负责理解用户意图、决策使用哪个工具、组装最终回答对外暴露极简接口。表示层main.py只负责展示可轻易替换。6.2 LangChain 1.2 的create_agent带来了什么极简创建一行代码搞定 Agent无需拼接模板和执行器。工具自动识别普通函数加类型注解和文档字符串即可被 Agent 理解极大降低开发门槛。标准消息接口输入/输出均为消息列表便于集成流式处理、上下文管理等高级功能。开箱即用的容错Agent 内置了对工具调用格式错误的恢复机制可通过handle_parsing_errors调整。面向未来新版本 LangChain 的 Agent 图LangGraph与create_agent兼容后续可无缝升级到有状态的多步智能体。6.3 项目如何展示 LangChain 1.2 的功能工具调用Tool Calling用户询问天气Agent 自动识别并调用get_weather将函数返回结果组织成自然语言。角色设定System Prompt通过system_prompt定义助手的行为边界Agent 会严格遵守。模型无关性通过ChatOpenAI兼容接口轻松切换底层大模型只需改config.py中的模型名。可扩展性在tools/下新增工具文件并注册到agent.pyAgent 立即可用无需修改其他代码。7. 扩展思路不改变功能仅作提示虽然本 Demo 只包含一个天气工具但架构已经为扩展做好准备添加新工具在tools/下新建文件定义任意函数然后在agent.py的tools列表中追加即可。替换真实 API只需修改weather.py的内部实现调用和风或 OpenWeather 的 HTTP 接口其余代码完全不变。调整 Agent 行为修改system_prompt可以改变助手的语气、能力范围。部署为 Web 服务新建api.py导入agent对象用 FastAPI 封装一个 POST 接口即可上线。提示若运行时遇到任何问题请检查.env中的DEEPSEEK_API_KEY是否正确网络是否能访问api.siliconflow.cn依赖是否安装完整pip list确认langchain版本 ≥ 1.2.0