智能体运行时契约

智能体运行时契约，是 CLI、模型适配器、循环、工具、存储和渲染器共同遵守的数据类型与生命周期规则。它让各模块围绕同一套消息和事件协作，而不直接依赖彼此的实现。

叶子包模式

共享契约适合放在依赖图底部：上层模块都可以引用它，但契约层不反向引用具体工具、压缩引擎或供应商实现。

契约	典型内容	作用
消息	用户、助手、工具结果、压缩检查点	保存会话状态并驱动循环
内容块	文本、思考、工具调用、图片	表达结构化和多模态输出
事件	Agent、回合、消息、工具、压缩生命周期	支持流式展示、日志和插件
工具	名称、描述、Schema、执行模式、执行函数	统一内置和外部工具调用面
Hooks	prepare、before、after、steering、stop	提供受控策略插入点

失败也属于数据

可恢复的运行时失败不一定要抛出为语言级异常。工具失败可以变成带错误标记的工具结果，供应商失败可以进入助手消息的停止原因，压缩失败也可以通过生命周期事件记录。这样模型仍能获得可修复反馈，观察者也能看到完整的开始和结束事件。

设计原则

• 使用明确的类型判别字段，未知变体立即失败。
• 静态会话状态与动态生命周期事件分开。
• 工具调用、结果、请求和响应之间保留稳定关联 ID。
• 增量事件和最终结果使用不同语义。
• 只把不可安全表示的传输故障或不变量破坏升级为异常。

这些契约是智能体 Harness 工程、工具执行流水线和智能体循环工程之间的共同语言。