消息·事件·格式化Messages, events & formatting · 单元Unit 04
消息与事件：系统内唯一的数据契约Messages and events: the single data contract
掌握 Msg、内容块、角色和流式事件。学完本单元，你能排查消息丢失、顺序错乱、工具结果无法回填和前端重复渲染。Master Msg, content blocks, roles and streaming events. After this unit you can debug lost messages, ordering issues, unlinked tool results and duplicated UI rendering.
学习目标Learning goals
- 正确构造 system/user/assistant/tool 四类消息Construct system/user/assistant/tool messages correctly
- 理解工具调用块与工具结果块的关联方式Understand how tool-call and tool-result blocks correlate
- 消费流式事件并合并增量与最终消息Consume streaming events and merge deltas with the final message
概念闪卡Concept cards
点击卡片翻面查看解释。Click a card to flip it and reveal the explanation.
关键 APIKey APIs
点击进入对应的 Python 或 Java 参考页。Open the exact Python or Java reference for each type.
问题巩固Check yourself
完成 10 道题；答错会自动进入错题本。Answer all ten questions. Wrong answers are added to your wrong-answer book automatically.
01AgentScope 支持哪四种消息角色？Which four message roles does AgentScope support?
解析Why 角色集合保持最小化，多智能体角色通过 name 与元数据表达，而不是新增角色类型。The role set is minimal; multi-agent roles are expressed through name and metadata rather than new role types.
02Python 中表示一次工具调用的内容块是？Which Python content block represents a tool call?
解析Why ToolCallBlock 包含调用 id、工具名和参数，模型通过它请求工具执行。ToolCallBlock contains the call id, tool name and arguments requested by the model.
03Python 中表示工具执行结果的内容块是？Which Python content block represents a tool result?
解析Why ToolResultBlock 必须带上对应的 tool call id 和工具名，否则模型无法关联。ToolResultBlock must carry the matching tool-call id and tool name, or the model cannot correlate it.
04Python 中所有事件的基类是？What is the base class for Python events?
解析Why EventBase 定义事件类型、来源等公共字段，具体事件在其上扩展。EventBase defines common fields such as event type and source; concrete events extend it.
05文本流式增量对应哪个事件？Which event carries a streaming text delta?
解析Why Start/Delta/End 成对出现，Delta 携带增量内容，End 表示该块结束。Start/Delta/End come as a triplet; Delta carries the increment and End closes the block.
06Java 中统一消息类型是？What is the unified Java message type?
解析Why Java 的 Msg 提供 builder、角色、内容块、元数据、用量和结构化数据访问。Java's Msg offers a builder, role, content blocks, metadata, usage and structured-data access.
07Java 中表示工具调用的内容块是？Which Java content block represents a tool call?
解析Why Java 使用 ToolUseBlock，对应 Python 的 ToolCallBlock。Java uses ToolUseBlock, the counterpart of Python's ToolCallBlock.
08从 Python Msg 中提取纯文本应调用？How do you extract plain text from a Python Msg?
解析Why get_text_content 拼接文本块；需要遍历所有块时用 get_content_blocks。get_text_content joins text blocks; use get_content_blocks when you need every block type.
09Java 中所有内容块的基类是？What is the base class for Java content blocks?
解析Why TextBlock、ThinkingBlock、ToolUseBlock、ToolResultBlock 等都实现 ContentBlock。TextBlock, ThinkingBlock, ToolUseBlock and ToolResultBlock all implement ContentBlock.
10工具结果依靠什么与模型发起的调用关联？What links a tool result to the model's tool call?
解析Why 缺少或复用错误的 id 会导致模型报错或把结果当上下文噪声。A missing or mismatched id causes model errors or treats the result as context noise.