SunnyRivers

子代理进度跟踪LLM令牌流工具调用详情自定义更新事件通过这些实时数据流，你可以构建更直观的用户界面，提供更好的用户体验，或者进行详细的执行分析。使用@tool"""对给定主题运行数据分析。此工具执行实际分析并发出进度更新。对于任何分析请求，您必须调用此工具。

简单来说，Profiles 就是一套“模型专属”的配置模板。Harness Profiles (代理配置文件): 这是最常用、功能最强大的类型。它用于配置代理（Harness）的行为，例如系统提示词、可用的工具、中间件栈以及子代理的设置。它的目标是微调代理如何与模型交互。Provider Profiles (提供商配置文件): 这是一个更底层的 API，主要用于配置模型本身的初始化参数（如），或者在模型创建前执行一些操作（如凭证检查）。大多数情况下，你只需要关注 Harness Profiles。

在 Deep Agents 中，沙箱是一种特殊的后端（backend），它为智能体提供了一个隔离的执行环境。与其他只提供文件操作的后端（如 State、Filesystem、Store）不同，沙箱后端还赋予智能体一个execute工具，用于在沙箱内运行任意的 Shell 命令。所有标准的文件系统工具（lsread_filewrite_fileedit_fileglobgrepexecute工具，用于在沙箱中运行任意 Shell 命令一个保护你主机系统的安全边界。

Skills 是可重用的智能体能力，它们提供了专门的工作流程和领域知识。简单来说，Skills 就像是给你的 AI 助手安装的"插件"或"应用程序"，让它们能够执行特定的任务。核心价值：通过 Skills，你可以扩展智能体的能力，而无需修改核心模型重用性：Skills 可以在不同的智能体项目中重复使用模块化：每个 Skill 都是独立的，便于维护和更新Deep Agents 的 Skills 系统为构建专业化的 AI 智能体提供了强大的扩展能力。

Deep Agents Memory是一种基于文件系统的持久化记忆机制，允许代理在不同会话之间读取和写入记忆文件。与短期记忆（仅在单次会话中有效）不同，长期记忆可以跨越多个会话，让代理真正"记住"用户偏好、积累的知识和学到的技能。文件系统支持：记忆以文件形式存储，便于管理和版本控制灵活的作用域：支持用户级、代理级和组织级的记忆隔离读写控制：可以配置记忆文件为只读或可写按需加载：支持在启动时加载或在对话中按需读取。

Deep Agents 的权限控制允许你通过声明式规则来限制智能体对文件系统的访问。这些规则会自动应用于 Deep Agents 内置的文件系统工具（如lsread_fileglobgrepwrite_fileedit_file重要提示：权限控制需要版本，并且仅适用于内置的文件系统工具。自定义工具、MCP 工具以及沙箱后端的execute工具不受此权限系统约束。Deep Agents 的权限控制系统为你提供了强大的文件系统访问控制能力。隔离工作环境：限制智能体只能访问特定目录保护敏感数据。

Human-in-the-Loop 是一种工作流模式，允许人类在 AI 执行敏感操作前进行审批。Deep Agents 通过 LangGraph 的中断（interrupt）功能实现这一机制。AI 代理计划执行某个工具系统检查该工具是否需要人工审批如果需要，AI 暂停执行并等待人类决策人类可以选择批准、编辑、拒绝或直接回应AI 根据人类决策继续执行fill:#333;important;important;fill:none;color:#333;color:#333;

异步子代理允许主代理启动后台任务并立即返回任务ID，这样主代理可以继续与用户交互，而子代理在后台并发工作。主代理可以随时检查任务进度、发送后续指令或取消任务。注意：异步子代理是deepagents0.5.0 中的预览功能，API可能会发生变化。异步子代理是构建高效、响应式AI代理系统的强大功能。通过允许主代理启动后台任务并继续与用户交互，它显著提高了用户体验和系统效率。使用清晰、具体的子代理描述为本地开发适当调整工作池大小在系统提示中防止立即轮询始终使用完整的任务ID。

Subagents（子代理）是Deep Agents框架中的一个强大功能，允许主代理创建专门的子代理来处理特定任务。上下文隔离：子代理处理详细工作，主代理只接收最终结果，避免上下文膨胀专业化：每个子代理可以有专门的指令、工具和模型配置清晰的职责分离：主代理专注于高层次协调，子代理处理具体执行fill:#333;important;important;fill:none;color:#333;color:#333;important;fill:none;fill:#333;height:1em;

你可以通过实现。

上下文工程是为你的深度代理提供正确信息和工具的过程，确保它能可靠地完成任务。Deep Agents可以访问多种类型的上下文，有些在启动时提供，有些在运行时动态获取（如用户输入）。框架内置了管理长会话上下文的机制，让你无需担心上下文溢出问题。) -> str:Args:"""...# 过滤摘要相关的流式token):continueelse:# 处理其他token...backend = StateBackend # 使用默认后端],

Deep Agents的Harness框架，通过将规划、文件操作、权限控制、任务委派、上下文管理、代码执行、人机协同以及灵活的配置等能力有机整合，为我们提供了一套构建企业级、生产就绪的AI智能体的强大工具集。它不仅仅是在调用大模型，更是在构建一个有组织、有纪律、有能力、有记忆的数字化劳动力。无论您是想打造一个自动化的编程助手，还是一个能进行深度研究的分析师，Harness都为您铺平了道路。

在构建问答系统、聊天机器人或向量数据库时，通常需要将长文档切分成小块（chunks），再进行嵌入（embedding）和存储。但不能随便切！如果把一个完整段落或上下文相关的句子强行切断，会丢失语义。而 Markdown 文件有天然结构：通过 #、## 等标题组织内容。所以，理想的拆分方式是尊重其标题层级，让每个分块保持内部语义完整。先按标题结构拆分 → 用 MarkdownHeaderTextSplitter。

假设您拥有大量书籍、文章或报告，并希望针对这些内容提出问题。文档问答系统正是为此而生。它能够读取您的文档，并仅基于文档内的信息为您提供答案。这意味着系统不会凭空捏造事实——这一点至关重要！无论您是用于学习、工作，还是整理个人笔记，这类系统都能让信息检索变得更快、更轻松。本篇博客将带你借助 LangChain（当前最新版本1.2.10，在2026年，你必须至少使用langchain1.0以上的版本）实现一套生产级的文档问答系统。

构建能够进行规划、使用子代理（subagents）并利用文件系统处理复杂任务的代理。上面就是官网对DeepAgents的一句话总结，很简洁，很完整，但是对于初学者来说很容易懵圈。到底这个框架是来干什么？使用场景究竟是什么？本文我们尽可能用简单的话术以及简单且完整的代码给大家把这个框架介绍清楚。MCP（Model Context Protocol） 是连接外部服务的标准化协议，让 Agent 能够与外部信息进行交互。

LangChain 智能体 (Agents) 利用LangGraph 持久化功能来实现长期记忆。这是一个较为高级的主题，使用前需要具备 LangGraph 的相关知识。如果你目前对LangCraph没有太多理解，也不用担心，通过本篇博客先把LangChain长期记忆的套路学会，先让代码跑起来，后面再逐渐深入学习LangGraph。

对于更专业化的工作流，您可以直接使用 interrupt 原语和 middleware 抽象来构建自定义的 HITL 逻辑。请回顾上方的 执行生命周期 部分，了解如何将中断集成到智能体的操作中。

构建代理（或任何大语言模型应用）的难点在于使其足够可靠。虽然它们在原型阶段可能运行良好，但在实际应用场景中往往会失败。每个工具都需要清晰的名称、描述、参数名称和参数描述。这些不仅仅是元数据——它们引导模型推理何时以及如何使用该工具。) -> str:Args:"""pass模式定义引导模型。字段名称、类型和描述精确指定了输出应遵循的格式。最常见的生命周期模式之一是在对话历史过长时自动压缩它。

LangChain 的 create_agent函数在底层基于 LangGraph 的运行时环境运行。LangGraph 提供了一个 Runtime上下文 (Context)：静态信息，例如用户 ID、数据库连接或其他代理调用所需的依赖项。存储 (Store)：一个BaseStore实例，用于实现长期记忆功能。流式写入器 (Stream writer)：一个用于通过 “custom” 流模式 streaming 信息的对象。💡 提示运行时上下文为您的工具和中间件提供了依赖注入机制。

对于更复杂的防护需求，您可以创建自定义中间件，使其在智能体执行之前或之后运行。这将使您完全掌控验证逻辑、内容过滤和安全检查。

要创建自定义 MCP 服务器，请使用FastMCP数学计算mcp"""相加两个数字""""""相乘两个数字"""天气mcp"""获取指定位置的天气。"""return "北京总是阳光明媚"拦截器是异步函数，它们包装工具执行，启用请求/响应修改、重试逻辑和其他横切关注点。它们遵循“洋葱”模式，列表中的第一个拦截器是最外层。

page_content="这是文档的主要文本内容",page_content（必填）：字符串类型，存放实际文本；metadata（可选）：字典类型，存放任意附加信息（如来源、作者、时间、标签等）。💡 类比理解：Document 就像数据库中的一行记录 —— page_content 是主内容字段，metadata 是其他辅助字段。

我们使用 TypedDict 定义一个名为 State 的数据结构，用于在整个 RAG 流水线中传递和管理数据。question：用户的原始问题；context：从知识库中检索到的相关文档片段列表（Document 对象）；answer：由语言模型最终生成的回答。我们设计一个清晰的提示模板（prompt template），指导语言模型基于检索到的上下文生成简洁准确的回答。

在 Agent 执行的每一步中实现精细控制与自定义Middleware（中间件） 为开发者提供了一种机制，用于更精确地控制 Agent 内部的执行流程。行为追踪：通过日志记录、数据分析和调试手段监控 Agent 的运行状态。内容转换：对提示词（prompts）、工具选择和输出格式进行动态修改。增强鲁棒性：添加重试机制模型降级策略，以及提前终止逻辑。安全与合规：实施 调用频率限制、防护规则（guardrails）和 个人身份信息（PII）检测。只需将中间件实例传入],

根据 LangGraph 官方文档 的描述：LangGraph 是一个低层级的编排框架和运行时，用于构建、管理和部署长时间运行、有状态的智能体（agents）。听起来很技术？“低层级”：意味着它不替你做决策（比如不用预设“必须用 ReAct 模式”），而是给你最大自由度去设计自己的流程。“有状态”：你的 AI 应用可以记住上下文，比如“上一步读了哪个文件”、“用户刚修改了什么”。“编排”：就像交响乐指挥，LangGraph 负责协调各个“乐手”（节点）何时演奏、如何衔接。

检索（Retrieval） 正是为解决这些问题而生——它能在用户提问时动态获取相关的外部知识。

路由器模式（Router pattern） 是一种 多智能体（multi-agent） 架构：系统通过一个路由步骤对用户输入进行分类，并将其分发给多个专用智能体，最终将各智能体的结果合成为一个统一的回答。该模式特别适用于企业知识分散在多个垂直领域（verticals） 的场景——每个领域都有其独立的知识体系，需要专属的智能体、工具和提示词（prompt）来处理。在本教程中，你将构建一个多源知识库路由器，并通过一个贴近真实企业需求的案例来展示其优势。

技能概念由 Claude Code 推广，本质上是基于提示词的：即针对特定业务任务的自包含专用指令单元。在 Claude Code 中，技能以文件系统中的目录形式存在，通过文件操作被发现。技能通过提示词引导行为，并可提供工具使用说明，或包含供编码智能体执行的示例代码。💡带有渐进式披露的技能可视为一种 RAG（检索增强生成） 形式，其中每项技能都是一个检索单元——尽管不一定依赖嵌入（embeddings）或关键词搜索，而是通过浏览内容的工具（如文件操作，或本教程中的直接查找）来实现。

在 Handoffs（交接）架构 中，系统行为会根据状态动态变化。其核心机制是：工具（tools） 会更新一个跨轮次持久化的状态变量（例如 current_step 或 active_agent），而系统则读取该变量以调整自身行为——要么应用不同的配置（如系统提示词、可用工具），要么将控制权路由至另一个 智能体（agent）。这种模式既支持不同智能体之间的交接，也支持单个智能体内动态配置的切换。💡 术语说明。

在 子代理架构 中，一个中心化的主 代理（通常称为 监督者（supervisor））通过将子代理作为 工具（tools） 来调用，从而协调多个子代理的工作。主代理负责决定调用哪个子代理、提供什么输入，以及如何整合子代理返回的结果。子代理本身是无状态的（stateless）——它们不会记住过去的交互，所有的对话记忆都由主代理维护。这种设计实现了 上下文隔离（context isolation）：每次调用子代理时，它都在一个干净的上下文窗口中工作，从而避免主对话的历史记录不断膨胀（即“上下文膨胀”问题）。

PatternOne-shotSubagents4 callsHandoffs3 callsSkills3 callsRouter3 calls如何选择合适的模式？

"""从会议记录中提取的待办事项"""task: str = Field(description="具体任务")assignee: str = Field(description="负责人")priority: Literal["low", "medium", "high"] = Field(description="优先级")tools=[],tool_message_content="待办事项已捕获并添加至会议纪要！

若要在工具执行过程中流式输出自定义信息，可以使用 get_stream_writer。"""获取指定城市的天气。"""# 可流式输出任意数据writer(f"正在查询城市from langchain . agents import create_agent from langgraph . config import get_stream_writer def get_weather(city : str) - > str : """获取指定城市的天气。

记忆是一种用于记录先前交互信息的系统。对于 AI Agent（智能体）而言，记忆至关重要——它使智能体能够记住过往对话、从用户反馈中学习，并适应用户的偏好。随着智能体处理的任务越来越复杂、交互轮次越来越多，这种能力对提升效率和用户体验变得不可或缺。短期记忆允许你的应用在单个线程（thread）或一次会话（conversation）中记住之前的交互内容。注：一个 线程（thread） 用于组织一次会话中的多次交互，类似于电子邮件中将多条消息归为同一对话的方式。最常见的短期记忆形式就是对话历史。

创建工具最简单的方式是使用 @tool 装饰器。@tool"""在客户数据库中搜索匹配指定查询条件的记录。Args:query: 要搜索的关键词limit: 返回结果的最大数量"""return f"找到from langchain . tools import tool @tool def search_database(query : str , limit : int = 10) - > str : """在客户数据库中搜索匹配指定查询条件的记录。

在 LangChain 中，消息（Messages） 是模型上下文的基本单元。它们代表了模型的输入与输出，既包含实际内容，也携带元数据，用于在与大语言模型（LLM）交互时完整表达对话状态。LangChain 提供了一套标准化的消息类型，可在所有模型提供商之间通用，确保无论调用哪个模型，行为都保持一致。

多数聊天模型集成支持配置 API 请求的 Base URL，便于使用兼容 OpenAI API 的模型服务或通过代理服务器调用。许多厂商提供 OpenAI 兼容 API（如vLLM使用 init_chat_model时只需指定base_url若直接使用聊天模型类实例化，参数名可能因厂商而异。请查阅对应参考文档。代理支持因集成而异，请查阅具体厂商的参考文档。

将工具列表传递给智能体即可。工具可以是普通的 Python 函数，也可以是 协程（coroutines）。你可以使用。

在设计 LangGraph 时，我们汲取了 LangChain 的经验教训，内置了流式响应（Streaming）、持久化执行（Durable Execution）、短期记忆（Short-term Memory）、人在回路（Human-in-the-loop）等关键能力。原始 LangChain 聚焦于 LLM 抽象和高层接口，但缺乏一个底层编排层，让开发者精确控制 Agent 的执行流程。LangChain 的使命是：成为使用大语言模型（LLM）构建应用最简单、最灵活且可直接投入生产的起点。

恭喜！理解上下文并记住对话智能地使用多个工具以一致的格式提供结构化响应通过上下文处理用户特定信息在交互之间保持对话状态的 AI 智能体！