cursor-byok/docs/协议消息参考.md

Agent Bidi / RunSSE 协议消息参考

本文描述 Agent Bidi / RunSSE 链路中的消息功能、字段语义和消息之间的关联关系。

本文是协议参考，不描述服务端或客户端的内部实现。字段定义以当前 internal/backend/cursor/proto/agent_v1.proto 和 internal/backend/cursor/proto/aiserver_v1.proto 为准。

范围包括 BidiAppend / RunSSE 传输封装、AgentClientMessage 的全部顶层分支、AgentServerMessage 的全部顶层分支，以及这些分支直接关联的主要请求、响应和控制消息。工具专属的 Args / Result 类型按功能归类，不展开为具体执行流程。

1. 协议概览

该协议将一次 Agent 通信拆成两条方向相反的通道：

• BidiAppend：客户端向服务端追加消息。
• RunSSE：服务端持续向客户端返回消息。

两条通道通过同一个 request_id 关联。

客户端                                      服务端
  |                                           |
  | BidiAppend(request_id, append_seqno, data)|
  |------------------------------------------>|
  |                                           |
  | RunSSE(request_id)                        |
  |------------------------------------------>|
  |                                           |
  |       stream AgentServerMessage           |
  |<------------------------------------------|

1.1 主要关联标识

标识	范围	功能
conversation_id	会话	标识一个可持续多轮的 Agent 会话。
request_id	请求流	关联 BidiAppend、RunSSE 和一次活跃请求。
run_id	运行	独立标识一次 Agent Run；不得假定它与 request_id 等值。
message_id	用户消息	标识一条用户输入。
model_call_id	模型调用	标识一次具体的模型调用或 provider pass。
call_id / tool_call_id	工具调用	标识模型发起的一次工具调用。
id	桥接消息	关联 Exec、Interaction 或 KV 的请求和响应。
exec_id	客户端执行	标识一次客户端执行任务，可跨多个流式消息。
append_seqno	Bidi 请求流	表示同一 request_id 下客户端上行消息的顺序。

1.2 Connect 流式帧封装

RunSSE 中的每条消息都位于 Connect 流式帧中。帧由固定 5 字节帧头和消息载荷组成：

部分	长度	功能
flags	1 字节	描述压缩和流结束状态。
length	4 字节	使用大端序表示后续载荷的字节数，不包含 5 字节帧头。
payload	length 字节	普通帧中是 protobuf 消息；流结束帧中是结束状态。

flags 属于 Connect 传输层，不是 AgentServerMessage 或其他 protobuf 消息的字段。当前使用的标志位为：

标志	含义
0x00	普通、未压缩的数据帧。
0x01	压缩的数据帧，载荷需要按照流声明的压缩算法解压后再解析。
0x02	流结束帧，载荷表示 EndStream 状态，不应按业务 protobuf 消息解析。

这些值按 bit 表达：最低位 0x01 表示压缩，次低位 0x02 表示流结束，其余 bit 为保留位。因此，判断帧类型时应读取标志位，而不是把 flags 当作 protobuf 枚举。

例如下面的 RunSSE 帧：

{
  "kind": "interaction_update",
  "messageType": "agent.v1.AgentServerMessage",
  "flags": "0x00",
  "length": 4,
  "compressed": false,
  "endStream": false,
  "message": {
    "interaction_update": {
      "heartbeat": {}
    }
  }
}

它表示载荷是一个长度为 4 字节、未压缩且尚未结束流的 AgentServerMessage。heartbeat 消息很小，使用 0x00 是正常情况；较大的业务消息可能使用 0x01。

2. BidiAppend 传输消息

2.1 BidiAppendRequest

功能：向指定请求流追加一条客户端消息。

字段	类型	功能
data	string	十六进制编码的 AgentClientMessage protobuf 数据。
request_id	BidiRequestId	指定消息所属的请求流。
append_seqno	int64	指定消息在当前请求流中的追加顺序。
data_binary	bytes	二进制形式的消息载荷。

约束：

• data 与 data_binary 表达的是消息载荷，不应同时承载语义不同的消息。
• append_seqno 只在同一个 request_id 内比较。
• 解码后的根消息必须是 AgentClientMessage。

2.2 BidiAppendResponse

功能：确认本次 append 请求已经被接收。

该消息没有业务字段。它只确认 unary 请求本身，不代表 Agent Run 已经完成。

2.3 BidiRequestId

字段	类型	功能
request_id	string	标识 BidiAppend 与 RunSSE 共享的请求流。

3. 客户端上行根消息

3.1 AgentClientMessage

功能：封装一条客户端到服务端的 Agent 消息。

message 是 oneof，一条消息只能选择以下一个分支：

分支	消息类型	功能
run_request	AgentRunRequest	启动或恢复一次 Agent Run。
exec_client_message	ExecClientMessage	返回客户端工具执行的数据或结果。
kv_client_message	KvClientMessage	返回 blob 读取或写入结果。
conversation_action	ConversationAction	追加会话动作，例如继续、取消或执行计划。
exec_client_control_message	ExecClientControlMessage	返回客户端执行通道的控制事件。
interaction_response	InteractionResponse	回答服务端发起的用户交互请求。
client_heartbeat	ClientHeartbeat	表示客户端连接仍然活跃。
prewarm_request	PrewarmRequest	提前准备会话、模型和上下文。

4. AgentRunRequest

功能：携带启动或恢复 Agent Run 所需的会话状态、动作、模型与能力信息。

4.1 核心字段

字段	类型	功能
conversation_state	ConversationStateStructure	客户端掌握的会话 checkpoint。
action	ConversationAction	本次 Run 要执行的会话动作。
model_details	ModelDetails	旧式或展示用途的模型信息。
requested_model	RequestedModel	本次实际请求的模型、参数和凭据。
conversation_id	string?	本次 Run 所属会话。
run_id	string?	客户端分配的 Run 标识。

4.2 工具和上下文字段

字段	类型	功能
mcp_tools	McpTools	本次 Run 可用的 MCP 工具定义。
mcp_file_system_options	McpFileSystemOptions?	MCP 文件系统能力和描述符。
skill_options	SkillOptions?	可用技能及技能加载选项。
custom_system_prompt	string?	调用方提供的自定义系统提示。
exclude_workspace_context	bool?	是否排除工作区上下文。
pre_fetched_blobs	PreFetchedBlob[]	调用前已经取得的 blob 内容。

4.3 模式和子 Agent 字段

字段	类型	功能
subagent_type_name	string?	当前 Run 使用的子 Agent 类型。
selected_subagent_models	RequestedModel[]	为子 Agent 选择的模型。
selected_subagent_model_details	ModelDetails[]	子 Agent 模型的展示信息。
subagent_model_overrides	SubagentModelOverride[]	按子 Agent 类型覆盖模型选择。
can_create_cloud_subagents	bool?	客户端是否允许创建云端子 Agent。
suppress_subagent_progress_update_tool	bool?	是否隐藏子 Agent 进度更新工具。
conversation_group_id	string?	将多个相关会话归入同一组。

4.4 客户端能力字段

字段	类型	功能
suggest_next_prompt	bool?	是否请求生成下一条提示建议。
harness	string?	标识调用方所使用的 Agent harness。
dev_raw_model_slug	string?	开发模式下使用的原始模型标识。
client_supports_inline_images	bool?	客户端是否支持内联图片。
client_supports_send_to_user	bool?	客户端是否支持 send-to-user 能力。
computer_use_coordinate_mode	string?	Computer Use 坐标系模式。

5. PrewarmRequest

功能：提前提供模型、会话状态和能力声明，使后续正式 Run 可以复用已经准备好的上下文。

其主要字段与 AgentRunRequest 相同，但没有直接携带 ConversationAction：

字段组	字段
模型	model_details、requested_model
会话	conversation_id、conversation_state、conversation_group_id
工具	mcp_tools、mcp_file_system_options
Prompt	custom_system_prompt、exclude_workspace_context
子 Agent	subagent_type_name、selected_subagent_models、selected_subagent_model_details、subagent_model_overrides
客户端能力	suggest_next_prompt、client_supports_inline_images、client_supports_send_to_user、computer_use_coordinate_mode
预取	pre_fetched_blobs
候选选择	best_of_n_group_id、try_use_best_of_n_promotion

6. 模型选择消息

6.1 RequestedModel

功能：描述调用方实际希望使用的模型和运行参数。

字段	类型	功能
model_id	string	Provider 模型标识。
max_mode	bool	是否启用该模型的 max 模式。
parameters	ModelParameterValue[]	额外模型参数，每项包含字符串 id 和 value。
built_in_model	bool	是否为内建模型。
is_variant_string_representation	bool	model_id 是否表示模型变体字符串。
credentials	oneof	api_key_credentials、azure_credentials 或 bedrock_credentials。

6.2 ModelDetails

功能：提供模型展示信息、别名、思考能力和凭据。

字段	类型	功能
model_id	string	模型标识。
display_model_id	string	面向 UI 的模型标识。
display_name	string	完整展示名称。
display_name_short	string	短展示名称。
aliases	string[]	可识别的模型别名。
thinking_details	ThinkingDetails?	模型思考能力声明。
max_mode	bool?	是否启用 max 模式。
credentials	oneof	API Key、Azure 或 Bedrock 凭据。

凭据字段属于敏感信息，不应写入普通日志、错误消息或会话记录。

7. ConversationAction

功能：描述一次会话级动作。action 是 oneof。

7.1 公共字段

字段	类型	功能
triggering_auth_id	string?	触发动作的认证主体。
triggering_user_info	TriggeringUserInfo?	触发用户的信息。
request_context_parts	RequestContextPartReferences?	通过 blob 引用传递的大型上下文部分。

7.2 动作分支

分支	主要参数	功能
user_message_action	user_message、request_context、prepend_user_messages、conversation_history	提交新用户消息并开始或继续会话。
resume_action	request_context	从已有 checkpoint 或等待点继续会话。
cancel_action	reason、interrupted_pending_tool_call_resolutions	取消当前 Run，并可携带未完成工具的解决结果。
summarize_action	无字段	请求生成或刷新会话摘要。
shell_command_action	shell_command、exec_id	将一次显式 Shell 命令写入会话。
start_plan_action	user_message、request_context、is_spec	进入计划编制流程。
execute_plan_action	request_context、plan、计划文件字段、execution_mode、plan_id	执行已有计划。
async_ask_question_completion_action	original_tool_call_id、original_args、result	回填异步 AskQuestion 的结果。
cancel_subagent_action	subagent_id	取消指定子 Agent。
background_task_completion_action	completions[]	上报后台 Shell 或子 Agent 的进度和终态。
background_shell_action	tool_call_id	将指定 Shell 工具调用切换到后台语义。
background_subagent_action	tool_call_id	将指定子 Agent 工具调用切换到后台语义。
subscription_notification_action	notifications[]、request_context	将订阅系统产生的消息注入会话。
goal_continuation_action	无字段	继续当前长期目标。
inject_context_action	injection_id、expected_run_id、user_context/system_context	向仍在运行的 Run 注入上下文。

8. UserMessage

功能：描述用户输入及其选择的上下文和运行模式。

字段组	字段	功能
内容	text、rich_text、text_blob_id、rich_text_blob_id	用户输入的纯文本、富文本或 blob 引用。
身份	message_id、thread_id、prompt_reference_id	消息、线程和提示引用标识。
上下文	selected_context、conversation_state_blob_id	用户选择的文件、代码或会话状态。
模式	mode、custom_mode_intent	Agent、Ask、Plan、Debug、Multitask 或自定义模式。
计划	execute_plan_info	当前消息关联的计划。
子 Agent	subagent_system_reminder、project_details	子 Agent 或项目相关信息。
模拟消息	is_simulated_msg、simulated_msg_reason、simulated_message_metadata	标记系统代用户生成的输入。
Hook	hook_additional_contexts	Hook 产生的附加上下文。

9. RequestContext

功能：描述本次请求可见的工作区、规则、工具和运行环境。

字段较多，按语义分组如下：

字段组	代表字段	功能
环境	env	OS、Shell、工作区路径、时区、终端目录、sandbox 与 Computer Use 能力。
规则	rules、non_file_rules、cloud_rule、disabled_team_rules	本次请求适用的规则集合。
仓库	repository_info、git_repos、project_layouts、完整性标记	仓库索引、Git 和项目布局。
MCP	tools、mcp_instructions、mcp_file_system_options、mcp_meta_tool_options	MCP 工具与文件系统能力。
技能	skill_options、agent_skills	可用技能和技能内容。
子 Agent	custom_subagents	自定义子 Agent 声明。
文件	file_contents	已预取的路径到文件内容映射。
Web	web_search_enabled、web_fetch_enabled	Web Search 和 Web Fetch 能力开关。
Hook	hooks_additional_context、hooks_config	Hook 配置和附加上下文。
权限	user_permissions_auto_run、project_permissions_auto_run、admin_permissions_auto_run、admin_command_denylist	自动执行许可和禁止命令。
功能能力	supports_mcp_auth、read_lints_enabled、search_conversations_enabled、send_message_enabled	客户端可提供的附加能力。

大型上下文也可以通过 RequestContextPartReferences 传递。该结构为 rules、skills、subagents 和 MCP 分别携带 blob_id 与字节长度，并用 dynamic_context 继续携带小型动态字段。

10. ExecClientMessage

功能：返回 ExecServerMessage 所请求的客户端执行数据或结果。

10.1 公共字段

字段	类型	功能
id	uint32	与对应 ExecServerMessage.id 相同。
exec_id	string	与对应 ExecServerMessage.exec_id 相同。
local_execution_time_ms	int32?	客户端本地执行耗时。
hook_additional_contexts	HookAdditionalContext[]	执行 Hook 返回的附加上下文。
message	oneof	工具特定的结果或流式事件。

10.2 主要结果分支

分类	分支	功能
文件	read_result、redacted_read_result	返回文件读取结果。
文件	write_result、delete_result	返回文件写入或删除结果。
搜索	grep_result、ls_result	返回文本搜索、Glob 或目录列表结果。
诊断	diagnostics_result、canvas_diagnostics_result	返回代码或 Canvas 诊断结果。
Shell	shell_result、shell_stream	返回一次性 Shell 结果或流式 Shell 事件。
Shell	background_shell_spawn_result、write_shell_stdin_result、force_background_shell_result	返回后台 Shell 创建、输入和后台切换结果。
上下文	request_context_result	返回动态构建的 RequestContext。
MCP	mcp_result、list_mcp_resources_exec_result、read_mcp_resource_exec_result、mcp_state_exec_result	返回 MCP 调用和资源操作结果。
Hook	execute_hook_result	返回 Hook 执行结果。
子 Agent	subagent_result、force_background_subagent_result、subagent_await_result	返回子 Agent 运行、后台切换和等待结果。
Web/Computer	fetch_result、record_screen_result、computer_use_result	返回网页、录屏或 Computer Use 结果。
权限预检	shell_allowlist_precheck_result、mcp_allowlist_precheck_result、web_fetch_allowlist_precheck_result	返回 allowlist 检查结果。
Git	git_diff_response	返回 Git diff。
Pi 工具	pi_read_result、pi_bash_result、pi_edit_result、pi_write_result、pi_grep_result、pi_find_result、pi_ls_result	返回 Pi 工具族的执行结果。
其他	smart_mode_classifier_result、conversation_search_result、agent_store_conflict_result	返回模式分类、会话搜索或 Agent Store 冲突处理结果。

对于 shell_stream，其内部 event 也是 oneof，常见事件包括：

• start：进程已经启动。
• stdout：标准输出增量。
• stderr：标准错误增量。
• exit：进程已经退出。
• rejected：执行请求被拒绝。
• permission_denied：缺少执行权限。
• backgrounded：进程已经转入后台。

11. ExecClientControlMessage

功能：描述客户端执行通道本身的状态，不承载正常工具结果。

message 是 oneof：

分支	参数	功能
stream_close	id	表示指定 Exec 数据流已经关闭。
throw	id、error、stack_trace?、error_code?	表示客户端执行通道异常终止。
heartbeat	id	表示指定 Exec 仍然存活。

12. InteractionResponse

功能：返回客户端或用户对 InteractionQuery 的响应。

字段	类型	功能
id	uint32	与对应 InteractionQuery.id 相同。
result	oneof	交互类型对应的响应。

当前主要响应分支：

分支	主要内容	功能
ask_question_interaction_response	AskQuestionResult	返回问题答案、拒绝、错误或异步状态。
create_plan_request_response	CreatePlanResult	返回计划 URI以及成功或错误。
web_search_request_response	approved/rejected	批准或拒绝 Web Search。
web_fetch_request_response	approved/rejected	批准或拒绝 Web Fetch。
switch_mode_request_response	approved/rejected	批准或拒绝模式切换。

协议还定义 VM 环境、PR 管理、MCP Auth、图片生成、环境替换和 SCM 连接等响应分支。

13. KvClientMessage

功能：返回 KvServerMessage 发起的 blob 操作结果。

字段	类型	功能
id	uint32	与对应 KvServerMessage.id 相同。
get_blob_result	GetBlobResult	返回 blob_data 或 error。
set_blob_result	SetBlobResult	返回可选的写入错误；无错误表示写入成功。

14. ClientHeartbeat

功能：表示客户端 Agent 通道仍然存活。

该消息没有业务字段，也不与 ExecClientHeartbeat 混用：

• ClientHeartbeat 面向整个 Agent 请求通道。
• ExecClientHeartbeat 面向某个具体 ExecServerMessage.id。

15. RunSSE 请求与服务端根消息

15.1 RunSSE 请求

RunSSE 请求体是 BidiRequestId，只包含：

字段	类型	功能
request_id	string	订阅指定请求流的服务端消息。

15.2 AgentServerMessage

功能：封装一条服务端到客户端的 Agent 消息。

字段	类型	功能
ttft_breakdown	TtftBreakdown	可选的首 token 延迟分解。
message	oneof	本条消息的业务载荷。

message 可以选择以下一个分支：

分支	消息类型	功能
interaction_update	InteractionUpdate	返回文本、思考、工具和 turn 生命周期更新。
exec_server_message	ExecServerMessage	请求客户端执行本地工具。
exec_server_control_message	ExecServerControlMessage	控制已经发出的客户端执行。
conversation_checkpoint_update	ConversationStateStructure	更新客户端持有的会话 checkpoint。
kv_server_message	KvServerMessage	请求客户端读取或写入 blob。
interaction_query	InteractionQuery	请求用户或客户端作出交互决策。

16. InteractionUpdate

功能：承载模型输出和一次 turn 中的增量状态。

message 是 oneof。当前主要消息如下。

16.1 文本和思考

分支	参数	功能
text_delta	text、is_server_notice	返回可展示文本增量。
thinking_delta	text、thinking_style?	返回思考文本增量及展示样式。
thinking_completed	thinking_duration_ms	表示思考阶段结束。

16.2 工具调用

分支	参数	功能
tool_call_started	call_id、tool_call、model_call_id	宣布工具调用已经建立。
partial_tool_call	call_id、tool_call、args_text_delta、model_call_id	在参数尚未完整时返回部分 ToolCall。
tool_call_delta	call_id、tool_call_delta、model_call_id	返回 Shell、Task、Edit 或环境替换的增量。
tool_call_completed	call_id、tool_call、model_call_id	表示工具调用已经得到终态结果。
shell_output_delta	stdout/stderr/start/exit	返回 Shell 进程输出和生命周期增量。

同一次工具调用的这些消息必须使用相同的 call_id；同一次模型调用产生的工具事件应使用相同的 model_call_id。

16.3 摘要和结束

分支	参数	功能
summary_started	无字段	表示摘要阶段开始。
summary	summary	返回摘要文本。
summary_completed	hook_message?	表示摘要阶段完成，并可携带后续 Hook 信息。
turn_ended	token 统计字段	表示当前 turn 正常结束。

turn_ended 的 token 字段包括：

• input_tokens
• output_tokens
• cache_read_tokens
• cache_write_tokens
• reasoning_tokens

16.4 保活

分支	参数	功能
heartbeat	无字段	保持 RunSSE 活跃，不表示业务状态变化。

协议还定义 user_message_appended、token_delta、step 生命周期、prompt suggestion、branch change、feedback、response comparison 和 context injection state 等更新。

17. ExecServerMessage

功能：要求客户端执行一项本地能力。

17.1 公共字段

字段	类型	功能
id	uint32	执行桥消息编号，客户端回包必须原样携带。
exec_id	string	执行任务标识，流式消息应保持一致。
span_context	SpanContext?	可选的分布式追踪上下文。
accept_hook_additional_contexts	bool?	是否接受客户端在结果中返回 Hook 附加上下文。
message	oneof	工具特定的执行参数。

17.2 主要执行分支

分类	分支	功能
文件	read_args、write_args、delete_args	读取、写入或删除文件。
搜索	grep_args、ls_args	搜索文本、匹配路径或列出目录。
诊断	diagnostics_args	获取编辑器或项目诊断。
Shell	shell_stream_args	启动流式 Shell 命令。
Shell	write_shell_stdin_args、force_background_shell_args	向 Shell 写入输入或切换后台执行。
MCP	mcp_args、list_mcp_resources_exec_args、read_mcp_resource_exec_args	调用 MCP 工具或读取 MCP 资源。
Hook	execute_hook_args	请求客户端执行 Agent Hook。
子 Agent	subagent_args	请求客户端启动子 Agent。

协议还定义普通 Shell、后台 Shell 创建、RequestContext、Fetch、Computer Use、allowlist 预检、Git diff、Pi 工具、会话搜索和 Agent Store 冲突等执行分支。

17.3 回包规则

客户端返回 ExecClientMessage 或 ExecClientControlMessage 时：

• id 必须与请求一致。
• 如果存在 exec_id，应与请求一致。
• 流式执行可以返回多条数据消息。
• 最终结果、throw 或明确终态用于结束本次执行关联。

18. ExecServerControlMessage

功能：控制此前已经发出的 Exec 请求。

当前协议分支：

分支	参数	功能
abort	id	请求客户端终止对应的 Exec。

abort.id 对应 ExecServerMessage.id，不是 tool_call_id。

19. InteractionQuery

功能：请求用户或客户端完成不能由模型单独决定的交互。

19.1 公共字段

字段	类型	功能
id	uint32	交互编号，响应必须原样携带。
query	oneof	具体交互内容。

19.2 主要查询分支

分支	主要参数	功能
ask_question_interaction_query	args、tool_call_id	向用户展示一个或多个问题。
create_plan_request_query	args、tool_call_id	请求客户端创建或保存计划。
web_search_request_query	args	请求批准 Web Search。
web_fetch_request_query	args、skip_approval、smart_mode_approval	请求批准或执行 Web Fetch。
switch_mode_request_query	args.target_mode_id、explanation?、tool_call_id	请求切换 Agent 模式。

协议还定义 VM 环境、PR 管理、MCP Auth、图片生成、环境替换和 SCM 连接查询。

19.3 响应规则

客户端必须用 InteractionResponse 返回结果：

• InteractionResponse.id 与查询 id 相同。
• result 分支必须与原查询类型匹配。
• 批准/拒绝型响应应明确选择对应的 oneof 分支，不能用空消息代替拒绝。

20. KvServerMessage

功能：请求客户端提供或保存较大的二进制数据。

字段	类型	功能
id	uint32	KV 操作编号。
span_context	SpanContext?	可选追踪上下文。
get_blob_args	GetBlobArgs	按 blob_id 读取数据。
set_blob_args	SetBlobArgs	按 blob_id 保存 blob_data。

客户端使用相同 id 返回 KvClientMessage。

Blob 字段是原始 bytes。协议使用 blob_id 引用它们，以避免在主要会话消息中重复传输大型上下文。

21. ConversationStateStructure

功能：表示可跨请求传递的会话 checkpoint。

该结构既可以由客户端随 AgentRunRequest 上传，也可以由服务端通过 conversation_checkpoint_update 返回。

字段组	代表字段	功能
Prompt	root_prompt_messages_json	根 Prompt 消息，元素以 bytes 保存。
Turn	turns、turn_timings	历史 turn 和耗时。
工具	pending_tool_calls	尚未解决的工具调用。
状态	todos、plan、plans	Todo 和计划状态。
Token	token_details	已用 token、最大 token 和上下文分解。
摘要	summary、summary_archive、summary_archives、self_summary_count	当前摘要和历史摘要。
文件	file_states、file_states_v2、read_paths	会话涉及的文件状态。
工作区	previous_workspace_uris、tracked_git_repo_branches、active_branch_name	工作区和 Git 状态。
模式	mode、agent_type	当前 Agent 模式和类型。
子 Agent	subagent_states、subagent_threads、subagent_runs_by_parent_tool_call_id、subagent_state_refs	子 Agent checkpoint。
通信进度	communicate_update_*	长任务进度和最终摘要。
会话时间	conversation_started_timestamp_ms、conversation_started_time_zone	会话开始时间。
Goal	goal_state	长期目标状态。

注意：多个字段使用 bytes，其内部内容通常仍是另一种 protobuf 或 JSON 编码。消费者必须依据字段定义解码，不能把所有 bytes 都当作 UTF-8 文本。

22. 消息配对关系

22.1 Run

AgentClientMessage.run_request
  -> AgentServerMessage.interaction_update (...多条)
  -> AgentServerMessage.conversation_checkpoint_update
  -> AgentServerMessage.interaction_update.turn_ended
  -> stream end

22.2 Exec

AgentServerMessage.exec_server_message(id, exec_id)
  -> AgentClientMessage.exec_client_message(id, exec_id) (...可多条)
  -> AgentClientMessage.exec_client_control_message(id)   (...可选)

22.3 Interaction

AgentServerMessage.interaction_query(id, query)
  -> AgentClientMessage.interaction_response(id, matching_result)

22.4 KV

AgentServerMessage.kv_server_message(id, get/set)
  -> AgentClientMessage.kv_client_message(id, matching_result)

23. oneof 与可选字段规则

• 同一个 oneof 在一条 protobuf 消息中只能设置一个分支。
• 未设置 optional 字段和设置为默认值在业务语义上可能不同，消费者需要保留 presence 信息。
• 未识别的 protobuf 字段应按 protobuf 兼容规则保留或忽略，不应导致整条消息无法解析。
• 请求与响应的类型必须匹配，不能只依赖相同的 id。
• request_id、conversation_id、model_call_id、tool_call_id、exec_id 和桥接 id 属于不同命名空间，不应互相替代。
• 增量消息只表达追加内容；接收方不应把 delta 当作完整快照覆盖已有内容。
• checkpoint 表达完整状态视图；同类的新 checkpoint 可以替代旧 checkpoint。

24. 错误与终止语义

协议需要区分三类结束：

1. 正常业务结束
   • 典型信号是 InteractionUpdate.turn_ended，随后流结束。
2. 用户或系统取消
   • 可能先出现 Exec abort，随后 RunSSE 以 canceled 状态结束。
3. 协议、provider 或服务错误
   • 可以通过 Connect end-stream error 返回，不一定存在对应的 AgentServerMessage.oneof 分支。

因此，客户端不能仅凭“流关闭”判断正常完成；还需要结合最后一条业务消息和流终止状态。