Model 与 Agent模块中Messages差异

type

Post

status

Published

date

Mar 18, 2026

slug

summary

Model

invoke 阻塞式

使用invoke向model输入时，只需要传入字符串即可，对于model来说，每一次输入输出都是无状态的，没有经过工程化处理，与直接使用curl ai_api类似，需要手动维护上下文

同时，也可以使用messeages列表作为对象传入

stream 流式

调用stream时需要使用迭代器获取输出的块

对于stream输出时，模型的块中有类别区别，所以可以通过指定类别输出相应的内容，如type=tool_call_chunk的块对应的是model调用的tool详情

invoke返回时是完整的Aimessage对象，而stream返回的是AimessageChunk对象

需要进行拼接，这一过程实现的就是类打字机效果

messages model写法

形式	示例	省略了什么
字典完整版	`{"role":"user","content":"hi"}`	什么都没省
消息对象	`HumanMessage("hi")`	省掉显式 `role` 字段
tuple 简写	`("user", "hi")`	省掉字典键名，只保留核心值

Agent

agent与model最大区别在于，每一次调用agent而言，都是一次状态变化，所以messages对于agent来说就是最直观的state change，所以agent返回的输出是一整个状态，包含了全部的messages，要得到最后的AImessages，需要取到最后一个message，再返回它的.content

agent的输入

invoke传入messages列表，agent输入时无法像model一样直接传入字符串，而是需要规范的message对象，标明当前message来源是谁，输入了什么，对于来源而言，有Human,Ai,system等，与model中一致

Openai总结

我把 model 和 agent 两层分别拆成“顶层 invoke 输入”和“内部 messages 写法”两张表，再补上哪些是官方推荐、哪些只是兼容写法。这样你就能直接判断哪里能省、哪里不能省。

下面这张“总表”按 LangChain v1（Python） 来看，最实用。核心区别是：

model：是“调用聊天模型”，顶层输入可以很简。str、messages 都行。

agent：是“给 agent 的 state 传一次更新”，顶层标准入口是 {"messages": ...}，不是旧式 {"input": ...}。所有 agent 的 state 默认都含有 messages。

1) model 层：支持哪些输入缩写

A. 顶层直接传字符串

这是最短写法，适合单轮、无历史。官方 Messages 和 Models 页面都直接给了这种例子。

B. 顶层传 `messages` 列表：消息对象写法

这是官方最基础、最推荐的多轮写法。角色由对象类型表达，所以你不用再手写 role。

C. 顶层传 `messages` 列表：完整字典写法

这是 OpenAI 风格格式，显式写 role 和 content。官方 Messages 页面明确支持。

D. 顶层传 `messages` 列表：tuple 简写

LangChain 的消息强制转换规则把 tuple 视为合法的 MessageLikeRepresentation。

E. `messages` 列表里直接放字符串

LangChain 的 coercion 规则还把 plain string 视为合法消息项，并会把它转换成 HumanMessage。这属于“支持的 message-like format”，但官方教学页没有把它作为主例子展示。

2) model 层怎么记“完整版 / 省略版”

你记忆里的“三种 messages 写法”，最常见就是这三个：

完整版

{"role": "user", "content": "hi"}

省略 role 的对象版

HumanMessage("hi")

进一步省略键名的 tuple 版

("user", "hi")

再加一个不属于 messages 列表本身、但经常一起记的：

顶层裸字符串

model.invoke("hi")

这四种里，前 3 种是“messages 的写法”，第 4 种是“顶层调用的简写”。

3) model 层哪些字段能省

最准确的说法是：

role 可以省：改用 HumanMessage/SystemMessage/... 对象就行。

content 不能凭空省：消息总要有内容。对象写法是把内容放在构造参数里，不是没有内容。

role 和 content 这两个键只能在“字典写法”里同时出现；如果你还想用字典，那它们就是必需字段。缺了会报错。

例如这个会报错，因为字典里缺 content：

官方错误页明确写了：message dict 必须包含 role 和 content。

4) agent 层：支持哪些输入缩写

这里和 model 最大不同：

A. 顶层标准写法：传 state update dict

官方 agent 文档明确说：调用 agent 时，是“向它的 State 传入一次更新”；所有 agent 都包含一组 messages，因此调用时传一个新消息。标准示例就是：

B. `messages` 内部可以用消息对象

官方 agent 文档直接给过 HumanMessage(...) 放进 messages 的例子。也就是说，agent 内部的消息列表 也可以走对象写法。

C. `messages` 内部可以用完整字典

这就是 agent 文档里最常见的示例。

D. `messages` 内部的 tuple / plain string

这里要分“通用规则”和“agent 文档示例”两层说：

LangChain 的通用消息 coercion 规则支持 tuple 和 plain string。

agent 文档把消息格式说明委托给 Messages 页面，并展示了对象和字典两类示例。

所以，在 agent 的 messages 列表内部，tuple / plain string 通常也符合 LangChain 的消息转换规则；但官方 agent 页面本身没有把它们当作“标准示例”来主推。 更稳妥的生产写法仍然是 消息对象 或 完整字典。

5) agent 层哪些不能像 model 那样省

这是你最关心的点。

不能把顶层直接省成裸字符串

model 可以这样写：

但 agent 的官方文档没有把裸字符串作为标准入口；官方标准入口是：

因为 agent 接收的是 state update，不是单次 prompt。

不建议再用旧式 `input` 作为主入口

LangChain v1 的 agent 文档统一展示的是 messages，不是 input。所以在 v1 语义里，主入口应理解为 state 的 messages 字段。

`role` 在 agent 里也可以不手写

前提和 model 一样：你用 HumanMessage/SystemMessage/... 对象。

所以一句话总结：

agent 里能省 role，但不能把整个顶层入口省成 model 那种裸字符串；顶层仍然应是 {"messages": ...}。

6) agent 除了 `messages` 还能传什么

agent 的 state 不只可以有 messages。官方文档给了两类扩展：

通过 middleware 扩展 state

通过 state_schema 扩展 state

示例里直接传了额外字段 user_preferences。同时，v1 里自定义 state schema 要用 TypedDict；Pydantic model 和 dataclass 不再支持。

另外，运行时依赖 不放在 state 里，而是单独走 context= 参数；官方 runtime 文档给了 context_schema 和 agent.invoke(..., context=...) 的例子。

7) 输出也别和 model 混了

model：输出通常是一条 AIMessage。

agent：输出通常是最终 state dict。如果启用了结构化输出，解析结果在 result["structured_response"]。官方示例就是这样读。

8) 最后给你一版“速记总表”

model 顶层输入

model.invoke("hi")：可以，最短。

model.invoke([...messages...])：可以。

model 的 `messages` 项

HumanMessage("hi")：可以。

{"role": "user", "content": "hi"}：可以。

("user", "hi")：可以。

"hi"：支持 coercion，会转成 HumanMessage。

agent 顶层输入

agent.invoke("hi")：不是 v1 官方标准写法。

agent.invoke({"input": "hi"})：不是 v1 官方主入口。

agent.invoke({"messages": [...]})：是标准写法。

agent 的 `messages` 项

HumanMessage("hi")：可以，官方示例有。

{"role": "user", "content": "hi"}：可以，官方示例最多。

("user", "hi") / "hi"：按 LangChain 通用消息 coercion 通常可行，但 agent 文档未把它当主示例；生产上优先对象或字典。

9) 一个最稳的实践建议

如果你想写得既短又稳，我建议统一成这两套：

model：

agent：

这样：

不用手写 role

不踩字典字段错误

又完全贴近 v1 官方写法。