设计思想
Covonaut 提供构建 Agent 应用的基础组件，而不代替你托管服务。如何管理模型凭据、保存数据、检查权限、部署服务和呈现界面，都由应用决定。
将推理与执行分离
模型决定要调用什么工具，Go 函数负责执行。JSON Schema 描述工具接受的参数，但不能判断用户是否有权限，也不能保证操作安全。这些检查需要写在工具或应用代码中，不能只靠提示词约束。
这样可以在更换模型服务时保留工具实现，也可以把文件、Shell、浏览器等操作放到沙箱或其他受控环境中执行。
按流程选择合适的抽象
如果下一步要做什么取决于模型回答，就使用 Agent。如果处理阶段和分支已经确定，工作流通常更合适。如果步骤之间有复杂依赖，或者需要反复更新状态，可以用图来描述。
这些方式可以一起使用。验证、数据库访问、文件处理等步骤也可以直接调用 Go 函数，不必都交给模型。
| 场景 | 建议入口 |
|---|---|
| 让模型回答问题，必要时调用工具 | agentcore.Agent |
| 应用直接调用工具 | Agent.InvokeTool |
| 固定阶段、并行或路由 | workflow |
| 无环依赖或共享状态迭代 | graph |
| 职责不同的专业 Agent | Agent handoff |
| 远程托管的专业 Agent | A2A |
让各组件各司其职
Provider 负责与模型服务通信，Tool 将工具定义和执行函数关联起来，Extension 将一组相关能力接入 Agent。Runnable[I, O] 为普通调用和流式处理提供统一接口。存储、链路追踪和指标也通过接口接入，具体实现可以由应用选择。
协议适配器同样各有用途：MCP 连接外部工具，A2A 连接远程 Agent，AG-UI 传输执行事件，A2UI 描述界面结构。终端界面只需接收事件并展示结果，不必参与模型的推理过程。
将历史视为应用状态
会话历史不仅是聊天窗口里的文字。工具调用与结果的对应关系、图片等内容块、压缩摘要和会话分支都会影响后续请求，因此不能简单地把文字拼接后保存。
如果只需要按 ID 保存和读取 Agent 状态，可以使用快照。如果需要保留每条记录、创建分支并追踪条目 ID，可以使用会话树。检查点则用于恢复执行状态，与重新显示旧消息不是一回事。
看清运行中发生了什么
重试、模型切换、工具错误和上下文压缩都可能影响用户看到的结果。例如，一次流式请求失败后，界面需要根据重置事件撤回已经显示的部分内容。应用也需要限制重试次数，避免重复写入、付款等操作。
事件用于实时更新界面，链路和指标用于诊断与运维。它们都不能代替权限检查或持久化存储。
以接口文档为准
示例说明如何组合各组件，准确的签名和类型以 Go 文档为准。本站对应 main 分支，使用固定版本时应查询相应 API。即使适配器提供统一接口，不同模型支持的功能也可能不同。