模块 1模型原理与 Agent 基础
模型 API 与事件流
先定义内部请求模型
指令与输入
- 角色/优先级或 Item 模型
- 文本、图像、文件等内容块
- 动态上下文的来源标记
执行选项
- 模型与推理参数
- 工具清单与选择策略
- 结构化输出约束
- 追踪和幂等元数据
响应是带状态的 Item 集合
- 文本只是可能的输出项之一
- Tool Call、Reasoning、引用和 Artifact 需要独立类型
- Usage、完成原因和不完整状态必须保留
- 未知事件应可前向兼容而不是静默丢弃
用状态机消费流式事件
事件类别
响应生命周期
- created、in-progress 与 completed
- failed、cancelled 与 incomplete
Item 生命周期
- Item 创建、更新与完成
- 文本、引用和 Artifact 内容 Delta
Tool 事件
- 调用参数增量与参数完成
- 执行结果按 Call ID 关联
终止事件
- 错误、取消与连接中断
- 只允许一个最终终态
客户端 Reducer
- 按响应和 Item ID 关联
- 处理顺序、重复和晚到事件
- 部分结果与最终结果分离
终态必须唯一
- completed
- failed
- cancelled
- incomplete
Tool Call 的完整往返
- 模型产生调用 ID、工具名和参数
- 参数完成后再执行 Schema 与策略校验
- 执行结果或结构化错误按调用 ID 回注
- 并行调用必须保持关联和独立状态
- 大结果、二进制和敏感字段不能直接无界回注
明确谁拥有对话状态
客户端重放
- 可移植但窗口和并发由应用负责
Provider Conversation
- 减少重放但引入锁定、生命周期和数据边界
应用 Session Store
- 承接业务状态、权限、摘要和审计
- 重试、分支和多端并发需要版本或冲突策略
错误要按恢复语义归一化
响应开始前
- 鉴权与参数错误
- 限流和容量
- 安全重试与退避
流中断
- 部分输出是否可展示
- 是否能续传
- 避免重复执行 Tool
协议成功但行为失败
- 拒答
- 结构不合法
- 工具选择错误
- 无法通过传输重试解决
统一公共语义，保留厂商差异
适合统一
- 基础消息与内容块
- 函数工具
- 生命周期与错误类别
- Usage 和 Trace 关联
必须保留 Escape Hatch
- 内置工具
- Reasoning 与缓存控制
- 厂商特有事件
- 能力探测和版本差异
适配器验收
- 录制事件序列
- 乱序/截断/未知事件
- 重复 Tool Call
- 升级回归