在使用LangChain/LangGraph开发智能体时你是否遇到过设计工具导致幻觉的场景明明已经约定模型返回值了但还是输出了思考过程导致提示词越来越复杂难懂(模型层面)。本文将介绍工具设计时的两种方式约定使智能体的输出在我们预想的范围内。一、return_direct 的底层机制、场景1. 核心定义return_direct是 LangChain 自定义 Tool 的核心流程控制布尔参数默认值为False。它的作用是决定工具执行结束后是否截断整个Agent推理链路。简单来说控制「工具跑完后要不要再交给大模型继续思考」。2. 两种模式完整工作链路模式1return_direct False默认模式完整执行流程用户提问 → Agent 解析意图判定需要调用工具 → 执行自定义Tool逻辑工具返回原始结果文本/字典/列表结果重新塞入LLM上下文进入二次推理LLM结合工具返回结果 系统提示词 历史对话整理、润色、扩写、总结生成自然语言最终回复返回用户适用场景所有工具只负责拿数据、不负责出答案的场景检索知识库、查询数据库、联网搜索、代码执行、数据统计。这类场景下工具返回的是原始、生硬、无排版的数据必须依靠大模型二次加工才能传递给用户。优缺点优点回答更自然、话术统一、支持多工具多轮联动缺点多一轮外层LLM推理、Token消耗更高、耗时更长、存在幻觉风险模式2return_direct True直返模式完整执行流程用户提问 → Agent 解析意图命中当前工具规则 → 执行Tool工具执行完毕后直接返回结果不进入LLM二次推理、不刷新prompt、不继续路由工具返回内容直接作为本轮对话最终输出适用场景业务结果无需润色、规则固定、确定性极强的场景纯数值计算、公式推理固定指令应答、开关类操作结构化JSON输出、接口透传结果权限校验、参数校验、拒绝应答优缺点优点零二次推理、极致省Token、耗时最低、杜绝模型篡改工具执行结果缺点无法自然润色仅适合结构化/固定话术输出3. 使用方式class _BaseInput(BaseModel): query: str Field(..., description...) class BaseTool(BaseTool): name: str base_tool description: str ... args_schema: type[BaseModel] _BaseInput return_direct: bool True # BaseTool 原生参数保证工具输出原封不动返回给父节点 def _run(self, query: str): return self._arun(query) async def _arun(self, query: str) - str: try: return 成功 except Exception as e: return f失败: {str(e)}注意return_direct参数在pydantic~2.13.3不兼容新版langchain-core1.3.3,降低pydantic版本pip install pydantic2.12.3 pydantic-core2.41.4 --force-reinstall4. 生产环境缺点LangGraph 嵌套场景 return_direct 失效在 Graph 节点内部通过create_agent嵌套子Agent子Agent工具配置的return_directTrue无法穿透外层Graph。原因子Agent是独立执行上下文Graph外层状态流转不感知子工具的直返标记依旧会继续走图流程导致直返无效、流程错乱。多工具串联时 return_direct 优先级最低同一个Agent挂载多个工具时只要存在后续可执行工具直返参数工具会被Agent调度逻辑覆盖无法终止链路。return_direct 直返不携带记忆润色直返结果完全脱离LLM不会结合历史对话做上下文适配纯工具原生输出若工具未做格式化处理前端极易出现展示错乱。5. 工程化最佳实践检索、问答、搜索类工具统一约定参数为False依靠模型润色整合规则型、计算型、结构化输出工具统一约定参数为True提速降本控幻觉直返工具建议搭配Pydantic结构化输出保证工具返回格式稳定可渲染二、Pydantic 模型约束返回体1. 为什么必须强制Pydantic约束大模型原生输出是自由自然语言存在三大工程问题字段忽多忽少、随机缺失输出格式不统一时而JSON、时而文本、时而换行特殊字符乱码、嵌套层级错乱、无法对接后端接口在私有化小模型、低参数量模型、复杂业务prompt场景下格式幻觉概率会指数级上升。 Pydantic结构化输出是LangChain官方唯一推荐的生产级标准化落地方案。2. 工作原理开发者基于Pydantic V2定义数据模型字段名、字段类型、必填规则、默认值、字段描述、校验规则通过PydanticOutputParser绑定模型自动生成固定格式约束Prompt将格式约束注入系统提示词强制模型必须输出合规JSON模型输出后解析器自动校验类型校验、空值校验、字段校验校验失败自动抛出异常可配置重试/兜底逻辑避免服务崩溃3. 能力详解1强类型强制约束支持字符串、数字、布尔、枚举、嵌套模型、列表、字典等所有类型彻底杜绝「类型错乱」。 比如强制分数为float、ID为字符串、状态为枚举值从根源避免脏数据。2Field语义约束通过Field(description, requiredTrue, defaultxxx)给模型明确业务语义告诉模型每个字段代表什么业务含义强制必填字段不能为空异常场景自动填充默认值 大幅降低模型字段遗漏、语义混淆的问题。3自动纠错与解析兜底LangChain解析器具备轻度容错能力自动剔除markdown代码块json标记自动修复首尾多余字符、换行、空格配合try-catch可实现解析失败重试、降级兜底输出4适配LangGraph状态流转Graph的State状态本质是字典结构Pydantic模型可直接序列化/反序列化完美适配状态存储、节点传参、上下文回溯。4. 使用方式# pydantic 模型 class AnalysisResult(BaseModel): param1: bool param2: str Field(defaultxxx) ​ agent create_agent( modelmodel, system_promptsystem_prompt, namebase-agent, # 约定返回结构 response_formatAnalysisResult, )5. 价值彻底消灭输出随机性无论模型、轮次、输入如何变化输出结构永远统一前后端无缝对接固定JSON结构可直接用于前端渲染、数据库存储、第三方接口回调降低运维成本无需人工处理格式错乱减少线上报错、日志异常适配多节点协同多智能体、多工具、多节点工作流中统一数据协议无对接成本三、LangChain LangGraph 实践1. 轻量简单业务单能力、单工具直接使用 LangChain 原生 Agent 自定义 Tool确定性结果工具return_directTrue检索润色类工具return_directFalse全部输出启用 Pydantic 结构化约束优势开发快、结构简单、无需Graph编排、运维成本低2. 复杂业务多能力、多分支、多路由采用 LangGraph 分层架构路由节点LLM意图识别分发不同业务技能节点技能节点拆分独立Agent能力各司其职输出节点统一结构化结果封装、兜底处理优势拆分单Agent超大Prompt、降低Token消耗、减少模型幻觉、流程可追溯3. 流式业务强制规范所有节点禁止阻塞式嵌套调用统一使用astream流式消费所有输出强制Pydantic约束手动管控Graph终止逻辑杜绝死循环4. 通用准则永远不要让单Agent承载过多Prompt和工具永远不要信任大模型自由文本输出Graph节点返回必须遵循State结构禁止随意返回值嵌套Agent优先子图方案禁止黑盒阻塞调用四、核心总结return_direct管控工具推理链路解决冗余推理、Token浪费、模型二次篡改问题是工具层的流程开关Pydantic结构化输出从数据层根治模型格式幻觉是大模型应用从Demo走向工业化的必备约束工业化智能体开发的核心逻辑分层解耦 结构约束 流程可控 流式保真。关于我后续会持续分享 Agent 开发的实战经验欢迎关注。