最近在 CSDN 和开发者群里关于 LangChain 的提问出现了一个很有意思的分化新手问的是“从哪开始”老手问的是“现在还用不用学”。原因不难理解——网上大量教程还停留在 2023 年的写法一上来就是LLMChain、SequentialChain可翻开今天的官方文档首页主推的已经是 Chat Models、LangGraph、MCP 这些新概念。照旧教程写代码跑不通照新文档学又缺少一条清晰的入门主线。先说我的判断2026 年学 LangChain核心不是背 API而是理解它解决的三层问题——模型接入的抽象、工具能力的封装、Agent 编排的机制。这篇文章会从零起步带你完成一条完整的 LangChain 入门主线跑通第一个大模型调用掌握 Prompt 模板和结构化输出再从原理到代码实现一个真正会“自己调用工具”的 Agent 项目。读完你会得到一套能直接复制的代码也能在报错之后快速定位问题同时搞清楚 LangChain 和 LangGraph 在项目中到底怎么分工。1. LangChain 入门别急着敲代码先搞清它在 2026 年到底解决什么问题很多人对 LangChain 的印象还停留在“把多个 LLM 调用串成链”。这个印象不算错但如果你真按这个思路去查官方文档会非常困惑SequentialChain几乎从文档里消失了取而代之的是千奇百怪的新名词。这背后其实是 LangChain 一次明显的架构演进它从早期的单体框架逐步拆成了多个子包langchain-core负责核心抽象langchain-openai、langchain-anthropic负责对接不同厂商langchain-community承接社区集成。换句话说LangChain 不再强迫你用它的“链式写法”而是给你提供了一组标准接口Model、Prompt、OutputParser、Memory、Tool 和 Agent。那它到底解决了什么问题不妨想一个没有 LangChain 的开发场景。你要接入两家大模型就得写两套请求代码OpenAI 有 OpenAI 的 SDKDeepSeek 虽然是 OpenAI 兼容格式但请求和返回的细节仍要自己处理。更麻烦的是一旦需要让模型调用工具function calling你得手工构造tools参数、解析tool_calls回包、把工具结果再回填给模型。这个循环写一次两次还能接受写多了就是大量重复代码而且每换一个模型供应商几乎要把同样的逻辑再写一遍。LangChain 的意义就是把上面这些工作抽象成两层Model 层负责抹平各家 API 的差异Agent 编排层负责“决策 → 调工具 → 看结果 → 再决策”的循环。你只需要关心业务逻辑不用每次对接新模型都重新实现工具调用。这个“只学一套 API对接多家模型”的收益在今天的模型生态里尤其重要。可选模型越来越多生产项目不能绑定在某一家厂商上模型抽象层越薄、越通用迁移成本就越低。很多初学者容易把 LangChain 当成一个“重量级框架”实际上它更像一组与模型无关的开发接口。理解到这一层后面的学习才不会跑偏。2. LangChain 核心概念与底层原理2.1 Model模型所有大模型在 LangChain 眼里都是“同一个接口”LangChain 里的 Model 接口分为两种LLM纯文本补全和ChatModel对话式补全。日常开发中99% 的场景用的是ChatModel因为当前主流大模型几乎都是对话格式就连很多偏补全的模型也提供了 chat 兼容端点。ChatModel的输入输出是消息列表核心包含四种角色消息类型作用典型场景SystemMessage设定模型身份和行为规则“你是一个数据分析助手”HumanMessage用户输入用户提问AIMessage模型回复模型的回答或工具调用请求ToolMessage工具执行后的结果回填把查询结果返回给模型理解这几种消息类型是后面实现 Agent 不写错的前提。很多人在手动实现多轮对话时报错就是因为消息角色拼接不对尤其是工具调用后没有把结果正确回填。2.2 Prompt 模板把提示词变成可维护的工程资产Prompt 模板解决的是“提示词不能写死在代码里”的问题。直接用 f-string 拼接虽然简单但项目一大会很难维护尤其是多角色消息、Few-shot 示例、结构化输出要求混在一起时。ChatPromptTemplate提供了类似 f-string 的变量插值能力同时支持多角色消息模板还能和输出解析器组合使用。后面你会看到用prompt | llm | parser这种管道写法代码会非常简洁。2.3 OutputParser把模型输出变成程序能用的数据LLM 返回的是字符串但业务系统往往需要 JSON、列表或对象。OutputParser把“模型输出 → 结构化数据”的解析过程标准化。常用的有StrOutputParser直接取文本内容和PydanticOutputParser按 Pydantic 模型校验字段并转换成对象。结构化输出的重要性常被新手低估模型偶尔会返回多余的解释文字如果直接按 JSON 解析很容易失败用 Parser 配合格式指令能显著提高解析成功率。2.4 Tool工具与 Function Calling模型本身不执行代码但你可以通过 function calling 机制让模型“请求”调用某个函数。实现时需要两步先把工具的名称、描述、参数 schema 声明给模型模型在回答时返回tool_calls其中包含要调用的工具名和参数。注意真正执行函数的是你的程序模型只负责“决定调用什么、传什么参数”。这解决了 LLM 无法实时获取数据、无法执行确定性计算、无法操作外部系统的三大局限。2.5 Agent智能体模型、工具和循环的组合把模型、Prompt、工具组合起来让模型自主决定何时调用工具、如何根据工具结果继续推理这就是 Agent 的基本形态。更准确的描述是Agent 模型 工具集 循环机制。模型在循环中扮演“决策大脑”工具负责“动手”循环负责“把每一步串起来”。这个循环通常也被称为 ReActReasoning Acting即先推理、再行动、观察结果、继续推理。2.6 Chain 和 LangGraph 的关系早期 LangChain 用 Chain 串联调用写法直观但一旦遇到多分支、循环、需要人工确认的流程就会变得很别扭。LangGraph 用图结构表达状态流转更适合构建复杂 Agent。2026 年的主流判断是简单固定流程可以继续使用 LangChain 的核心抽象有状态、多分支、需要人工介入的流程则交给 LangGraph。两者不是替代关系而是配合关系——LangGraph 里的很多节点依然依赖 LangChain 的 Model、Tool、Prompt 抽象。3. 环境准备与版本选择3.1 选择 Python 与包管理工具LangChain 是 Python 生态项目建议使用 Python 3.9 以上版本我推荐 3.11 或 3.12。不要直接在系统 Python 里装一堆依赖强烈建议创建虚拟环境。现在社区里比较流行uv包安装速度比pip快不少当然直接用venv pip也完全没问题。python -m venv .venv source .venv/bin/activate # Windows 使用 .venv\Scripts\activate3.2 安装依赖包LangChain 0.3 之后官方对包做了拆分所以安装时不要只装一个langchain需要按用途安装pip install langchain0.3 langchain-core0.3 langchain-openai0.1 langgraph0.2说明一下这几个包的分工langchain-core是核心抽象Prompt、OutputParser、Tool、Messagelangchain-openai是对接 OpenAI 及 OpenAI 兼容接口的模型实现langchain是更上层的集成包langgraph是状态编排框架。如果你的项目要用向量库还要额外安装对应的社区包。由于 LangChain 迭代速度较快本文示例基于 0.3 之后的通用写法具体版本差异以官方文档为准。3.3 配置模型密钥本文示例以 OpenAI 兼容接口为例这里使用 DeepSeek 的兼容端点做演示。你需要先在对应平台申请 API Key然后配置环境变量export OPENAI_API_KEYsk-你的密钥 export OPENAI_BASE_URLhttps://api.deepseek.com/v1生产项目中密钥一定不要写死在代码里也不要把密钥提交到 Git 仓库。本地学习阶段用环境变量没问题团队项目建议使用密钥管理服务或 CI/CD 的 Secret 配置。4. 基础 Model 调用与结构化输出4.1 第一个 LangChain 模型调用环境准备好以后先用最小示例跑通模型调用。新建一个文件langchain_demo/model_basic.py# 文件路径langchain_demo/model_basic.py import os from langchain_openai import ChatOpenAI os.environ.setdefault(OPENAI_API_KEY, sk-请填入你的密钥) os.environ.setdefault(OPENAI_BASE_URL, https://api.deepseek.com/v1) llm ChatOpenAI( modeldeepseek-chat, temperature0.7, ) response llm.invoke(用一句话解释什么是 Agent 智能体) print(type(response)) print(response.content)运行方式很简单python langchain_demo/model_basic.py这段代码的关键点有两个ChatOpenAI是 langchain-openai 提供的模型封装invoke是 LangChain 中所有可运行对象的统一调用入口。注意返回结果不是字符串而是一个AIMessage对象真正的文本内容需要通过.content获取。后面你会看到这个AIMessage对象里还藏着tool_calls、usage_metadata等信息。如果你用的不是 DeepSeek而是 OpenAI、智谱、通义或者其他 OpenAI 兼容服务只需要修改model和base_url两个参数即可。这就是模型抽象层带来的第一个好处。4.2 多轮对话使用消息列表单轮调用无法满足真实对话场景。把消息以列表传入让模型理解上下文# 文件路径langchain_demo/model_messages.py from langchain_core.messages import HumanMessage, SystemMessage from langchain_openai import ChatOpenAI llm ChatOpenAI( modeldeepseek-chat, base_urlhttps://api.deepseek.com/v1, temperature0.5, ) messages [ SystemMessage(content你是一个只输出中文的技术助手回答不超过三句话。), HumanMessage(content用通俗语言解释函数调用 Function Calling。), ] resp llm.invoke(messages) print(resp.content)这里真正值得关注的是SystemMessage。很多初学者写多轮对话时习惯把所有内容都塞进用户消息里模型也能回答但系统消息的作用是稳定地设定行为边界不会被后续对话冲淡。在实际项目中系统消息建议单独抽取成配置方便调整和版本管理。4.3 Prompt 模板 输出解析器让输出变成程序能用的 JSON直接让模型“输出 JSON”通常不太可靠更稳妥的做法是让它遵循明确的格式指令再用解析器校验。先看一个把 Prompt 模板和字符串输出解析器组合的例子# 文件路径langchain_demo/prompt_chain.py from langchain_core.output_parsers import StrOutputParser from langchain_core.prompts import ChatPromptTemplate from langchain_openai import ChatOpenAI llm ChatOpenAI( modeldeepseek-chat, base_urlhttps://api.deepseek.com/v1, temperature0.3, ) prompt ChatPromptTemplate.from_messages([ (system, 你是一名资深技术架构师擅长把复杂概念讲清楚。), (human, 请用 {limit} 字以内解释 {topic}。), ]) chain prompt | llm | StrOutputParser() result chain.invoke({topic: RAG 检索增强生成, limit: 100}) print(result)注意prompt | llm | StrOutputParser这种写法它把不同组件串成一条管道输入一个字典输出直接就是字符串。这是 LangChain 0.1 之后很核心的 Runnable 组合思维几乎贯穿所有官方示例。再看一个更适合后端系统的例子用PydanticOutputParser让模型返回结构化的项目计划。# 文件路径langchain_demo/structured_output.py from typing import Literal from pydantic import BaseModel, Field from langchain_core.output_parsers import PydanticOutputParser from langchain_core.prompts import PromptTemplate from langchain_openai import ChatOpenAI class ProjectPlan(BaseModel): name: str Field(description项目名称) difficulty: Literal[easy, medium, hard] Field(description难度等级) steps: list[str] Field(description实施步骤列表) parser PydanticOutputParser(pydantic_objectProjectPlan) prompt PromptTemplate.from_template( 请为「{topic}」生成一份简短项目计划。\n{format_instructions} ).partial(format_instructionsparser.get_format_instructions()) llm ChatOpenAI( modeldeepseek-chat, base_urlhttps://api.deepseek.com/v1, temperature0.2, ) chain prompt | llm | parser plan chain.invoke({topic: 使用 LangChain 开发一个客服机器人}) print(plan) print(plan.difficulty)这里parser.get_format_instructions()会自动生成一段让模型“按照什么 JSON 结构输出”的说明所以你不必自己把输出格式写死在提示词里。解析成功后plan就是一个ProjectPlan对象可以直接用plan.name、plan.difficulty访问字段下游代码不需要再处理原始字符串。这个模式在真实项目里非常实用强烈建议掌握。5. Agent 智能体项目实战原理拆解与完整代码5.1 Agent 的核心运行机制前面说过Agent 的核心是“推理-行动”循环。展开来看一个基本的 Agent 循环包含四个步骤模型接收用户问题和系统提示词决定需要调用哪些工具。模型返回tool_calls包含工具名和参数。程序真正执行对应的工具函数拿到结果。把工具结果作为ToolMessage回填给模型模型继续推理直到不需要再调用工具、输出最终答案。这个循环看起来简单但有几个关键点容易踩坑工具调用请求中携带的tool_call_id必须原样带回否则模型无法匹配“哪个工具调用的结果”工具结果要尽量简洁清晰模型才能理解必须限制循环次数防止模型在几个工具之间“空转”。5.2 项目背景我们来构建一个“每日销售分析助手”。用户可以直接问“查一下今天的销售数据和当前时间帮我总结成一句话。”模型需要先调用时间工具拿到当前日期再调用销售数据工具查询结果最后基于数据生成回答。这个例子天然需要两次工具调用非常适合理解 Agent 的完整链路。5.3 定义工具# 文件路径langchain_demo/agent_manual.py import datetime import json from langchain_core.messages import HumanMessage, SystemMessage, ToolMessage from langchain_core.tools import tool from langchain_openai import ChatOpenAI tool def get_current_time() - str: 获取当前日期和时间格式为 YYYY-MM-DD HH:MM:SS。 return datetime.datetime.now().strftime(%Y-%m-%d %H:%M:%S) tool def get_sales_report(date: str) - str: 查询指定日期的销售数据date 格式为 YYYY-MM-DD。 # 演示环境使用模拟数据生产环境可替换为数据库或业务接口查询 if date datetime.datetime.now().strftime(%Y-%m-%d): return json.dumps( {date: date, gmv: 128000, order_count: 3200, refund_rate: 0.018} ) return json.dumps( {date: date, gmv: 86000, order_count: 2100, refund_rate: 0.022} )这里用tool装饰器把普通函数变成 LangChain 的工具对象。关于工具设计有一条容易被忽略的经验给工具写一个清晰、完整的 docstring 非常重要因为模型看不到你的源码它理解工具全靠名称、描述和参数 schema。参数尽量少复杂结构拆成多个简单参数模型传参的成功率会更高。5.4 手动实现 Agent 循环为了让原理更直观这一版先不引入 LangGraph而是手动实现循环。这是理解 Agent 内部结构最快的路径。# 文件路径langchain_demo/agent_manual.py续 tools [get_current_time, get_sales_report] tools_by_name {tool.name: tool for tool in tools} llm ChatOpenAI( modeldeepseek-chat, base_urlhttps://api.deepseek.com/v1, temperature0, ) llm_with_tools llm.bind_tools(tools) def run_agent(query: str, max_iterations: int 5) - str: messages [ SystemMessage( content( 你是一个数据分析助手。当需要实时数据时 必须调用工具获取不要凭空编造。回答要简洁、准确。 ) ), HumanMessage(contentquery), ] for _ in range(max_iterations): ai_msg llm_with_tools.invoke(messages) messages.append(ai_msg) # 模型没有再请求调用工具说明可以输出最终答案了 if not ai_msg.tool_calls: return ai_msg.content # 逐条执行模型请求的工具调用 for tool_call in ai_msg.tool_calls: tool_name tool_call[name] tool_args tool_call[args] print(f[工具调用] {tool_name}({tool_args})) tool_result tools_by_name[tool_name].invoke(tool_args) messages.append( ToolMessage( contenttool LangChain入门指南：从模型调用到Agent实战全流程解析
最近在 CSDN 和开发者群里关于 LangChain 的提问出现了一个很有意思的分化新手问的是“从哪开始”老手问的是“现在还用不用学”。原因不难理解——网上大量教程还停留在 2023 年的写法一上来就是LLMChain、SequentialChain可翻开今天的官方文档首页主推的已经是 Chat Models、LangGraph、MCP 这些新概念。照旧教程写代码跑不通照新文档学又缺少一条清晰的入门主线。先说我的判断2026 年学 LangChain核心不是背 API而是理解它解决的三层问题——模型接入的抽象、工具能力的封装、Agent 编排的机制。这篇文章会从零起步带你完成一条完整的 LangChain 入门主线跑通第一个大模型调用掌握 Prompt 模板和结构化输出再从原理到代码实现一个真正会“自己调用工具”的 Agent 项目。读完你会得到一套能直接复制的代码也能在报错之后快速定位问题同时搞清楚 LangChain 和 LangGraph 在项目中到底怎么分工。1. LangChain 入门别急着敲代码先搞清它在 2026 年到底解决什么问题很多人对 LangChain 的印象还停留在“把多个 LLM 调用串成链”。这个印象不算错但如果你真按这个思路去查官方文档会非常困惑SequentialChain几乎从文档里消失了取而代之的是千奇百怪的新名词。这背后其实是 LangChain 一次明显的架构演进它从早期的单体框架逐步拆成了多个子包langchain-core负责核心抽象langchain-openai、langchain-anthropic负责对接不同厂商langchain-community承接社区集成。换句话说LangChain 不再强迫你用它的“链式写法”而是给你提供了一组标准接口Model、Prompt、OutputParser、Memory、Tool 和 Agent。那它到底解决了什么问题不妨想一个没有 LangChain 的开发场景。你要接入两家大模型就得写两套请求代码OpenAI 有 OpenAI 的 SDKDeepSeek 虽然是 OpenAI 兼容格式但请求和返回的细节仍要自己处理。更麻烦的是一旦需要让模型调用工具function calling你得手工构造tools参数、解析tool_calls回包、把工具结果再回填给模型。这个循环写一次两次还能接受写多了就是大量重复代码而且每换一个模型供应商几乎要把同样的逻辑再写一遍。LangChain 的意义就是把上面这些工作抽象成两层Model 层负责抹平各家 API 的差异Agent 编排层负责“决策 → 调工具 → 看结果 → 再决策”的循环。你只需要关心业务逻辑不用每次对接新模型都重新实现工具调用。这个“只学一套 API对接多家模型”的收益在今天的模型生态里尤其重要。可选模型越来越多生产项目不能绑定在某一家厂商上模型抽象层越薄、越通用迁移成本就越低。很多初学者容易把 LangChain 当成一个“重量级框架”实际上它更像一组与模型无关的开发接口。理解到这一层后面的学习才不会跑偏。2. LangChain 核心概念与底层原理2.1 Model模型所有大模型在 LangChain 眼里都是“同一个接口”LangChain 里的 Model 接口分为两种LLM纯文本补全和ChatModel对话式补全。日常开发中99% 的场景用的是ChatModel因为当前主流大模型几乎都是对话格式就连很多偏补全的模型也提供了 chat 兼容端点。ChatModel的输入输出是消息列表核心包含四种角色消息类型作用典型场景SystemMessage设定模型身份和行为规则“你是一个数据分析助手”HumanMessage用户输入用户提问AIMessage模型回复模型的回答或工具调用请求ToolMessage工具执行后的结果回填把查询结果返回给模型理解这几种消息类型是后面实现 Agent 不写错的前提。很多人在手动实现多轮对话时报错就是因为消息角色拼接不对尤其是工具调用后没有把结果正确回填。2.2 Prompt 模板把提示词变成可维护的工程资产Prompt 模板解决的是“提示词不能写死在代码里”的问题。直接用 f-string 拼接虽然简单但项目一大会很难维护尤其是多角色消息、Few-shot 示例、结构化输出要求混在一起时。ChatPromptTemplate提供了类似 f-string 的变量插值能力同时支持多角色消息模板还能和输出解析器组合使用。后面你会看到用prompt | llm | parser这种管道写法代码会非常简洁。2.3 OutputParser把模型输出变成程序能用的数据LLM 返回的是字符串但业务系统往往需要 JSON、列表或对象。OutputParser把“模型输出 → 结构化数据”的解析过程标准化。常用的有StrOutputParser直接取文本内容和PydanticOutputParser按 Pydantic 模型校验字段并转换成对象。结构化输出的重要性常被新手低估模型偶尔会返回多余的解释文字如果直接按 JSON 解析很容易失败用 Parser 配合格式指令能显著提高解析成功率。2.4 Tool工具与 Function Calling模型本身不执行代码但你可以通过 function calling 机制让模型“请求”调用某个函数。实现时需要两步先把工具的名称、描述、参数 schema 声明给模型模型在回答时返回tool_calls其中包含要调用的工具名和参数。注意真正执行函数的是你的程序模型只负责“决定调用什么、传什么参数”。这解决了 LLM 无法实时获取数据、无法执行确定性计算、无法操作外部系统的三大局限。2.5 Agent智能体模型、工具和循环的组合把模型、Prompt、工具组合起来让模型自主决定何时调用工具、如何根据工具结果继续推理这就是 Agent 的基本形态。更准确的描述是Agent 模型 工具集 循环机制。模型在循环中扮演“决策大脑”工具负责“动手”循环负责“把每一步串起来”。这个循环通常也被称为 ReActReasoning Acting即先推理、再行动、观察结果、继续推理。2.6 Chain 和 LangGraph 的关系早期 LangChain 用 Chain 串联调用写法直观但一旦遇到多分支、循环、需要人工确认的流程就会变得很别扭。LangGraph 用图结构表达状态流转更适合构建复杂 Agent。2026 年的主流判断是简单固定流程可以继续使用 LangChain 的核心抽象有状态、多分支、需要人工介入的流程则交给 LangGraph。两者不是替代关系而是配合关系——LangGraph 里的很多节点依然依赖 LangChain 的 Model、Tool、Prompt 抽象。3. 环境准备与版本选择3.1 选择 Python 与包管理工具LangChain 是 Python 生态项目建议使用 Python 3.9 以上版本我推荐 3.11 或 3.12。不要直接在系统 Python 里装一堆依赖强烈建议创建虚拟环境。现在社区里比较流行uv包安装速度比pip快不少当然直接用venv pip也完全没问题。python -m venv .venv source .venv/bin/activate # Windows 使用 .venv\Scripts\activate3.2 安装依赖包LangChain 0.3 之后官方对包做了拆分所以安装时不要只装一个langchain需要按用途安装pip install langchain0.3 langchain-core0.3 langchain-openai0.1 langgraph0.2说明一下这几个包的分工langchain-core是核心抽象Prompt、OutputParser、Tool、Messagelangchain-openai是对接 OpenAI 及 OpenAI 兼容接口的模型实现langchain是更上层的集成包langgraph是状态编排框架。如果你的项目要用向量库还要额外安装对应的社区包。由于 LangChain 迭代速度较快本文示例基于 0.3 之后的通用写法具体版本差异以官方文档为准。3.3 配置模型密钥本文示例以 OpenAI 兼容接口为例这里使用 DeepSeek 的兼容端点做演示。你需要先在对应平台申请 API Key然后配置环境变量export OPENAI_API_KEYsk-你的密钥 export OPENAI_BASE_URLhttps://api.deepseek.com/v1生产项目中密钥一定不要写死在代码里也不要把密钥提交到 Git 仓库。本地学习阶段用环境变量没问题团队项目建议使用密钥管理服务或 CI/CD 的 Secret 配置。4. 基础 Model 调用与结构化输出4.1 第一个 LangChain 模型调用环境准备好以后先用最小示例跑通模型调用。新建一个文件langchain_demo/model_basic.py# 文件路径langchain_demo/model_basic.py import os from langchain_openai import ChatOpenAI os.environ.setdefault(OPENAI_API_KEY, sk-请填入你的密钥) os.environ.setdefault(OPENAI_BASE_URL, https://api.deepseek.com/v1) llm ChatOpenAI( modeldeepseek-chat, temperature0.7, ) response llm.invoke(用一句话解释什么是 Agent 智能体) print(type(response)) print(response.content)运行方式很简单python langchain_demo/model_basic.py这段代码的关键点有两个ChatOpenAI是 langchain-openai 提供的模型封装invoke是 LangChain 中所有可运行对象的统一调用入口。注意返回结果不是字符串而是一个AIMessage对象真正的文本内容需要通过.content获取。后面你会看到这个AIMessage对象里还藏着tool_calls、usage_metadata等信息。如果你用的不是 DeepSeek而是 OpenAI、智谱、通义或者其他 OpenAI 兼容服务只需要修改model和base_url两个参数即可。这就是模型抽象层带来的第一个好处。4.2 多轮对话使用消息列表单轮调用无法满足真实对话场景。把消息以列表传入让模型理解上下文# 文件路径langchain_demo/model_messages.py from langchain_core.messages import HumanMessage, SystemMessage from langchain_openai import ChatOpenAI llm ChatOpenAI( modeldeepseek-chat, base_urlhttps://api.deepseek.com/v1, temperature0.5, ) messages [ SystemMessage(content你是一个只输出中文的技术助手回答不超过三句话。), HumanMessage(content用通俗语言解释函数调用 Function Calling。), ] resp llm.invoke(messages) print(resp.content)这里真正值得关注的是SystemMessage。很多初学者写多轮对话时习惯把所有内容都塞进用户消息里模型也能回答但系统消息的作用是稳定地设定行为边界不会被后续对话冲淡。在实际项目中系统消息建议单独抽取成配置方便调整和版本管理。4.3 Prompt 模板 输出解析器让输出变成程序能用的 JSON直接让模型“输出 JSON”通常不太可靠更稳妥的做法是让它遵循明确的格式指令再用解析器校验。先看一个把 Prompt 模板和字符串输出解析器组合的例子# 文件路径langchain_demo/prompt_chain.py from langchain_core.output_parsers import StrOutputParser from langchain_core.prompts import ChatPromptTemplate from langchain_openai import ChatOpenAI llm ChatOpenAI( modeldeepseek-chat, base_urlhttps://api.deepseek.com/v1, temperature0.3, ) prompt ChatPromptTemplate.from_messages([ (system, 你是一名资深技术架构师擅长把复杂概念讲清楚。), (human, 请用 {limit} 字以内解释 {topic}。), ]) chain prompt | llm | StrOutputParser() result chain.invoke({topic: RAG 检索增强生成, limit: 100}) print(result)注意prompt | llm | StrOutputParser这种写法它把不同组件串成一条管道输入一个字典输出直接就是字符串。这是 LangChain 0.1 之后很核心的 Runnable 组合思维几乎贯穿所有官方示例。再看一个更适合后端系统的例子用PydanticOutputParser让模型返回结构化的项目计划。# 文件路径langchain_demo/structured_output.py from typing import Literal from pydantic import BaseModel, Field from langchain_core.output_parsers import PydanticOutputParser from langchain_core.prompts import PromptTemplate from langchain_openai import ChatOpenAI class ProjectPlan(BaseModel): name: str Field(description项目名称) difficulty: Literal[easy, medium, hard] Field(description难度等级) steps: list[str] Field(description实施步骤列表) parser PydanticOutputParser(pydantic_objectProjectPlan) prompt PromptTemplate.from_template( 请为「{topic}」生成一份简短项目计划。\n{format_instructions} ).partial(format_instructionsparser.get_format_instructions()) llm ChatOpenAI( modeldeepseek-chat, base_urlhttps://api.deepseek.com/v1, temperature0.2, ) chain prompt | llm | parser plan chain.invoke({topic: 使用 LangChain 开发一个客服机器人}) print(plan) print(plan.difficulty)这里parser.get_format_instructions()会自动生成一段让模型“按照什么 JSON 结构输出”的说明所以你不必自己把输出格式写死在提示词里。解析成功后plan就是一个ProjectPlan对象可以直接用plan.name、plan.difficulty访问字段下游代码不需要再处理原始字符串。这个模式在真实项目里非常实用强烈建议掌握。5. Agent 智能体项目实战原理拆解与完整代码5.1 Agent 的核心运行机制前面说过Agent 的核心是“推理-行动”循环。展开来看一个基本的 Agent 循环包含四个步骤模型接收用户问题和系统提示词决定需要调用哪些工具。模型返回tool_calls包含工具名和参数。程序真正执行对应的工具函数拿到结果。把工具结果作为ToolMessage回填给模型模型继续推理直到不需要再调用工具、输出最终答案。这个循环看起来简单但有几个关键点容易踩坑工具调用请求中携带的tool_call_id必须原样带回否则模型无法匹配“哪个工具调用的结果”工具结果要尽量简洁清晰模型才能理解必须限制循环次数防止模型在几个工具之间“空转”。5.2 项目背景我们来构建一个“每日销售分析助手”。用户可以直接问“查一下今天的销售数据和当前时间帮我总结成一句话。”模型需要先调用时间工具拿到当前日期再调用销售数据工具查询结果最后基于数据生成回答。这个例子天然需要两次工具调用非常适合理解 Agent 的完整链路。5.3 定义工具# 文件路径langchain_demo/agent_manual.py import datetime import json from langchain_core.messages import HumanMessage, SystemMessage, ToolMessage from langchain_core.tools import tool from langchain_openai import ChatOpenAI tool def get_current_time() - str: 获取当前日期和时间格式为 YYYY-MM-DD HH:MM:SS。 return datetime.datetime.now().strftime(%Y-%m-%d %H:%M:%S) tool def get_sales_report(date: str) - str: 查询指定日期的销售数据date 格式为 YYYY-MM-DD。 # 演示环境使用模拟数据生产环境可替换为数据库或业务接口查询 if date datetime.datetime.now().strftime(%Y-%m-%d): return json.dumps( {date: date, gmv: 128000, order_count: 3200, refund_rate: 0.018} ) return json.dumps( {date: date, gmv: 86000, order_count: 2100, refund_rate: 0.022} )这里用tool装饰器把普通函数变成 LangChain 的工具对象。关于工具设计有一条容易被忽略的经验给工具写一个清晰、完整的 docstring 非常重要因为模型看不到你的源码它理解工具全靠名称、描述和参数 schema。参数尽量少复杂结构拆成多个简单参数模型传参的成功率会更高。5.4 手动实现 Agent 循环为了让原理更直观这一版先不引入 LangGraph而是手动实现循环。这是理解 Agent 内部结构最快的路径。# 文件路径langchain_demo/agent_manual.py续 tools [get_current_time, get_sales_report] tools_by_name {tool.name: tool for tool in tools} llm ChatOpenAI( modeldeepseek-chat, base_urlhttps://api.deepseek.com/v1, temperature0, ) llm_with_tools llm.bind_tools(tools) def run_agent(query: str, max_iterations: int 5) - str: messages [ SystemMessage( content( 你是一个数据分析助手。当需要实时数据时 必须调用工具获取不要凭空编造。回答要简洁、准确。 ) ), HumanMessage(contentquery), ] for _ in range(max_iterations): ai_msg llm_with_tools.invoke(messages) messages.append(ai_msg) # 模型没有再请求调用工具说明可以输出最终答案了 if not ai_msg.tool_calls: return ai_msg.content # 逐条执行模型请求的工具调用 for tool_call in ai_msg.tool_calls: tool_name tool_call[name] tool_args tool_call[args] print(f[工具调用] {tool_name}({tool_args})) tool_result tools_by_name[tool_name].invoke(tool_args) messages.append( ToolMessage( contenttool