大家在聊 Agent 落地的时候常常会遇到一个尴尬局面单次调用大模型很容易但要让 Agent 自己完成“拆解任务→调用工具→观察结果→修正方案→给出结论”的完整闭环却总是差点意思。不是工具调用不稳定就是循环控制不住要么就是出了问题完全没法排查。这段时间我系统梳理了 DeepAgent 在企业级场景下的落地路径把 Harness、LangChain、LangGraph、AI 大模型这几块拼图完整串了一遍。这篇文章就把这套体系拆开揉碎从核心原理讲到可运行的完整代码再给出高频问题和工程建议。无论你是准备入门 Agent 开发还是已经在做企业级 AI 应用都可以照着试一遍。1. DeepAgent 到底是什么为什么企业需要它1.1 从“聊天机器人”到“任务执行体”过去我们使用大模型最常见的形态是 ChatBot用户提问模型回答。这种模式适合知识问答、文案生成、代码解释等场景但它有明显的边界——模型只能“说”不能“做”。而在企业场景中我们真正需要的往往是一个能“做事情”的智能体帮用户查订单、改配置、生成报表、处理工单、调用内部 API 完成一系列操作。这种具备目标理解、任务拆解、工具调用、结果验证能力的系统就是 Agent。DeepAgent 可以理解为“深度智能体”它强调几个核心能力规划能力把复杂目标拆成多个可执行的子任务。工具调用通过 Function Calling 或 MCP 协议调用外部系统。记忆管理区分短期记忆对话上下文和长期记忆业务数据、历史偏好。自我修正执行失败时读取报错信息自动调整方案并重试。可控性每一步都可以被记录、被审计、被干预。如果一个 Agent 只做了“模型 Prompt”那它还不是合格的 DeepAgent。真正企业级的 Agent必须把上面这些能力工程化、产品化。1.2 DeepAgent 框架的核心组成部分一个典型的企业级 DeepAgent 框架从逻辑上可以拆成五层层次职责典型实现模型层提供推理能力GPT、Claude、DeepSeek、Qwen 等大模型编排层控制 Agent 的执行流程LangGraph、Harness、自研状态机工具层让 Agent 能与外部世界交互内部 API、数据库查询、RPA、MCP Server记忆层存储短期与长期状态Redis、向量数据库、关系型数据库可观测层记录日志、追踪链路、评估效果LangSmith、Prometheus、自研日志平台在这五层中编排层是 DeepAgent 的灵魂。它决定了 Agent 是“看起来聪明”还是“真的可靠”。这也是为什么 LangChain、LangGraph、Harness 工程量概念最近被反复讨论的原因。1.3 Harness 在 DeepAgent 中的角色Harness 这个词直译是“安全带、控制装置”。在 Agent 工程中Harness 指的是承载 Agent 运行的控制框架或执行环境。它的核心职责是决定模型如何被调用系统提示词、工具定义如何注入。控制 Agent 的循环最大步数、终止条件、异常处理。管理工具执行的安全边界哪些工具能调、哪些不能调。提供执行沙箱在隔离环境里跑模型生成的代码避免破坏宿主系统。输出结构化日志方便追踪每一步决策。社区里常提到的 Codex Harness、DeepSeek Harness 等工具本质就是把“模型推理、代码执行、安全隔离、结果反馈”封装成一个可控的闭环让 Agent 可以反复尝试运行代码直到得到正确结果。Harness 工程也因此成为 Agent 从 Demo 走向生产的关键技术点。理解了 Harness 在框架中的定位我们再来看现在最常被提到的 LangChain 和 LangGraph。2. 环境准备与版本说明在进入代码之前先把环境准备好。本文示例以 Python 3.10 为主会用到 LangChain、LangGraph 以及大模型的 OpenAI 兼容接口。2.1 环境要求操作系统Windows / macOS / Linux 均可。Python3.10 及以上建议 3.11。包管理工具pip 或 poetry。大模型 API可以是 OpenAI 兼容接口也可以是本地部署的 Ollama / vLLM 服务。需要说明的是LangChain 和 LangGraph 的版本迭代速度比较快不同版本的 API 有过调整。本文代码基于以下版本区间编写实际操作时请结合你的项目情况微调。langchain0.2 langchain-core0.2 langchain-openai0.1 langgraph0.2 python-dotenv1.0安装命令pip install langchain langchain-core langchain-openai langgraph python-dotenv2.2 项目结构我们用一个完整示例来贯穿全文企业订单售后助理 Agent。agent-demo/ ├── .env ├── requirements.txt ├── tools.py ├── agent.py └── main.pytools.py定义 Agent 可以调用的工具。agent.py使用 LangGraph 搭建 Agent 工作流。main.py入口脚本接收用户问题并让 Agent 执行。.env存放 API Key 和模型配置。2.3 配置大模型连接在.env文件中写入模型配置# 如果使用 OpenAI 官方接口 OPENAI_API_KEYsk-xxxx OPENAI_BASE_URLhttps://api.openai.com/v1 # 如果使用本地 Ollama # OPENAI_BASE_URLhttp://localhost:11434/v1 # OPENAI_API_KEYollama如果使用本地 Ollama需要提前拉取模型ollama pull qwen2.5:7b在本文示例中我们优先展示 OpenAI 兼容接口的调用方式因为这种方式可以平滑切换不同厂商的模型服务适合企业环境。3. 核心机制拆解LangChain、LangGraph、Harness 的关系3.1 LangChain 的核心抽象LangChain 是最早被广泛使用的大模型应用开发框架之一。它的核心贡献在于抽象出了几个常用组件ChatModel统一不同厂商的大模型调用接口。PromptTemplate把提示词变成可复用、可参数化的模板。Tool / tool把普通函数包装成模型可以理解并调用的工具。Memory管理对话历史。Chain把若干步骤串成固定流程。一个最简单的 LangChain 调用长这样from langchain_openai import ChatOpenAI from langchain_core.prompts import ChatPromptTemplate llm ChatOpenAI(modelgpt-4o-mini, temperature0) prompt ChatPromptTemplate.from_messages([ (system, 你是一个专业的订单售后助理。), (human, {question}) ]) chain prompt | llm response chain.invoke({question: 订单 20240715001 为什么还没发货}) print(response.content)LangChain 的prompt | llm这种管道式写法非常直观适合构建固定流程的应用比如 RAG 问答、文档摘要、内容分类等。但 LangChain 的 Chain 更适合“线性的、预先定义好的流程”。如果要做“模型自己决定下一步调用哪个工具、失败后重新规划”的动态流程Chain 就不太够了。3.2 LangGraph 如何补足 LangChain 的短板LangGraph 是专为构建有状态、可编排、可循环的 Agent 工作流而设计的框架。它引入了几个核心概念StateAgent 运行过程中的共享状态所有节点都可以读写。Node一个处理单元可以是调用模型、执行工具、判断条件等。Edge节点之间的连接。Conditional Edge条件边根据当前状态决定下一步走向哪个节点。Checkpointer可选的检查点机制用于保存和恢复运行状态。用 LangGraph 实现一个 ReAct 模式的 Agent流程是这样的用户输入 ↓ 模型节点决定下一步调用工具还是直接回答 ↓ 条件判断 ├→ 需要调用工具 → 工具节点 → 回到模型节点 └→ 已有答案 → 结束这个循环结构正是 DeepAgent 与普通 Chain 的本质区别。LangGraph 允许 Agent 在不断循环中逐步逼近答案而不是一次调用就结束。3.3 Harness 工程Agent 稳定运行的关键如果说 LangGraph 解决的是“Agent 流程怎么编排”那 Harness 解决的是“Agent 运行环境怎么控制”。一个完整的 Agent Harness 需要考虑运行循环控制设置最大迭代次数比如最多 10 步防止模型陷入死循环。工具白名单明确 Agent 可以调用哪些工具不能调用哪些工具。隔离环境如果 Agent 生成的代码要执行需要在 Docker 或其他沙箱中运行。日志与追踪记录每一轮模型输入、输出、工具调用参数、返回结果。人工介入遇到高风险操作如删除数据、转账、发送邮件时暂停并等待人工确认。在实际项目中LangGraph 负责编排流程而 Harness 思路则体现在对运行环境的控制上。很多企业自研 Agent 平台其实就是在 LangGraph 这类框架外面再包一层 Harness 控制能力。还有一个常被讨论的概念是 DeepSeek Harness。社区中出现的这类工具通常是把大模型推理、工具执行、日志可视化整合到一起甚至提供桌面端 Web 调试面板方便开发者观察 Agent 每一步的工具调用与中间输出。这类工具的出现说明 Agent 开发已经从“写 Prompt”转向“搭系统”的阶段。3.4 LangGraph 和 LangChain 的区别与选择很多人会问LangGraph 出来后LangChain 是不是过时了其实两者不是替代关系而是互补关系。对比项LangChainLangGraph核心模型Chain 链式调用StateGraph 状态图是否支持循环较弱原生支持是否支持条件分支有限原生支持是否适合复杂 Agent不太适合非常适合工具/模型抽象保留可复用 LangChain 组件建议如果你的任务流程是固定的、线性的用 LangChain 就够了。如果你的 Agent 需要自主规划、动态调用工具、失败后重试直接用 LangGraph。两者可以混合使用LangGraph 中调用 LangChain 的 ChatModel、Tool、Memory 等组件非常方便。4. 保姆级实战用 LangGraph 搭建企业级售后 Agent下面进入核心环节。我们从一个真实的业务场景出发完整实现一个可运行的企业级 Agent。4.1 场景定义与功能拆分假设我们是一家电商公司需要一个“订单售后助理” Agent它需要支持根据订单号查询订单状态。根据订单号判断是否满足退款条件并计算退款金额。如果用户问题超出工具能处理的范围礼貌地转人工。这个场景本身不复杂但它覆盖了 Agent 开发的核心环节工具定义、状态管理、条件路由、循环控制。4.2 编写工具层tools.py在tools.py中定义两个模拟业务工具# 文件路径agent-demo/tools.py from langchain_core.tools import tool # 模拟订单数据库 ORDER_DB { 20240715001: {status: 已发货, amount: 299.00, days_since_order: 12}, 20240715002: {status: 待发货, amount: 520.00, days_since_order: 2}, 20240715003: {status: 已签收, amount: 1299.00, days_since_order: 40}, } tool def get_order_status(order_id: str) - str: 根据订单号查询订单的发货状态。当用户询问订单是否发货、物流状态时使用。 order ORDER_DB.get(order_id) if order is None: return f没有找到订单号为 {order_id} 的订单请确认订单号是否正确。 return f订单 {order_id} 当前状态是{order[status]}。 tool def calculate_refund_amount(order_id: str) - str: 根据订单号判断退款条件并计算退款金额。当用户申请退款、询问退款金额时使用。 order ORDER_DB.get(order_id) if order is None: return f订单 {order_id} 不存在无法计算退款金额。 days order[days_since_order] if days 7: return ( f订单 {order_id} 已超过 7 天退款期限下单至今 {days} 天 不符合无理由退款条件建议引导用户咨询人工客服。 ) return f订单 {order_id} 满足退款条件可退款金额为 {order[amount]} 元。 ALL_TOOLS [get_order_status, calculate_refund_amount]这里有两个细节需要注意tool装饰器会把普通函数变成 LangChain 可识别的工具。函数里的docstring非常重要它是模型判断“什么时候该调用这个工具”的依据所以要写清楚触发条件和用途。4.3 搭建 LangGraph 状态图agent.py接下来是核心部分用 LangGraph 构建 Agent 的循环流程。# 文件路径agent-demo/agent.py from dotenv import load_dotenv from langchain_openai import ChatOpenAI from langgraph.graph import StateGraph, START, END, MessagesState from langgraph.prebuilt import ToolNode, tools_condition from tools import ALL_TOOLS load_dotenv() # 1. 初始化大模型并绑定工具 llm ChatOpenAI(modelgpt-4o-mini, temperature0) llm_with_tools llm.bind_tools(ALL_TOOLS) # 2. 定义模型节点Agent 根据当前对话状态决定下一步 def assistant_node(state: MessagesState) - dict: response llm_with_tools.invoke(state[messages]) return {messages: [response]} # 3. 构建状态图 def build_agent(): graph StateGraph(MessagesState) # 注册节点 graph.add_node(assistant, assistant_node) graph.add_node(tools, ToolNode(ALL_TOOLS)) # 设定起点 graph.add_edge(START, assistant) # 条件边如果模型决定调用工具进入工具节点否则直接结束 graph.add_conditional_edges( assistant, tools_condition, { tools: tools, __end__: END, }, ) # 工具执行完毕后回到模型节点让模型基于工具结果继续推理 graph.add_edge(tools, assistant) # 编译图 return graph.compile() # 4. 提供对外调用接口 def run_agent(user_input: str, max_iterations: int 5): agent build_agent() config {recursion_limit: max_iterations * 2 10} result agent.invoke( {messages: [{role: user, content: user_input}]}, configconfig, ) return result[messages][-1].content这段代码的循环逻辑可以这样理解用户输入进入assistant节点。模型判断是直接回答还是需要调用工具。如果需要工具则进入tools节点执行对应函数。工具返回结果后再次进入assistant节点。直到模型认为可以给出最终答案流程走到END。recursion_limit是 LangGraph 防止死循环的重要参数企业级环境中一定要设置。4.4 编写入口脚本main.py# 文件路径agent-demo/main.py from agent import run_agent if __name__ __main__: questions [ 订单 20240715001 为什么还没发货, 订单 20240715002 可以退款吗能退多少, 我想了解你们的退货政策。, ] for q in questions: print(f用户{q}) print(Agent) print(run_agent(q)) print(- * 60)运行方式python main.py4.5 预期结果说明预期的运行效果大致如下实际输出取决于模型用户订单 20240715001 为什么还没发货 Agent 我帮您查询了订单 20240715001 的状态当前显示为“已发货”。建议您关注物流信息如果长时间没有更新可以联系物流公司或转人工客服协助处理。 ------------------------------------------------------------ 用户订单 20240715002 可以退款吗能退多少 Agent 订单 20240715002 下单至今只有 2 天符合 7 天无理由退款条件可退款金额为 520 元。请问需要我为您发起退款申请吗 ------------------------------------------------------------ 用户我想了解你们的退货政策。 Agent 抱歉关于退货政策的具体细节我这边暂时无法直接查询。为了确保信息准确建议您转接人工客服咨询感谢理解可以看到Agent 在遇到无法通过工具解决的问题时能够给出合理的兜底回复而不是强行编造答案。这就是工具边界设计的作用。4.6 增加人工审批节点上面的示例 Agent 已经可以跑通基本流程。但在企业级场景中很多操作不能由 Agent 全权决定比如退款、删除、发消息等。这种时候需要引入Human-in-the-Loop人为介入机制。LangGraph 提供了interrupt_before参数来实现暂停点# 文件路径agent-demo/agent_with_human.py from langgraph.graph import StateGraph, START, END, MessagesState from langgraph.prebuilt import ToolNode, tools_condition from langchain_openai import ChatOpenAI from tools import ALL_TOOLS llm ChatOpenAI(modelgpt-4o-mini, temperature0) llm_with_tools llm.bind_tools(ALL_TOOLS) def assistant_node(state: MessagesState) - dict: response llm_with_tools.invoke(state[messages]) return {messages: [response]} def build_human_agent(): graph StateGraph(MessagesState) graph.add_node(assistant, assistant_node) graph.add_node(tools, ToolNode(ALL_TOOLS)) graph.add_edge(START, assistant) graph.add_conditional_edges( assistant, tools_condition, { tools: tools, __end__: END, }, ) graph.add_edge(tools, assistant) # 进入 tools 节点前暂停等待人工确认 return graph.compile(interrupt_before[tools]) def run_with_human_review(user_input: str): agent build_human_agent() result agent.invoke( {messages: [{role: user, content: user_input}]}, config{recursion_limit: 15}, ) # 如果结果被中断说明 Agent 想要调用工具 if result and messages in result: last_message result[messages][-1] if last_message.tool_calls: print(⚠️ Agent 请求调用以下工具) for call in last_message.tool_calls: print(f 工具: {call[name]}) print(f 参数: {call[args]}) # 这里可以加入人工审批逻辑 return result这种设计把决策权和执行权分离AI 负责建议人负责审批符合企业风控要求。5. 常见问题与排查思路实际开发中Agent 项目踩坑远比其他后端项目多因为中间加入了不可控的模型环节。下面是高频问题汇总。5.1 高频报错排查表问题现象常见原因解决思路模型完全不调用工具工具描述不清晰或模型没有收到工具定义检查bind_tools是否执行工具 docstring 是否写清楚触发条件Agent 死循环不结束缺少循环上限或条件边配置错误设置recursion_limit检查条件边返回值的对应关系报错langchain_core相关 ImportErrorLangChain 版本过旧或过新API 路径变动统一升级到 langchain0.2按当前版本调整 import 路径工具返回结果没有被模型理解工具返回的数据结构太复杂让工具返回简洁、结构化的文本必要时用 JSON模型给出编造的工具结果temperature 过高或模型幻觉调低 temperature增加“只能根据工具返回内容回答”的系统提示词中文输出乱码终端编码问题Windows 下设置chcp 65001或改用 UTF-8 编码输出5.2 排查问题的一般顺序当 Agent 行为不符合预期时不要急着改代码按下面顺序排查固定模型参数先把temperature设为 0排除随机性干扰。查看完整调用链打印每一轮的messages确认模型是否真的收到了工具返回结果。检查工具描述如果你是模型看到这段 docstring能知道什么时候调用吗逐步缩小范围先只绑定一个工具跑通再增加第二个。检查限额确认recursion_limit足够但不要设得过大否则一次异常可能会消耗大量 token。查看模型原文输出有些模型在复杂工具定义下会输出不符合格式的内容换用更稳定的模型或升级版本。5.3 关于模型选型的建议企业级 Agent 对模型稳定性要求较高。建议复杂工具调用场景优先选择 Tool Calling 能力强的模型。如果使用本地部署模型注意显存和推理延迟必要时用 vLLM 做高并发部署。在模型能力有限时可以通过“把复杂任务拆成多个简单步骤”来降低单步推理难度而不是把所有逻辑都塞进一个 Prompt。6. 企业落地 DeepAgent 的最佳实践6.1 工具设计规范Agent 的能力上限很大程度上由工具层决定。工具设计有几个关键原则单一职责一个工具只做一件事。不要把“查订单 计算退款”写成一个工具。描述清晰docstring 要写清楚“这个工具干什么、什么时候用、参数怎么传”。返回值结构化优先返回 JSON 字符串或规整文本方便模型解析。错误信息友好工具内部要做好异常捕获返回给模型的信息要让模型知道下一步该怎么办。tool def get_order_status(order_id: str) - str: 根据订单号查询订单状态。 当用户询问“订单是否发货”“物流到哪了”时使用。 参数 order_id 是用户的订单号例如 20240715001。 try: order ORDER_DB[order_id] return f订单 {order_id} 当前状态{order[status]} except KeyError: return f订单 {order_id} 不存在。请先确认订单号后重试。6.2 安全边界与权限控制这是企业级 Agent 与个人 Demo 最本质的区别。最小权限原则Agent 调用数据库时只授予查询权限不授予删除权限。敏感操作人工审批退款、发消息、删除数据等操作必须经过人工确认节点。工具白名单机制开发阶段做好工具注册表Agent 只能调用注册表中的工具。沙箱隔离如果 Agent 需要执行代码一定要在 Docker 容器或独立虚拟机中执行不能直接跑在宿主机。审计日志记录每次工具调用的参数、操作人、时间、返回结果方便问题追溯。6.3 可观测性与日志记录Agent 的决策链路比普通接口复杂得多必须做全链路追踪。建议记录以下信息每轮模型的完整输入和输出。模型决定调用哪个工具传了什么参数。工具的真实执行结果。每次调用的 token 消耗和耗时。最终回复内容及来源依据。你可以把每条记录写成一个结构化 JSON 写入日志系统{ session_id: xxx, step: 1, node: assistant, model: gpt-4o-mini, tool_calls: [ {name: get_order_status, args: {order_id: 20240715001}} ], latency_ms: 1200, tokens: 356 }如果团队有条件可以使用 LangSmith 等平台来做链路追踪也可以自研一个简单的日志中间件。6.4 成本与性能优化Agent 的 token 消耗通常比普通问答高很多因为它要经历多轮推理。优化方向如下压缩历史消息只保留最近几轮关键上下文防止上下文无限膨胀。结果缓存固定条件查询类工具可以加缓存避免重复调用模型。模型分级简单意图用便宜的小模型复杂推理用大模型。设置预算上限为每次 Agent 会话设置最大 token 消耗超限强制中止。异步处理与队列面对大量请求时用消息队列削峰避免压垮上游系统。一个实用的做法是在系统提示词中要求模型“消息只保留必要字段不要重复粘贴大段工具结果”能显著减少 token 浪费。6.5 从 Demo 到生产的清单如果你的 Agent 准备上线生产建议对照以下清单检查[ ] 是否设置了最大执行步数[ ] 敏感工具是否有人工审批[ ] 每次工具调用是否有审计日志[ ] 是否有超时和熔断机制[ ] API Key 是否通过环境变量或密钥管理平台配置[ ] 下游系统是否做了限流保护[ ] 是否有评测集来回归测试 Agent 效果[ ] 模型输出是否有敏感信息过滤7. 学习路线与进阶方向如果你从这个教程的 0 开始现在的进度大概是这样的理解了 DeepAgent 的基本概念和核心组成。知道了 Harness 在 Agent 框架中扮演什么角色。能区分 LangChain 和 LangGraph 的定位。跑通了一个基于 LangGraph 的完整 Agent 示例。了解了企业落地时需要补齐的安全、日志、成本控制能力。接下来可以继续深入的方向MCPModel Context Protocol用标准协议接入更多企业工具降低工具集成成本这是当前 Agent 工具层的重要趋势。Long-term Memory基于向量数据库实现历史记忆让 Agent 记住用户偏好与历史业务记录。Multi-Agent 协作多个 Agent 分工协作一个负责规划、一个负责执行、一个负责质检。评测体系建设 Agent 的自动化评测集从准确率、工具调用正确率、成本、延迟等维度持续评估。Harness 工程实践参考开源 Harness 工具的实现思路结合企业安全规范打造自己的 Agent 运行时环境。企业级 DeepAgent 是一个系统性工程模型能力只是起点框架编排、工具设计、安全管控、可观测性四者缺一不可。建议你先跑通本文的售后 Agent 示例再逐步替换成真实业务工具加上人工审批和日志追踪一个能用的企业级 Agent 就初步成型了后续再根据线上反馈不断迭代工具描述和流程设计稳定性的提升会非常明显。