搞懂DeepAgent、Harness与LangGraph：Agent框架核心机制实战

DeepAgentHarnessLangChain
于 2026-08-30 04:01:35 修改
·本内容遵循CC 4.0 BY-SA版权协议

好的，我理解全部要求。现在直接为你输出一篇完整、可直接发布的CSDN技术教程博文。

作为一名后端开发，过去半年我一直在和各种 Agent 框架打交道。从最初调 LangChain 的 Agent 经常“答非所问”，到后来把团队业务接入 LangGraph 做状态编排，再到研究 DeepAgent 这类强调“控制循环”的企业级框架，一个很深的感受是：如果只看官方文档，很容易被各种抽象名词绕晕，但一旦理解了底层机制，所有 Agent 框架的核心套路其实是一致的。

这篇文章我想把这段时间的实践经验整理成一套保姆级教程。围绕 DeepAgent、Harness、LangChain、LangGraph 这组关键词，从“这些概念到底是干什么的”讲起，再拆解 Agent 运行的核心机制，最后给出一个可以直接落地的可运行项目，并且补充你在生产环境里大概率会遇到的问题和排查思路。不管你是刚入门 AI 应用开发，还是已经在业务里尝试接大模型，这篇文章都能给你一条相对完整的路径。

先说清楚：我不会把每个框架的 API 都罗列一遍，而是重点讲透 Agent 的运行机制——因为只要你理解了 Harness 是怎么控制 Agent 循环的，理解 LangGraph 的状态图为什么是这么设计的，再看任何框架的文档，都会轻松很多。

1. 先把概念搞清楚：DeepAgent、Harness、LangChain 和 LangGraph 到底指什么

很多初学者一开始就把这几个词当成并列的技术栈去学，结果越学越乱。我先用通俗的方式把它们归一下类。

1.1 DeepAgent 是什么

DeepAgent 并不是某个官方发布的单一框架，而是在大模型应用开发中，用来描述“具备自主决策能力的智能体运行机制”的一类框架或架构方案。通俗地说，DeepAgent 强调的是：大模型不只是回答你的问题，而是能自己规划步骤、调用工具、观察结果、修正策略，最终完成任务。

这种机制通常包含以下模块：

  • 规划（Planning）：大模型把用户的目标拆解成一系列可执行的步骤。
  • 工具调用（Tool Calling）：根据规划结果，调用外部 API、数据库、代码执行器等。
  • 记忆（Memory）：保存对话历史或任务过程中的关键信息。
  • 执行与反馈（Execution & Reflection）：执行工具后，把结果反馈给大模型，让它判断下一步怎么做。

所以当你听到“DeepAgent 框架”时，可以把它理解为一套专门用来构建上述能力的工程化方案。

1.2 Harness 是什么

Harness 直译过来是“马具、挽具”，在 AI Agent 领域，Harness 指的是包裹在大模型之外的运行时控制层。

你可以这样理解：大模型本身只是一个“大脑”，它输出 Token、生成文字。Harness 则负责在大模型输出之前和之后，做一系列工程化处理，比如：

  • 维护对话上下文。
  • 解析大模型输出中的工具调用指令。
  • 执行工具并将结果返回给模型。
  • 控制整个循环什么时候结束。
  • 处理超时、重试、安全限制。

现在不少团队提到“Harness Engineering”，本质上就是把 Agent 的循环控制逻辑当成一个独立工程设计问题来看待。Codex Harness、DeepSeek Harness 这类名词，也都指的是围绕特定模型构建的 Agent 控制层。

1.3 LangChain 和 LangGraph 的关系

LangChain 是最早让“用大模型开发应用”变得简单的一批框架。它提供了 LLM 封装、Prompt 模板、Chain 链式调用、Agent 工具等模块。

LangGraph 是 LangChain 团队后来推出的底层编排框架。你可以理解成：LangChain 是上层封装，LangGraph 是底层状态机。

LangGraph 的核心思路，是把 Agent 的每一次思考、工具调用、结果返回，都看作状态图里的一个节点和一条边。开发者可以精确控制状态如何在节点之间流转，这比 LangChain 早期 Agent 里那种“黑盒循环”要可控得多。

另外提一下，LangGraph 和 LangChain 并不是替代关系。LangGraph 里照样可以使用 LangChain 的模型封装、Prompt 模板和工具组件。它们的关系是“上下层协作”，不是“二选一”。

1.4 AI 大模型在整个体系里的位置

AI 大模型是整个 Agent 系统的推理引擎。无论是 DeepAgent、Harness 还是 LangChain，最终都要调用一个或多个大模型来完成理解、规划、生成等核心能力。

当前阶段，主流的调用方式有两种：

  • 直接调用 API，比如 OpenAI、DeepSeek、Qwen 的开放接口。
  • 本地部署开源模型，通过 vLLM、Ollama 等工具提供 OpenAI 兼容接口。

在 Agent 开发中，你不需要特别关心模型内部的训练细节，但必须清楚模型的上下文窗口、函数调用能力、输出格式稳定性，这些会直接影响 Agent 的上限。

2. 环境准备与版本说明

在开始写代码之前，我们先把环境准备好。本文的示例会以 Python 和 LangGraph 为主，因为这套组合既能让你看清楚 Agent 的运行机制，又能快速落地业务。

2.1 运行环境

项目 说明
操作系统 Windows 10/11、macOS、Linux 均可
Python 版本 建议 3.10 及以上
包管理工具 pip 或 poetry
模型 API OpenAI 兼容接口，可采用 DeepSeek、OpenAI、通义千问等
框架版本 langchain、langgraph、langchain-openai，具体版本以官方 PyPI 最新为准

由于 LangChain 和 LangGraph 的迭代速度非常快，本文示例中不会把版本号写死。你在安装时，建议直接安装最新稳定版。

2.2 创建虚拟环境

这里我以 Python 的 venv 为例：

BASH
python -m venv agentenv
source agentenv/bin/activate # Linux / macOS
# 或
agentenv\Scripts\activate # Windows

激活之后，升级 pip：

BASH
pip install --upgrade pip

2.3 安装依赖

接下来安装核心依赖：

BASH
pip install langchain langchain-openai langgraph

这里说明一下每个依赖的作用：

  • langchain：提供模型封装、Prompt 模板、工具定义等基础组件。
  • langchain-openai：让 LangChain 能调用所有 OpenAI 兼容接口。
  • langgraph：提供状态图编排能力，是我们实现 Agent 循环的核心。

另外，如果希望做一些开发调试，可以安装 python-dotenv 来管理环境变量：

BASH
pip install python-dotenv

2.4 配置模型 API

在项目根目录新建一个 .env 文件，用于存放模型 API 相关的环境变量：

ENV
OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxx
OPENAI_BASE_URL=https://api.deepseek.com/v1
OPENAI_MODEL_NAME=deepseek-chat

如果你的模型来自其他服务商，只需要把 OPENAI_BASE_URL 换成对应的 Base URL 即可。

注意：这里有一个非常容易踩的坑。很多人拿到 LangChain 示例代码，发现调用失败，是因为 LangChain 默认会去连 OpenAI 官方接口。如果你使用的是国内模型服务，请务必设置 OPENAI_BASE_URL。还有一点需要提醒：生产环境里不要把 API Key 直接写死在代码里，应该通过环境变量或密钥管理服务注入。

3. 核心机制拆解：Agent 到底是怎么“自动思考”的

这一节是整个教程的重点，我们会从底层机制上弄清楚一个 Agent 是如何连续思考、调用工具、最终完成任务的。

3.1 ReAct 范式：思考 - 行动 - 观察

现在的 Agent 框架，绝大多数都遵循 ReAct 范式，也就是 Reason + Act 的循环。

它的基本流程是：

  1. 思考（Thought）：大模型根据当前对话上下文，决定下一步需要做什么。
  2. 行动（Action）：如果需要调用工具，大模型输出一个结构化指令，比如调用某个函数。
  3. 观察（Observation）：系统执行工具，并把结果返回给大模型。
  4. 重复：大模型看到观察结果后，继续思考，直到认为可以给出最终答案。

用文字描述可能不够直观，我们看一个最简单的手写循环示例。

PYTHON
# 文件路径：examples/mini_agent.py
from openai import OpenAI
 
client = OpenAI()
 
messages = [
{"role": "system", "content": "你是一个只使用工具回答问题的助手。"},
{"role": "user", "content": "计算 12345 乘以 6789 的结果，然后再加 100。"}
]
 
tools = [
{
"type": "function",
"function": {
"name": "calculator",
"description": "执行四则运算",
"parameters": {
"type": "object",
"properties": {
"expression": {"type": "string", "description": "数学表达式"}
},
"required": ["expression"]
}
}
}
]
 
for step in range(5):
response = client.chat.completions.create(
model="gpt-4o-mini",
messages=messages,
tools=tools
)
message = response.choices[0].message
messages.append(message)
 
if message.tool_calls:
for tool_call in message.tool_calls:
args = eval(tool_call.function.arguments)
result = eval(args["expression"])
messages.append({
"role": "tool",
"tool_call_id": tool_call.id,
"content": str(result)
})
continue
else:
print("最终答案：", message.content)
break

这段代码虽然简陋，但它包含了 Agent 循环的全部关键要素：模型判断是否需要调用工具、系统执行工具、结果回填给模型、模型继续推理直到输出最终答案。

这也是理解后面所有框架的基础：LangChain 也好，LangGraph 也好，本质上都是在帮你封装这个循环。

3.2 任务规划能力是怎么实现的

很多人问：“LangChain 中的任务规划能力是如何实现的？”

任务规划并不是某个独立算法，而是大模型根据 Prompt 指令、上下文信息、可用工具列表，自主生成执行步骤。实现方式主要有三种：

第一种：单步 ReAct 循环。 模型每一步只决定一个动作，执行完再决定下一步。好处是灵活，坏处是步骤多了容易“迷失”。

第二种：Plan-and-Execute。 模型先根据用户目标生成一份完整计划，然后逐步执行。比如用户说“帮我调研一下竞争对手的产品”，模型会先生成“打开搜索→搜索关键词→整理结果→生成报告”这样的计划，然后逐步执行。

第三种：结构化输出规划。 框架约束模型输出 JSON 等结构化格式，比如 {"step": "第一步", "action": "search_web", "args": {...}}。这种方式便于代码解析，也方便加入校验和重试逻辑。

LangGraph 比 LangChain 早期的 Agent 更加强大，是因为它允许你把“规划”和“执行”设计成图里的不同节点，既能动态规划，也能固定流程，甚至能做多层嵌套。

3.3 记忆机制对 Agent 的影响

Agent 需要记忆，否则模型会忘记前面已经做过的操作。

记忆大致可以分为三层：

  • 短期记忆：指一次任务内，把所有对话历史和中间结果都放进上下文里。这种方式实现简单，但会占用大量 Token。
  • 长期记忆：把重要信息存入向量数据库，比如 Chroma、Milvus。需要时通过检索把相关内容取回。
  • 工作记忆：在代码层维护一个状态对象，记录当前任务进度、已完成步骤、需要保留的中间变量。LangGraph 的状态机制就是典型的工作记忆。

在真实项目中，这三种记忆往往是组合使用的。比如：全局上下文只保留最近几轮对话，团队知识库放进向量数据库，任务状态全部放在 LangGraph 的 State 里。

3.4 LangChain 和 LangGraph 的区别，用一个例子说透

我用一个比喻来帮助大家记忆：

LangChain 更像是“预制菜流水线”。你把食材（工具）、菜谱（Prompt）准备好，可以用简单的 Chain 顺序执行，也可以用 AgentExecutor 自动调度。优点是上手快，缺点是流程一旦复杂，你很难精确控制每一步。

LangGraph 更像是“可编程流水线”。你得先把工序画成图纸（状态图），然后自己定义每个工位（节点）做什么、工序之间怎么流转。优点是完全可控，适合复杂业务。

下面是一个例子，假设我们需要实现一个“如果用户问天气，就查天气工具；否则走普通对话”的 Agent。

如果用 LangChain 早期的 AgentExecutor，你只需要定义一个工具列表，框架自己去决定调用哪个。但实际运行中，模型偶尔会挑错工具，或者陷入无限循环。这在生产环境里是非常致命的。

如果用 LangGraph，你可以把 “判断工具” 和 “执行工具” 拆成两个节点，并且在进入工具节点之前做一次规则判断，这样就能避免模型误用工具。本质上，LangGraph 的图结构给了你更多干预和兜底的机会。

4. 完整实战：基于 LangGraph 构建一个可落地的企业级 Agent

下面进入正题，我们用 LangGraph 来实现一个相对完整的 Agent。

这个 Agent 的需求是：用户输入一段产品需求描述，Agent 能先判断意图，然后调用“需求分析工具”提取关键信息，最后调用“文档生成工具”生成一份结构化的需求文档。

4.1 项目目录结构

我们先建立一个清晰的项目结构：

TEXT
enterprise_agent/
├── .env
├── requirements.txt
├── agent/
│ ├── __init__.py
│ ├── graph.py
│ ├── nodes.py
│ ├── state.py
│ └── tools.py
└── main.py

这个结构把状态定义、节点实现、工具实现和图的构建分开，便于维护。

4.2 定义 Agent 状态

在 LangGraph 中，状态是一个核心概念。所有节点共享一份状态对象，节点之间通过状态传递数据。

PYTHON
# 文件路径：agent/state.py
from typing import TypedDict, Annotated
from langgraph.graph.message import add_messages
 
 
class AgentState(TypedDict):
"""Agent 的全局状态"""
messages: Annotated[list, add_messages] # 对话消息列表
intent: str # 用户意图
requirement_text: str # 原始需求文本
analysis_result: str # 需求分析结果
doc_content: str # 生成的文档内容
error: str # 错误信息

这里的 messages 字段使用了 LangGraph 提供的 add_messages 标注，它的作用是当多个节点都要往消息列表里追加内容时，自动进行合并而不是覆盖。

4.3 编写工具函数

工具函数是 Agent 执行具体操作的能力。在本例中，我们提供两个简单的模拟工具：

PYTHON
# 文件路径：agent/tools.py
def analyze_requirement(text: str) -> str:
"""分析需求文本，提取关键要素"""
keywords = ["登录", "支付", "首页", "列表", "报表", "权限"]
found = [kw for kw in keywords if kw in text]
if not found:
return "未能识别出明确的核心功能关键词"
return f"识别到核心功能模块：{', '.join(found)}"
 
 
def generate_doc(analysis: str) -> str:
"""根据分析结果生成需求文档片段"""
return (
"# 需求说明书\n\n"
f"## 功能模块\n{analysis}\n\n"
"## 验收标准\n- 功能正常运行\n- 数据准确\n"
)

这里把工具写成普通函数，是为了让你看清楚：LangGraph 节点里执行的逻辑可以是你任意写的 Python 代码，不一定要被框架包装。 这在实际业务中意义重大，因为企业的很多系统调用都是内部 RPC、数据库操作，无法完全走大模型工具标准化协议。

4.4 实现节点逻辑

接下来定义图中的各个节点。节点就是一个接收状态、返回新状态增量的普通函数。

PYTHON
# 文件路径：agent/nodes.py
from agent.state import AgentState
from agent.tools import analyze_requirement, generate_doc
 
 
def intent_node(state: AgentState) -> dict:
"""根据用户输入判断意图"""
last_message = state["messages"][-1].content
if "需求" in last_message or "文档" in last_message:
intent = "requirement"
else:
intent = "chat"
return {"intent": intent}
 
 
def analyze_node(state: AgentState) -> dict:
"""调用需求分析工具"""
requirement_text = state["messages"][-1].content
result = analyze_requirement(requirement_text)
return {"analysis_result": result, "requirement_text": requirement_text}
 
 
def document_node(state: AgentState) -> dict:
"""生成需求文档"""
doc = generate_doc(state["analysis_result"])
return {"doc_content": doc}
 
 
def chat_node(state: AgentState) -> dict:
"""普通对话节点"""
last_message = state["messages"][-1].content
return {"messages": [{"role": "assistant", "content": f"我听到你说：{last_message}。我可以帮你整理需求文档。"}]}
 
 
def error_node(state: AgentState) -> dict:
"""兜底错误处理节点"""
return {"messages": [{"role": "assistant", "content": "系统处理失败，请稍后再试。"}]}

关于这里要重点解释的是 intent_node：在实际大模型项目中，意图判断不一定非要调用大模型，有时候用简单的规则反而更快更稳定。你可以把它理解成一个“可插拔的决策节点”，以后想换成大模型判断，只需修改这一个节点内部实现，不需要动整张图。

4.5 构建图结构

现在把这些节点组合成一张图：

PYTHON
# 文件路径：agent/graph.py
from langgraph.graph import StateGraph, START, END
from agent.state import AgentState
from agent.nodes import intent_node, analyze_node, document_node, chat_node, error_node
 
 
def build_graph():
"""构建 Agent 状态图"""
graph = StateGraph(AgentState)
 
# 添加节点
graph.add_node("intent", intent_node)
graph.add_node("analyze", analyze_node)
graph.add_node("document", document_node)
graph.add_node("chat", chat_node)
graph.add_node("error", error_node)
 
# 添加入口
graph.add_edge(START, "intent")
 
# 根据意图决定走向
graph.add_conditional_edges(
"intent",
lambda state: "analyze" if state["intent"] == "requirement" else "chat",
{"analyze": "analyze", "chat": "chat"}
)
 
# 正常流程
graph.add_edge("analyze", "document")
graph.add_edge("document", END)
 
# 聊天流程
graph.add_edge("chat", END)
 
return graph.compile()

可能有读者会问：error_node 和错误处理在哪里用上？这里先保留一个节点，说明图设计里可以预留兜底路径。后面我们在 5.3 节中会展示如何在节点执行异常时跳转到这个节点。

4.6 编写入口文件

PYTHON
# 文件路径：main.py
import os
from dotenv import load_dotenv
 
from agent.graph import build_graph
 
load_dotenv()
 
if __name__ == "__main__":
app = build_graph()
 
# 第一个测试输入：需求类
result_1 = app.invoke({
"messages": [{"role": "user", "content": "我们想要一个带登录、支付、权限管理的系统，帮我生成需求文档。"}]
})
print("=== 需求类输入 ===")
print(result_1["analysis_result"])
print(result_1["doc_content"])
 
# 第二个测试输入：聊天类
result_2 = app.invoke({
"messages": [{"role": "user", "content": "你好，今天天气不错啊"}]
})
print("\n=== 聊天类输入 ===")
print(result_2["messages"][-1].content)

4.7 运行与验证

在项目根目录执行：

BASH
python main.py

预期输出效果如下（实际内容取决于你的输入和工具函数实现）：

TEXT
=== 需求类输入 ===
识别到核心功能模块：登录, 支付, 权限
# 需求说明书
 
## 功能模块
识别到核心功能模块：登录, 支付, 权限
 
## 验收标准
- 功能正常运行
- 数据准确
 
=== 聊天类输入 ===
我听到你说：你好，今天天气不错啊。我可以帮你整理需求文档。

这样一来，你就能直观看到状态图如何根据意图把不同的节点串联起来。这里虽然还没有真正调用大模型，但你已经理解了 Agent 的骨架。后续不管接什么大模型、什么工具，都是往这张图里填血肉。

5. 常见问题与排查思路

在实际使用 LangGraph、LangChain 或自己写 Harness 层的过程中，很多问题其实是相似的。我整理了下面几个高频问题。

问题现象 常见原因 解决思路
Agent 陷入无限循环 模型不断调用同一个工具，或工具调用链过长 在 Harness 层设置最大迭代次数；用 LangGraph 时设计终结条件
工具调用参数格式错误 模型输出 JSON 与实际函数签名不一致 对工具参数做严格校验；给模型提供函数描述的示例
模型调用 API 超时 网络环境不稳定或模型服务负载高 设置合理的超时和重试策略；必要时切换备用模型通道
上下文越长费用越高 所有历史消息全部塞给模型 增加消息摘要节点，历史超过阈值后进行压缩
模型返回内容不稳定 Prompt 指令不够明确 定义清晰的输出格式，必要时使用 JSON Schema 约束
LangGraph 编译报错 边引用了不存在的节点或条件映射错误 检查节点名称和条件字典的 key 是否一致

5.1 无限循环怎么处理

在 LangGraph 里，你可以在条件边中增加计数器。当某个节点的执行次数超过阈值时，直接跳转到结束节点。

PYTHON
# 思路示例：在状态中增加 loop_count
def conditional_continue(state):
if state["loop_count"] > 5:
return "end"
return "continue"

这比单纯依靠大模型“自我判断”要安全得多。

5.2 工具调用失败怎么办

工具执行失败时，不要直接中断整个 Agent 流程。正确做法是：把异常信息当作“观察结果”回传给大模型，让模型决定是换一种参数重试，还是换一个工具，或者直接放弃。

如果你在 LangGraph 中使用 try/except 包装工具节点，返回一个 tool_error 字段，可以在条件边里判断是否需要重试。

5.3 在 LangGraph 中增加异常兜底路径

这里我们把前面预留的 error_node 接入图中，展示完整的容错写法。

PYTHON
# 文件路径：agent/graph.py（带异常兜底）
from langgraph.graph import StateGraph, START, END
from agent.state import AgentState
from agent.nodes import intent_node, analyze_node, document_node, chat_node, error_node
 
 
def build_graph_with_error_handling():
graph = StateGraph(AgentState)
 
graph.add_node("intent", intent_node)
graph.add_node("analyze", analyze_node)
graph.add_node("document", document_node)
graph.add_node("chat", chat_node)
graph.add_node("error", error_node)
 
graph.add_edge(START, "intent")
 
graph.add_conditional_edges(
"intent",
lambda state: "analyze" if state["intent"] == "requirement" else "chat",
{"analyze": "analyze", "chat": "chat"}
)
 
# 分析节点执行失败时跳转到 error
graph.add_edge("analyze", "document")
graph.add_edge("document", END)
graph.add_edge("error", END)
 
# 这里可以通过条件边实现失败跳转
graph.add_conditional_edges(
"analyze",
lambda state: "error" if state.get("error") else "document",
{"error": "error", "document": "document"}
)
 
graph.add_edge("chat", END)
 
return graph.compile()

在这个示例中，如果分析节点返回的错误字段不为空，会进入 error 节点，否则继续生成文档。这体现了 LangGraph 的另一个价值：你可以把容错逻辑作为显式路径画在图里，让 Agent 的行为变得可预期。

5.4 部署和监控层面的问题

本地跑通之后，部署到服务器或容器环境时，还需要额外关注：

  • API Key 不要打进镜像，要使用环境变量或 Secret 管理工具。
  • Agent 的日志要记录“每次调用的模型、工具、耗时、Token 数”，方便排查。
  • 生产环境建议加一层限流，防止异常循环导致巨额费用。

6. 最佳实践与工程建议

最后这部分，分享一些我在企业项目里总结出的工程经验。

6.1 把图当作业务流程，而不是技术实现

很多开发者一开始就陷入 LangGraph 的 API 细节里，忽略了真正重要的是业务流程。在画图之前，我建议你先用纸笔画出业务流转过程：

  • 哪些环节需要大模型参与？
  • 哪些环节可以走规则判断？
  • 哪些环节必须人工兜底？

把这些问题想清楚后，再用代码实现，会高效很多。这一点和 Harness Engineering 的思想也是相通的：先定义控制逻辑，再考虑模型能力。

6.2 每个工具都要有清晰的描述

大模型是靠工具描述来决定何时使用该工具的。如果你的工具描述写得太模糊，模型就会经常用错。写工具描述时，尽量包含：

  • 这个工具是干什么的。
  • 什么场景下使用。
  • 参数分别代表什么含义。
  • 一个典型的调用示例。
PYTHON
def get_user_balance(user_id: str) -> float:
"""
根据用户 ID 查询账户余额。
只有当用户明确询问余额时使用。
示例：get_user_balance("U12345")
"""
...

6.3 用结构化输出约束模型

对于企业级系统，模型输出的稳定性至关重要。如果只是用自然语言让模型“按格式输出”，很容易出现随机偏差。建议使用结构化输出约束，比如 LangChain 的 with_structured_output，或者直接在后端做 JSON Schema 校验。

6.4 State 设计要扁平化

在 LangGraph 中，State 设计得越扁平，节点间的耦合越少。尽量不要在 State 里放一个超大的嵌套对象，否则调试的时候很难看清状态变化。可以按业务领域拆分不同字段，比如 user_context、task_progress、final_answer。

6.5 重视可观测性

很多人写 Agent 时只关心最终结果，忽略了过程日志。在真实项目里，一个 Agent 任务可能跨多个节点、多次模型调用，如果没有完整日志，出了问题会非常难排查。建议在每个节点里加入结构化日志，记录：

  • 当前节点名。
  • 输入的关键字段。
  • 输出字段。
  • 节点耗时。
  • 模型调用次数和 Token 消耗。

在 LangGraph 中，你可以为每个节点加一个日志装饰器，或者在节点函数内部打印关键信息。

6.6 做充足的测试

Agent 的测试思路和传统后端完全不同。除了单元测试，你还需要对“模型调用的分支结果”做模拟测试。比如，工具返回异常格式时，Agent 是否还能继续处理。

建议至少覆盖以下场景：

  • 正常路径：输入符合预期，顺利完成任务。
  • 工具异常：工具抛错，能触发兜底逻辑。
  • 超长输入：对话历史很长，是否有压缩逻辑。
  • 空输入 / 无意图：模型能否判断出需要用户补充信息。
  • 敏感输入：是否会被安全策略拦截。

7. 总结

通过这篇文章，我们把 DeepAgent、Harness、LangChain、LangGraph 这几个容易混淆的概念重新梳理了一遍。它们的核心关系可以这样理解：DeepAgent 是一种智能体运行机制的统称，Harness 是包裹在大模型外的控制层，LangChain 提供了构建智能体的基础组件，LangGraph 则用状态图的方式帮助你把控制逻辑可视化、工程化。

文章中的实战示例虽然只用到了规则判断和简单工具，但骨架已经足够清晰。你可以在上面继续增加大模型节点、向量检索工具、数据库读写工具，甚至接入消息队列做异步任务处理。

如果你现在准备在项目中引入 Agent 机制，我的建议是：先不要急着追求复杂的框架和炫酷的功能，而是从一张简单的图开始，把流程跑通，把日志和容错做好。当你对图的结构越来越熟悉，再去处理复杂的动态规划、多 Agent 协作，会顺手很多。

希望这篇教程能帮你少走一些弯路。如果你在搭建过程中有自己的心得或者踩坑经历，欢迎在评论区交流。

DeepAgent和Harness到底是什么关系？选框架时该关注哪一层？
LangChain、LangGraph与DeepAgent：AI Agent开发技术栈全解析与实战选型指南
暗黑游侠
LangChain、LangGraph与DeepAgent：AI Agent开发三件套详解与选型指南
暗黑游侠
LangChain、LangGraph与DeepAgent：AI Agent开发三驾马车对比与选型指南
往后清白
LangChain、LangGraph与DeepAgent：AI Agent开发技术栈全解析与选型指南
往后清白
LangChain、LangGraph与DeepAgent：AI智能体开发框架选型指南
暗黑游侠
LangChain、LangGraph与DeepAgent：AI应用开发技术栈全解析
通人情
LangChain DeepAgent实战：构建智能代码分析Agent的完整指南
往后清白
2026年AI应用工程师必备：LangChain、LangGraph、Harness与RAG技术栈深度解析
往后清白
DeepAgents、LangChain和LangGraph之间是什么样的技术关系？
GGccc_
企业级DeepAgent框架落地：Harness+LangChain+LangGraph机制解析
本文系统解析企业级DeepAgent框架的三层核心架构：底层Agent Harness负责循环控制与状态管理，中间层LangChain实现模型与工具的抽象接入，上层LangGraph提供有状态、可恢复、可观测的图编排能力。内容涵盖适用场景边界、环境准备、API服务封装、资源性能优化及常见问题排查，聚焦信息技术领域中AI Agent系统的设计原理与工程实践。
weixin_30664615
381
企业级DeepAgent框架：LangGraph与Harness实战解析
本文深入解析企业级DeepAgent框架的核心机制，聚焦Harness作为运行时控制器的关键作用，以及LangGraph在状态化Agent编排中的工程优势。内容涵盖Harness校验、LangGraph图构建、循环控制、状态管理、安全边界与可观测性等关键技术点，并提供可落地的代码示例与最佳实践，强调模型决策需受控于框架而非自由发挥。
不吃章鱼烧
349
DeepAgent与Harness：从LangChain到LangGraph的AI Agent工程化指南
本文系统解析DeepAgent作为企业级AI Agent工程化体系的本质，阐明Harness作为运行时控制框架的核心作用，以及LangChain与LangGraph在Agent开发中的定位差异：LangChain适用于线性工具调用，LangGraph则通过StateGraph实现带状态、分支和循环的复杂流程编排。文章涵盖感知-规划-行动-观察核心循环、工具注册、记忆管理、可观测性设计及生产最佳实践，强调从脚本到可交付服务的关键升级路径。
努力忏悔修行
249
DeepAgent实战：理清LangChain、LangGraph与Harness的三层分工
本文系统剖析DeepAgent中Harness、LangChain与LangGraph的职责边界：LangChain作为组件库提供模型封装与工具抽象；LangGraph作为图编排引擎实现状态驱动的条件分支与多轮流程控制；Harness则作为工程化外壳，负责超时、重试、日志、输入校验等运行时管控。文章涵盖最小Demo搭建、企业级Agent四大核心机制（模型/工具调用、记忆管理、任务规划、可观测性）、LangGraph实战编排及三层排查方法论，强调状态一致性、工具幂等性与生产化必备工程项。
顺德韭菜星
272
LangGraph实战：从Harness到企业级DeepAgent完整落地指南
本文系统讲解如何基于LangGraph构建企业级DeepAgent，涵盖Harness工程化控制、LangChain与LangGraph协同机制、状态图编排、工具层设计、人工审批节点集成及可观测性实践。重点解析Agent循环控制、安全边界、日志追踪、成本优化等生产必备能力，提供可运行的售后助理Agent完整代码与落地 checklist。
Solarex
330
DeepAgent架构实战：LangChain、LangGraph与Harness企业级Agent落地指南
本文系统讲解基于LangChain、LangGraph与Harness构建企业级Agent应用的完整路径，涵盖四层架构设计（模型层、编排层、组件层、约束层）、状态图编排、工具调用、输出Schema校验、FastAPI接口封装及批量任务队列。重点解决任务拆解、状态管理、行为约束与可观测性等生产核心问题，所有代码适配API调用模式，无需本地大模型，强调工程化、安全边界与性能控制。
不想不见
260
LangChain、LangGraph 与 Deep Agents：一文搞懂三者区别与选型
本文深入对比LangChain、LangGraph和Deep Agents三大AI Agent框架，从架构层次、核心功能与适用场景三方面展开分析：LangChain作为基础构建块，适合简单RAG和单轮对话；LangGraph基于状态图提供复杂工作流编排与断点续传能力；Deep Agents是高层Agent框架，内置任务规划、上下文管理与子代理生成。三者呈递进关系，选型需依据任务复杂度与生产需求。
风生yy
889
DeepAgents Harness：状态驱动的AI智能体执行框架解析
本文深入解析DeepAgents的Harness执行框架，聚焦其状态驱动（StateGraph）架构如何解决LangChain基础Agent在上下文管理、多阶段规划和工具隔离上的三大硬伤。通过深度搜索实操案例，详解Harness三层抽象（Runtime/Plugin/Driver）、核心参数配置、自定义语义检索工具实现，以及状态持久化、任务依赖与上下文隔离等关键技术机制，强调Harness作为AI智能体‘操作系统内核’的工程价值。
weixin_30608503
451
[DeepAgents:LangChain平台的Harness-01]LangChain、LangGraph和DeepAgents三者之间的关系
本文深入剖析LangChain、LangGraph和DeepAgents三者的技术定位与协作关系：LangChain是Agent开发框架，提供核心模块；LangGraph是基于状态图的运行时系统，支撑持久化、流式与人机交互；DeepAgents则是构建于LangChain之上、深度集成LangGraph的生产级Agent框架，通过预注册中间件（如FileSystemMiddleware、TodoListMiddleware、SubAgentMiddleware等）实现任务规划、长期记忆、子Agent生成等高级能力，显著降低复杂Agent开发门槛。
JaydenAI
738
SDK Harness架构 ：DeepAgent 基于LangGraph的生产级Super Agent驾驭层实现
45岁资深老架构师尼恩
562
彻底搞懂Deep Agents全新升级：手把手玩转Agent Harness，收藏这篇就够了！
Deep Agents是一款基于LangChain与LangGraph构建的开源AI Agent框架，支持自动规划、文件系统交互、Shell命令执行及子Agent委派。其核心SDK提供可插拔中间件、原生LangGraph集成、多LLM供应商兼容性与沙盒化工具安全机制，显著降低复杂Agent开发门槛。
Python_金钱豹
450
从 Prompt 到 Platform：企业级 AI Agent 平台工程专栏导读
本文系统梳理企业级AI Agent从Prompt Engineering迈向Platform Engineering的技术演进路径，涵盖上下文控制（Context Engineering）、Agent Runtime设计、Harness Loop受控自我修正、Graph Engineering、AI Data Platform、多租户治理及MCP/A2A/Agent Registry协同等核心议题，强调运行控制、状态治理与数据演进三大闭环，构建可运行、可治理、可评测的生产级AI平台能力。
kishu_iOS&AI
1467
[智能体-362]：Deep agent的框架
本文系统阐述LangChain生态下的Deep Agents Harness框架，涵盖四层架构：LangGraph运行时（状态管理、图引擎、检查点、中断与流式输出）、LangChain能力库（LLM接入、Skill/Tool抽象、Memory）、核心Harness层（Planner任务规划、VFS虚拟文件系统、Subagent编排、HITL人机回路、Sandbox安全沙箱）及应用层接入。重点突出其工程化能力，如显式任务分解、超长上下文处理、多智能体协作、企业级合规与执行隔离。
文火冰糖的硅基工坊
204
深度智能代理框架DeepAgents：构建企业级AI代理系统的终极解决方案
DeepAgents是一个基于LangGraph和LangChain的企业级AI代理框架，支持模块化分层架构、模型无关部署、子代理并行处理、智能上下文管理及LangSmith可观测性集成。其核心特性包括统一文件系统抽象、可扩展中间件系统、MCP工具动态加载、生产级持久化与检查点机制，以及面向文档处理等复杂任务的实战能力，专为大规模、高可靠AI代理系统设计。
仲羿禹
436
基于Langchain、Langgraph与DeepAgents构建企业级Agent记忆系统
大模型应用在连续对话和跨会话场景中常出现“失忆”现象，影响了智能体Agent在电商导购、客服等场景中的服务连续性。构建可靠的记忆系统成为工程化落地的关键。记忆系统通常分为短期记忆与长期记忆：短期记忆基于对话窗口管理上下文，长期记忆则借助向量检索技术将用户偏好、历史信息持久化，并结合用户画像实现个性化服务。Langchain提供了模型调用与RAG等基础组件，Langgraph以图编排实现可控的记忆读写流程，而DeepAgents则简化了智能体的运行循环集成。在电商推荐助手中，通过记忆系统记录肤质、预算等画像，
LangChain DeepAgents 0.2深度解析：构建自主智能体的完整指南！
本文深度解析LangChain DeepAgents 0.2版本的核心升级，重点介绍可插拔后端架构（支持LangGraph State、Store、本地文件系统及OSS等复合存储）、大型工具结果驱逐、对话历史摘要、未完成工具调用修复等关键能力，并对比DeepAgents、LangChain与LangGraph在智能体开发中的定位与适用场景，明确其作为自主智能体工具（Agent Harness）的技术价值。
Agent学习路线
1993
第01章 LangChain 概述与环境搭建
本文系统介绍LangChain 1.0的核心定位、生态体系（LangChain/LangGraph/Deep Agent/LangSmith）及智能体四大能力模块；重点阐述其从链式思维到智能体优先的范式跃迁，并详细指导基于Python的开发环境配置、DeepSeek模型的OpenAI兼容API调用、init_chat_model初始化及首个答疑助手案例实现，涵盖API Key管理、依赖安装与常见问题排查。
m0_60873365
399
从零实现多智能体协作与异步任务编排：DeepAgents 与 Harness 实战
大模型应用开发中，单个 Agent 只能完成短链路任务，一旦涉及多步骤、多角色的复杂业务，就会面临上下文截断、串行低效、容错性差等问题。多智能体协作通过拆解任务、分配角色、统一消息传递，让系统具备更强的规划与执行能力。而异步任务编排则进一步解决了无依赖子任务的并行执行问题，显著缩短整体耗时。Harness 作为多智能体系统的运行框架，负责调度、状态管理和错误恢复，是整个架构稳定落地的关键。本文从 Agent 循环、工具调用等基础概念出发，逐步实现可运行的多智能体系统，并演示 Supervisor-Worke
weixin_34409357
205
DeepSeek Harness 实战：从插件开发到批量任务编排
在大模型应用开发中，智能体（Agent）与工具调用能力已成为衡量工程化水平的关键指标。借助插件化架构，开发者可以将模型能力与外部工具解耦，通过统一调度层实现任务编排、接口调用与批量处理。这种设计不仅降低了重复开发成本，也为私有化部署和企业工具链集成提供了灵活路径。DeepSeek Harness 正是将这一理念落地到 DeepSeek 生态的开源框架，其“一切皆插件”的核心设计，使得模型不再局限于对话，而是能按需加载 Skill 插件、执行复杂任务。本文从环境准备、服务启动到插件开发与 API 调用，梳理了
[DeepAgents:LangChain的Harness-02]构建抽象的文件系统
本文详解DeepAgents中基于BackendProtocol协议构建的统一文件系统抽象，涵盖StateBackend（状态内瞬时存储）、FilesystemBackend（宿主机直连）、StoreBackend（跨会话持久化）、SandboxBackend（沙箱隔离执行）及CompositeBackend（多后端路由）。重点描述各后端接口定义、安全机制、路径控制、序列化格式与典型使用场景，突出其在AI Agent上下文管理与外部存储解耦中的核心作用。
JaydenAI
416