在用 LangGraph 构建多 Agent 系统时你是否经常遇到这样的场景Researcher Agent 辛辛苦苦输出了一大段自然语言总结下一个 Critic Agent 或 Writer Agent 却完全“看不懂”无法提取关键信息导致整个流程卡死Supervisor 反复把同一个任务扔回给子 Agent陷入无限循环或者下游节点期望结构化数据却收到杂乱的字符串解析失败、Tool Calling 无法触发。这就是 LangGraph尤其是多 Agent 协作中最常见、也最让人头疼的问题之一——输出格式不一致。本文将深入剖析这个问题产生的根本原因并重点介绍 2026 年最推荐的解决利器llm.with_structured_output() Pydantic Model。掌握这个技巧后你的 Agent 间协作将从“经常卡住”变成“像调用 API 一样稳定可靠”。一、为什么输出格式不一致如此致命LangGraph 的核心是状态化图StateGraph节点之间通过共享 State 传递数据。每个节点通常是一个 Agent执行后需要把结果更新到 State 中供下一个节点使用。然而大模型LLM默认是“聊天模式”它擅长生成自然语言却不擅长严格遵守格式。上一个 Agent 可能输出“以下是我的研究总结……一大段自由文本”而下一个 Agent 或 Coordinator 期望的是{ summary: ..., key_findings: [...], next_action: critic }这样的结构化 JSON。常见表现形式解析失败下游 Agent 无法从自然语言中可靠提取字段导致决策错误。路由卡死Supervisor 依赖next字段决定路由但收到的输出没有这个字段。上下文膨胀反复让模型“重新格式化”token 消耗暴增成本上升。无限循环模型输出不符合预期Supervisor 不断重试同一 Agent。在多 Agent 系统中这个问题会被成倍放大。因为不像单 Agent 只需最终输出自然语言多 Agent 需要Agent 之间像模块一样精确通信。二、根本原因分析LLM 输出本质是概率性的即使你在 Prompt 中写“请用 JSON 输出”模型仍可能添加多余文字、遗漏字段、或格式错误。LangGraph 依赖结构化状态更新节点返回的 dict 需要符合 State Schema否则 Reducer 无法正确合并或下游节点无法读取。Tool Calling 与自由输出冲突ReAct Agent 同时支持 Tool Calling 和自由回复时模型容易混淆输出格式。层次化架构放大问题子图Subgraph返回的私有字段如果不是父图定义的 Key就会被默默丢弃进一步加剧格式不一致的影响。社区 2025-2026 年的反馈显示这个问题占多 Agent 项目调试时间的 30%-50% 以上。三、最佳解决方案强制使用.with_structured_output()LangChain / LangGraph 提供了强大且可靠的结构化输出机制——with_structured_output()。它会自动将 Pydantic Model 转换为模型可理解的 JSON Schema在 Prompt 中注入格式指令使用 JSON Mode 或 Function Calling 强制模型严格遵守如果输出不符合自动重试部分模型支持。3.1 核心代码示例frompydanticimportBaseModel,Fieldfromlangchain_openaiimportChatOpenAIfromlanggraph.prebuiltimportcreate_react_agentfromtypingimportList# 定义每个 Agent 的输出结构强烈推荐为每个 Agent 单独定义classResearcherOutput(BaseModel):reasoning:strField(...,description你的思考过程)summary:strField(...,description研究总结控制在 200 字以内)key_findings:List[str]Field(...,description3-5 个关键发现用列表形式)gaps:List[str]Field(...,description还需要补充的信息或疑问)next_agent:strField(...,description下一步应该交给哪个 Agentcritic / writer / done)confidence:floatField(...,ge0,le1,description输出置信度)# 绑定结构化输出核心一步llmChatOpenAI(modelgpt-4o,temperature0.2)structured_llmllm.with_structured_output(ResearcherOutput)# 创建 Researcher Agentresearcher_agentcreate_react_agent(modelstructured_llm,# 使用结构化 LLMtoolsresearch_tools,# 可选进一步强化 Promptstate_modifierlambdastate:[(system,你是一个严谨的研究员必须严格按照指定的 JSON Schema 输出不要添加任何额外文字。)]state[messages])3.2 在多 Agent 协作中的应用Coordinator / Supervisor也使用结构化输出定义RouterModel专门决定next_agent。Critic Agent可以定义CritiqueOutput包含quality_score、suggestions等字段专门校验上游输出。在 State 中增加对应字段如research_output: ResearcherOutput | None让状态更新更清晰。四、配套最佳实践Prompt 强化永远不要只依赖结构化输出Prompt 中仍需明确说明“必须严格遵守以下 Schema不要添加多余文字”。State Schema 配合在 MultiAgentState 中为每个 Agent 的输出预留专用字段避免所有信息都塞进messages。调试神器打开 LangSmith查看每个 Agent 的输入输出对比快速定位格式问题。防退化为重要节点设置temperature0或0.1降低随机性。生产建议结合langgraph-supervisor或自定义 Coordinator Node让路由决策也结构化。总结在 LangGraph 多 Agent 开发中输出格式不是“提示词问题”而是工程契约问题。把.with_structured_output() Pydantic当成每个 Agent 的“输出 API 规范”你的系统就会从脆弱的“聊天系统”升级为可靠的“Agent 流水线”。如果觉得这篇有用欢迎点赞和关注一起玩转 LangGraph