你在调试 LangChain Agent 时很容易看到这样的代码result agent.invoke({ messages: [ {role: system, content: 你是一个天气预报员}, {role: user, content: 北京天气怎么样} ] }) print(result[messages])然后打印出来的并不是一句简单的回答而是一长串SystemMessage(...) HumanMessage(...) AIMessage(...) ToolMessage(...) AIMessage(...)第一次看到这里最容易产生两个疑问为什么一次提问会返回这么多消息这些 SystemMessage、HumanMessage、ToolMessage、AIMessage 到底分别代表什么其实只要先抓住一条主线就很好理解用户输入 ↓ 模型决策 ↓ 如果需要工具发起 tool call ↓ 工具执行 ↓ 工具结果返回模型 ↓ 模型继续决策或生成最终回答LangChain 的 messages本质上就是在记录这条执行链路。先搞清楚result[messages] 是什么在当前 LangChain Agent 中Agent 会维护一个 AgentState。其中最核心的内置字段就是AgentState └── messages # 当前线程中的消息历史类型为 list[BaseMessage]也就是说result agent.invoke(...)拿到的 result 通常不是“模型的一句话回答”而是 Agent 执行结束后的状态。而result[messages]才是这次 Agent 执行过程中积累下来的消息序列。可以简单理解成result │ ├── messages # 消息历史 ├── structured_response # 如果配置了结构化输出可能存在 └── 其他自定义 State 字段所以以后看到result[messages][-1].content它的意思就是取当前消息历史里的最后一条消息。在大多数普通 Agent 场景中最后一条通常就是模型最终生成的 AIMessage。BaseMessage所有消息的共同父类SystemMessage、HumanMessage、AIMessage、ToolMessage 都继承自 BaseMessage。因此它们会共享一批基础字段。按照当前 LangChain 的消息结构可以重点理解成BaseMessage │ ├── content # 消息原始内容可以是文本也可以是内容块列表 ├── additional_kwargs # 模型供应商或扩展数据 ├── response_metadata # 响应元数据如模型名、finish_reason、headers 等 ├── name # 可选的人类可读名称 ├── id # 消息唯一 ID ├── type # 消息类型如 human / ai / tool / system ├── content_blocks # 标准化后的内容块例如文本、图片、文件、推理块等 └── text # 从消息内容中提取出的文本视图这里最需要记住的是content 是消息主体其他字段更多是在描述“这条消息是什么、从哪里来、还带了什么额外信息”。SystemMessage告诉模型“应该怎么工作”SystemMessage 主要负责给模型提供系统级规则。例如from langchain_core.messages import SystemMessage SystemMessage( content你是一个天气助手回答要简洁准确。 )它表达的是SystemMessage │ ├── content # 系统提示词、规则、角色、行为约束 ├── additional_kwargs # 扩展字段 ├── response_metadata # 响应元数据 ├── name # 可选名称 ├── id # 消息 ID └── type system # 固定类型在普通聊天模型调用中系统消息通常位于消息序列前面SystemMessage ↓ HumanMessage ↓ AIMessageHumanMessage用户输入HumanMessage 最简单。它就是用户发送给模型的消息。例如from langchain_core.messages import HumanMessage HumanMessage(content北京天气怎么样)核心字段可以理解成HumanMessage │ ├── content # 用户输入 ├── additional_kwargs # 额外扩展数据 ├── response_metadata # 响应元数据普通输入消息通常没有重要内容 ├── name # 用户或发送者名称可选 ├── id # 消息唯一 ID └── type human # 固定类型当你这样调用 Agentagent.invoke({ messages: [ {role: user, content: 北京天气怎么样} ] })LangChain 会把这种标准消息格式转换成对应的消息对象。也就是可以把它理解成{role: user, content: 北京天气怎么样} ↓ HumanMessage(content北京天气怎么样)AIMessage最重要的一种消息AIMessage 不只是“AI 回答了什么”。在 Agent 场景中它还有一个更重要的作用记录模型这一轮做出的决策。模型这一轮可能有两种典型行为。情况一直接回答比如用户问1 1 等于多少模型不需要调用工具。那么可能直接产生AIMessage └── content 2情况二模型决定调用工具比如用户问北京天气怎么样Agent 有一个天气工具。模型可能不会立刻给最终答案而是返回AIMessage │ ├── content └── tool_calls └── get_weather(city北京)所以在 Agent 里AIMessage 既可以表示最终回答也可以表示“我要调用哪个工具”的中间决策。AIMessage 里有哪些重要字段可以重点记住下面这些AIMessage │ ├── content # 模型输出正文 ├── additional_kwargs # 模型供应商原始扩展字段 ├── response_metadata # 模型名、finish_reason、响应头等 ├── name # Agent 名称可选例如 Alice / Bob ├── id # 消息唯一 ID ├── type ai # 固定类型 ├── tool_calls # 已成功解析的工具调用 ├── invalid_tool_calls # 解析失败或格式异常的工具调用 └── usage_metadata # LangChain 标准化后的 Token 使用统计这里真正和 Agent 执行关系最大的是tool_callstool_calls 里面又有什么假设模型决定调用get_weather(city北京)对应的 tool_calls 大致可以理解成[ { name: get_weather, args: { city: 北京 }, id: call_123, type: tool_call } ]字段关系是tool_calls └── ToolCall ├── name # 要调用哪个工具 ├── args # 传给工具的参数 ├── id # 这一次工具调用的唯一标识 └── type # tool_call所以AIMessage.tool_calls真正表达的是模型认为下一步应该执行哪些工具以及分别传什么参数。这一步非常关键。模型本身并没有执行工具。它只是生成了一个“工具调用请求”。真正执行工具是 Agent 框架后面的工具执行节点完成的。ToolMessage把工具执行结果重新交给模型假设模型刚刚产生AIMessage └── tool_calls └── id call_123 name get_weather args {city: 北京}Agent 框架看到这个 tool call 后就会真正执行get_weather(city北京)假设工具返回北京今天晴25°CLangChain 会把这个结果包装成ToolMessage │ ├── content 北京今天晴25°C └── tool_call_id call_123然后再交回给模型。模型看到工具结果后才继续生成最终回答。一次完整工具调用messages 是怎么变化的现在把整个流程串起来。假设用户输入北京天气怎么样Agent 有一个get_weather工具。一次典型执行过程就是HumanMessage 用户北京天气怎么样 ↓ AIMessage 模型我要调用 get_weather tool_calls [ { name: get_weather, args: {city: 北京}, id: call_123 } ] ↓ ToolMessage 工具北京今天晴25°C tool_call_id call_123 ↓ AIMessage 模型北京今天晴气温约 25°C。也就是说result[messages] 最终可能类似[ HumanMessage(...), AIMessage(tool_calls[...]), ToolMessage(...), AIMessage(...) ]这就是最典型的 Agent 消息链路。用一棵树把四种消息理清楚如果只看最常用字段可以整理成下面这样BaseMessage │ ├── content # 消息主体内容 ├── additional_kwargs # 扩展数据 ├── response_metadata # 响应元数据 ├── name # 可选名称 ├── id # 消息唯一 ID ├── type # 消息类型 ├── content_blocks # 标准化内容块 │ ├── SystemMessage # 系统规则 │ ├── content # 系统提示词、角色、规则、行为约束 │ └── type system # 固定类型 │ ├── HumanMessage # 用户消息 │ ├── content # 用户输入 │ └── type human # 固定类型 │ ├── AIMessage # 模型输出 / 模型决策 │ ├── content # 模型正文 │ ├── tool_calls # 成功解析的工具调用请求 │ │ └── ToolCall │ │ ├── name # 工具名称 │ │ ├── args # 工具参数 │ │ ├── id # 工具调用 ID │ │ └── type # tool_call │ ├── invalid_tool_calls # 无效或解析失败的工具调用 │ ├── usage_metadata # 标准化 Token 使用统计 │ └── type ai # 固定类型 │ └── ToolMessage # 工具执行结果 ├── content # 返回给模型的工具结果 ├── tool_call_id # 对应 AIMessage 中的 ToolCall.id ├── artifact # 完整附加工具结果 ├── status # success / error └── type tool # 固定类型刚开始学习 Agent其实先把这棵树记住就够了。 LangChain Agent消息链路全解析
你在调试 LangChain Agent 时很容易看到这样的代码result agent.invoke({ messages: [ {role: system, content: 你是一个天气预报员}, {role: user, content: 北京天气怎么样} ] }) print(result[messages])然后打印出来的并不是一句简单的回答而是一长串SystemMessage(...) HumanMessage(...) AIMessage(...) ToolMessage(...) AIMessage(...)第一次看到这里最容易产生两个疑问为什么一次提问会返回这么多消息这些 SystemMessage、HumanMessage、ToolMessage、AIMessage 到底分别代表什么其实只要先抓住一条主线就很好理解用户输入 ↓ 模型决策 ↓ 如果需要工具发起 tool call ↓ 工具执行 ↓ 工具结果返回模型 ↓ 模型继续决策或生成最终回答LangChain 的 messages本质上就是在记录这条执行链路。先搞清楚result[messages] 是什么在当前 LangChain Agent 中Agent 会维护一个 AgentState。其中最核心的内置字段就是AgentState └── messages # 当前线程中的消息历史类型为 list[BaseMessage]也就是说result agent.invoke(...)拿到的 result 通常不是“模型的一句话回答”而是 Agent 执行结束后的状态。而result[messages]才是这次 Agent 执行过程中积累下来的消息序列。可以简单理解成result │ ├── messages # 消息历史 ├── structured_response # 如果配置了结构化输出可能存在 └── 其他自定义 State 字段所以以后看到result[messages][-1].content它的意思就是取当前消息历史里的最后一条消息。在大多数普通 Agent 场景中最后一条通常就是模型最终生成的 AIMessage。BaseMessage所有消息的共同父类SystemMessage、HumanMessage、AIMessage、ToolMessage 都继承自 BaseMessage。因此它们会共享一批基础字段。按照当前 LangChain 的消息结构可以重点理解成BaseMessage │ ├── content # 消息原始内容可以是文本也可以是内容块列表 ├── additional_kwargs # 模型供应商或扩展数据 ├── response_metadata # 响应元数据如模型名、finish_reason、headers 等 ├── name # 可选的人类可读名称 ├── id # 消息唯一 ID ├── type # 消息类型如 human / ai / tool / system ├── content_blocks # 标准化后的内容块例如文本、图片、文件、推理块等 └── text # 从消息内容中提取出的文本视图这里最需要记住的是content 是消息主体其他字段更多是在描述“这条消息是什么、从哪里来、还带了什么额外信息”。SystemMessage告诉模型“应该怎么工作”SystemMessage 主要负责给模型提供系统级规则。例如from langchain_core.messages import SystemMessage SystemMessage( content你是一个天气助手回答要简洁准确。 )它表达的是SystemMessage │ ├── content # 系统提示词、规则、角色、行为约束 ├── additional_kwargs # 扩展字段 ├── response_metadata # 响应元数据 ├── name # 可选名称 ├── id # 消息 ID └── type system # 固定类型在普通聊天模型调用中系统消息通常位于消息序列前面SystemMessage ↓ HumanMessage ↓ AIMessageHumanMessage用户输入HumanMessage 最简单。它就是用户发送给模型的消息。例如from langchain_core.messages import HumanMessage HumanMessage(content北京天气怎么样)核心字段可以理解成HumanMessage │ ├── content # 用户输入 ├── additional_kwargs # 额外扩展数据 ├── response_metadata # 响应元数据普通输入消息通常没有重要内容 ├── name # 用户或发送者名称可选 ├── id # 消息唯一 ID └── type human # 固定类型当你这样调用 Agentagent.invoke({ messages: [ {role: user, content: 北京天气怎么样} ] })LangChain 会把这种标准消息格式转换成对应的消息对象。也就是可以把它理解成{role: user, content: 北京天气怎么样} ↓ HumanMessage(content北京天气怎么样)AIMessage最重要的一种消息AIMessage 不只是“AI 回答了什么”。在 Agent 场景中它还有一个更重要的作用记录模型这一轮做出的决策。模型这一轮可能有两种典型行为。情况一直接回答比如用户问1 1 等于多少模型不需要调用工具。那么可能直接产生AIMessage └── content 2情况二模型决定调用工具比如用户问北京天气怎么样Agent 有一个天气工具。模型可能不会立刻给最终答案而是返回AIMessage │ ├── content └── tool_calls └── get_weather(city北京)所以在 Agent 里AIMessage 既可以表示最终回答也可以表示“我要调用哪个工具”的中间决策。AIMessage 里有哪些重要字段可以重点记住下面这些AIMessage │ ├── content # 模型输出正文 ├── additional_kwargs # 模型供应商原始扩展字段 ├── response_metadata # 模型名、finish_reason、响应头等 ├── name # Agent 名称可选例如 Alice / Bob ├── id # 消息唯一 ID ├── type ai # 固定类型 ├── tool_calls # 已成功解析的工具调用 ├── invalid_tool_calls # 解析失败或格式异常的工具调用 └── usage_metadata # LangChain 标准化后的 Token 使用统计这里真正和 Agent 执行关系最大的是tool_callstool_calls 里面又有什么假设模型决定调用get_weather(city北京)对应的 tool_calls 大致可以理解成[ { name: get_weather, args: { city: 北京 }, id: call_123, type: tool_call } ]字段关系是tool_calls └── ToolCall ├── name # 要调用哪个工具 ├── args # 传给工具的参数 ├── id # 这一次工具调用的唯一标识 └── type # tool_call所以AIMessage.tool_calls真正表达的是模型认为下一步应该执行哪些工具以及分别传什么参数。这一步非常关键。模型本身并没有执行工具。它只是生成了一个“工具调用请求”。真正执行工具是 Agent 框架后面的工具执行节点完成的。ToolMessage把工具执行结果重新交给模型假设模型刚刚产生AIMessage └── tool_calls └── id call_123 name get_weather args {city: 北京}Agent 框架看到这个 tool call 后就会真正执行get_weather(city北京)假设工具返回北京今天晴25°CLangChain 会把这个结果包装成ToolMessage │ ├── content 北京今天晴25°C └── tool_call_id call_123然后再交回给模型。模型看到工具结果后才继续生成最终回答。一次完整工具调用messages 是怎么变化的现在把整个流程串起来。假设用户输入北京天气怎么样Agent 有一个get_weather工具。一次典型执行过程就是HumanMessage 用户北京天气怎么样 ↓ AIMessage 模型我要调用 get_weather tool_calls [ { name: get_weather, args: {city: 北京}, id: call_123 } ] ↓ ToolMessage 工具北京今天晴25°C tool_call_id call_123 ↓ AIMessage 模型北京今天晴气温约 25°C。也就是说result[messages] 最终可能类似[ HumanMessage(...), AIMessage(tool_calls[...]), ToolMessage(...), AIMessage(...) ]这就是最典型的 Agent 消息链路。用一棵树把四种消息理清楚如果只看最常用字段可以整理成下面这样BaseMessage │ ├── content # 消息主体内容 ├── additional_kwargs # 扩展数据 ├── response_metadata # 响应元数据 ├── name # 可选名称 ├── id # 消息唯一 ID ├── type # 消息类型 ├── content_blocks # 标准化内容块 │ ├── SystemMessage # 系统规则 │ ├── content # 系统提示词、角色、规则、行为约束 │ └── type system # 固定类型 │ ├── HumanMessage # 用户消息 │ ├── content # 用户输入 │ └── type human # 固定类型 │ ├── AIMessage # 模型输出 / 模型决策 │ ├── content # 模型正文 │ ├── tool_calls # 成功解析的工具调用请求 │ │ └── ToolCall │ │ ├── name # 工具名称 │ │ ├── args # 工具参数 │ │ ├── id # 工具调用 ID │ │ └── type # tool_call │ ├── invalid_tool_calls # 无效或解析失败的工具调用 │ ├── usage_metadata # 标准化 Token 使用统计 │ └── type ai # 固定类型 │ └── ToolMessage # 工具执行结果 ├── content # 返回给模型的工具结果 ├── tool_call_id # 对应 AIMessage 中的 ToolCall.id ├── artifact # 完整附加工具结果 ├── status # success / error └── type tool # 固定类型刚开始学习 Agent其实先把这棵树记住就够了。