Agent 保存会话运行状态,驱动单次回合循环。它管理当前逻辑路由、已解析运行时路由、历史快照 RuntimeSnapshot、前言、工具注册表、权限会话,以及迭代次数与工具调用上限。
上下文组装说明见 request-building.md,协议与网络层实现见 model-runtime.md。
发起模型调用需要完整的运行时配置,仅凭模型名称无法确定网络行为。
PrimaryRouteFactory::prepare_route 读取配置中的 ModelRoute,验证端点、凭据和协议设置,生成包含协议选项、模型目录、重试配置与已解析运行时路由的 PreparedPrimaryRoute。
安装完整路由使用 PreparedPrimaryRouteInstall::apply 或 Agent::apply_prepared_route,一次性更新逻辑路由、协议选项、模型目录、重试配置与 ResolvedModelRoute。Agent::set_model_route_authority 仅用于直接绑定逻辑路由与已解析路由,并同步模型名称。
普通回合未安装已解析路由时,执行会直接报错返回。切换模型或更新路由后,Agent 会让当前请求投影失效,下次请求按新配置重新构建。
Agent 提供三种执行入口。
run执行非流式请求,等待全部生成完成后返回文本。run_stream_async执行流式请求,通过回调通知文本增量与生命周期事件。run_stream_content_with_interactions_async支持交互提问,允许模型向用户提出结构化问题。
入口方法在确认路由就绪后,调用 src/agent/protocol_stream.rs 中的 run_resolved_turn_async 启动执行。
回合按以下步骤执行。
- 结合用户选中的技能构建回合前言,记录当前历史长度作为受保护起点,追加用户输入,并触发
TurnStarted事件。 - 创建
ResolvedTurnDriver,挂接状态数据、文本增量回调、事件回调与权限通道。 - 初始化
TurnOrchestrator,传入运行实例与迭代限制。 - 检查迭代次数与工具调用次数,超过配置上限时返回错误。
- 驱动层构造请求,模型运行时发送请求并解码响应。失败时按下文的重试与恢复条件处理。
- 模型返回工具调用时,执行工具并写入历史,随后进入下一轮迭代。
- 模型返回文本并持久化后,驱动层决定继续迭代或结束回合。结束时发出
TurnFinalized,清理回合状态并返回文本。输出为空时返回No response content。
模型在回复中给出工具调用时,驱动层调用 execute_tool_calls_and_record 处理整组工具。
Agent 根据工具作用域检查工具是否可用,并对照会话权限规则核验调用。如果权限配置为拒绝,或者自动审批拒绝,工具直接生成拒绝记录;若已持有会话授权,无需用户确认即可放行;需要人工审批时再调用外部交互通道。
权限拒绝与普通工具执行错误通常打包为错误结果写回历史,供模型在后续迭代中读取并调整,不会直接中断整个回合。
模型元数据开启并行工具调用时,连续出现的同类工具可以分组并发执行。
- 普通并行工具要求工具自身声明支持并行、工具作用域允许调用,且在预检中通过无交互授权放行。所有并行任务完成后,系统按模型生成的原始调用顺序记录结果。
- 子代理工具由子代理池并发执行,任务完成后按实际完成顺序逐项发布事件并写入历史。详细规则见 subagents.md。
- 不满足并发条件的工具转为串行执行。
前台当前批次的所有工具执行完毕后,Agent 才会启动下一次模型迭代。如果部分工具尚未返回,系统不会提前向模型发送下一轮 Prompt。
工具产出的文本数据与图片同时写入历史记录的 ToolOutput。详细工具系统设计见 tools.md。
stream_resolved_oneshot_text_async 与 execute_resolved_text_oneshot 用于上下文压缩或摘要生成等单次文本请求。
这些辅助方法关闭工具调用、思考过程、并行工具和快速模式,不创建驱动层实例,也不修改会话历史。请求直接使用传入的已解析路由,复用底层的协议绑定与网络传输。
调用异常根据是否产生副作用与错误类别分别处理。
- 未产生可见文本、思考片段或工具调用的请求失败,在满足可重试错误类别且未超过尝试次数时,按配置退避重试。
- 产生部分输出后中断的请求失败,在满足可恢复错误类别且未超过恢复上限时,系统保留已有片段并开启恢复迭代。不满足恢复条件时终止回合。
服务商返回 HTTP 错误时,系统读取固定截断上限以内的响应体,脱敏凭据后返回错误信息。用户取消或主动中断沿错误路径返回。
src/agent.rs定义Agent结构体,管理会话状态、路由安装与工具调用调度。src/agent/protocol_stream.rs实现回合调度run_resolved_turn_async、驱动层ResolvedTurnDriver与单次辅助方法。src/agent/tool_execution.rs实现普通并行工具批量执行与子代理并发调度。src/model_runtime/runtime.rs实现编排器TurnOrchestrator与物理重试逻辑。src/model_runtime/mod.rs定义已解析路由ResolvedModelRoute与底层模型事件。