IronClaw Reborn 轻量 Agent Loop 契约：父循环的决策权与执行权是如何分离的

人工智能AI 应用交互助手AI Agent【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址https://gitcode.com/gh_mirrors/iro/ironclaw点击查看免费下载本文围绕 IronClaw Reborn 的轻量 Agent Loop 参考契约lightweight-agent-loop.md展开讲清这个默认随项目交付的父循环parent loop在 IronClaw 宿主契约内如何运行它只负责“何时问模型、何时请求可见能力”而能力能否执行、如何执行完全由宿主侧的 CapabilityHost、审批与授权体系裁决。读完本文你将掌握该循环的完整状态机、Reply | CapabilityCalls父协议、批量执行与挂起/恢复机制、可见能力面visible capability surface的门控策略并能对照仓库源码定位每一环节的真实契约类型与测试用例。1. 定位默认交付的轻量 Agent Loop而非内核行为契约文档开篇即给出定位定义 Reborn 默认交付的轻量 Agent Loop作为参考循环实现reference loop implementation而不是内核行为。它借鉴了badlogic/pi-mono/packages/agent的循环机制stream assistant - execute tool/capability calls - append tool results - repeat until reply, blocked, failed, or interrupted但有两个明确的边界约束它不是对pi-mono的依赖也不导入pi-mono的授权authority语义而是一个运行在 IronClaw 宿主契约之内的 Reborn 原生循环它可以打包为内置的agent_loop扩展也可以实现为随附的参考循环 crate。无论哪种形态它只能获得一个窄化的、经内核中介的宿主门面host facade永远拿不到原始服务管理器也永远无法绕过CapabilityHost/策略检查。该契约声明依赖同目录下的多个兄弟契约仓库中均已存在agent-loop-protocol.md、runtime-workflows.md、capabilities.md、run-state.md、approvals.md、events.md、runtime-selection.md、runtime-profiles.md。2. 核心不变量循环决定“何时问”宿主决定“如何执行”契约的核心不变量只有两句话The lightweight loop decides when to ask the model and when to request visible capabilities. The host decides whether and how those capabilities execute.循环不得绕过以下内核管理器CapabilityHost RunStateManager ConversationManager ApprovalManager AuthFlowManager RuntimeDispatcher EventStreamManager ResourceGovernor契约进一步强调这个循环是父循环机制parent-loop mechanic而不是授权/运行时层。它由项目官方交付这一事实可能会通过宿主策略影响其信任上限trust ceiling但交付身份本身不授予任何授权。3. 父协议顶层只有Reply | CapabilityCalls两个分支面向宿主的父协议保持极简Reply | CapabilityCallsProvider 原生的 tool calling 可以编码CapabilityCalls但循环必须在执行前把 provider 的 tool call归一化为 IronClaw capability call。以下内容不是顶层父协议分支CodeAct QuickJS script shell job subagent experiment它们是显式的能力capability例如action_script.run(...) script.run(...) experiment.exec(...) spawn_subagent(...) create_job(...)从源码结构看这一“两个顶层分支”的约定在契约 crate 中有对应的枚举定义ironclaw_loop_contracts/src/host/model.rs 中的ParentLoopOutput只有两个变体——AssistantReply与CapabilityCalls(VecCapabilityCallCandidate)其中每个CapabilityCallCandidate携带activity_id、surface_version、capability_id、input_ref等字段model.rs与契约要求的“调用前分配稳定活动身份”相吻合。4. 循环机制从开始运行到停止的完整状态机契约第 4 节给出了完整的机制描述原文流程begin run load durable thread snapshot build instruction bundle load visible capability surface while run is active: process queued steering/follow-up messages stream one assistant response persist assistant milestone when finalized if response is Reply: complete run stop if response has CapabilityCalls: execute call batch sequentially or in parallel according to policy append capability-result messages continue if a call requires approval/auth/resource wait: checkpoint loop block run stop until resumed if interrupted/cancelled/failed: transition run state stop这里有一个关键的双通道设计能力结果在转录记录中携带严格的LoopSafeSummary用于可移植的元数据、日志、检查点和回退重放而当宿主拥有更丰富的面向模型的恢复信息时它可以向 tool-result 引用附加一个有界的ModelVisibleToolObservation侧信道。该观察值是模型可见的不可信工具输出不是LoopSafeSummary的替代品且在回放到模型前必须经过校验/脱敏。仓库源码印证了这两个类型都是真实存在的一等契约类型LoopSafeSummary定义在 ironclaw_loop_contracts/src/host/refs.rsModelVisibleToolObservation定义在 ironclaw_loop_contracts/src/model_observation.rs带schema_version、status、summary、detail、artifacts、recovery、trust字段并有硬性边界摘要最多 512 字节、artifacts/repairs/input issues 各最多 16 条model_observation.rsvalidate()方法在跨边界时强制校验 schema 版本与长度。契约还给出了等价伪代码loop { let pending host.take_pending_messages(run).await?; context.append(pending); let bundle host.build_instruction_bundle(run).await?; let surface host.visible_capabilities(run).await?; let assistant loop_impl.stream_assistant(context, bundle, surface).await?; host.append_milestone(assistant.clone()).await?; match assistant.output { Reply(reply) { host.complete_run(reply).await?; break; } CapabilityCalls(calls) { let results loop_impl.execute_batch(run, calls).await?; context.append(results.messages); host.checkpoint(run, context.summary()).await?; } } }循环的运行时实现落在 ironclaw_agent_loop crate 中其executor模块下按职责拆分为capabilities.rs、checkpoint.rs、model.rs、prompt.rs、mapping.rs等文件并配套了成体系的 executor 测试。5. 宿主门面AgentLoopHost与端口化落地循环接收的是AgentLoopHost门面而不是原始管理器。契约中给出的 trait 形态pub trait AgentLoopHost { async fn load_thread_snapshot(self, run: RunHandle) - ResultThreadSnapshot; async fn build_instruction_bundle(self, run: RunHandle) - ResultInstructionBundle; async fn visible_capabilities(self, run: RunHandle) - ResultVisibleCapabilitySurface; async fn stream_model(self, request: ModelStreamRequest) - ResultModelStream; async fn invoke_capability(self, request: LoopRequest) - ResultCapabilityOutcome; async fn append_milestone(self, milestone: TranscriptMilestone) - Result(); async fn publish_event(self, event: RuntimeEvent) - Result(); async fn checkpoint(self, checkpoint: LoopCheckpoint) - Result(); async fn block_run(self, blocked: BlockedRun) - Result(); async fn complete_run(self, output: LoopOutput) - Result(); async fn fail_run(self, error: LoopError) - Result(); }契约强调该门面“组合”了更底层的各类服务但不把所有权移入循环。从源码结构看当前仓库把这个门面进一步细化为一组按契约簇划分的端口port统一在 ironclaw_loop_contracts/src/host/mod.rs 中重导出例如LoopCapabilityPort/LoopRequest/LoopRequestBatch/VisibleCapabilitySurfacehost/capability.rsLoopModelPort/LoopModelRequest/LoopModelResponse/ParentLoopOutputhost/model.rsLoopCheckpointPort/LoopCheckpointKindhost/checkpoint.rsLoopTranscriptPort/BeginAssistantDraft/FinalizeAssistantMessagehost/transcript.rsLoopInputPort/LoopProgressPort/AgentLoopDriverHosthost/input.rs、host/progress.rs。其中LoopModelRequestmodel.rs携带messages、surface_version、iteration发起该 provider 调用的循环迭代序号与可选的tool_choice约束——这正是契约第 4 节“每次模型调用前请求带版本能力面”的工程化体现。该契约还有专门的调用方级测试ironclaw_turns/tests/agent_loop_host_contract.rs 通过宿主门面驱动整个循环。6. 能力工具封装与capability_info合成工具可见能力会变成当前运行专用的、紧凑的模型可见工具 schemaCapabilityDescriptor - model-visible name - description - input schema - concurrency policy - result shaping hints对应源码类型CapabilityDescriptorView携带capability_id、provider、runtime、safe_name、safe_description、description_trust与parameters_schemahost/capability.rs并由此派生出面向 provider 的ProviderToolDefinition。循环还暴露一个合成的只读 provider 工具capability_info用于渐进式披露progressive disclosure——当模型需要当前可见能力的名称、必填字段、副作用说明或完整输入 schema 时调用它。它不经过HostRuntime分发也无法检视当前可见面之外的能力。仓库中该功能有独立实现与测试ironclaw_loop_host/src/capability_info.rs、synthetic_capability.rs 以及 capability_info_tests.rs。工具执行是对CapabilityHost的封装完整调用链为model tool call - normalize to LoopRequest - CapabilityHost.invoke_json(...) - CapabilityAccessManager action-time authorization - Approval/Auth/Resource gates if needed - RuntimeDispatcher.dispatch_json(...) - capability result - toolResult/capability-result message契约划出一条硬边界循环不得直接调用RuntimeDispatcherRuntimeDispatcher只接收已经授权完成的调用。7. 批量执行默认并行独占资源强制串行同一模型响应中发出的多个调用默认并行调度。顺序执行的策略措辞仍保留在内部执行与可观测性词汇中但规范执行器不再为新的模型发出批次选择它。宿主端口仍可为具体调用集中的运营风险要求有序批次入口——有序入口会设置stop_on_first_suspension外层装饰器必须保持调用者顺序分发不得把批次重新扇出。契约给出的规则宿主能力策略可强制某个调用或整个批次串行执行每个调用独立授权并行批次执行不是批量授权多个调用需要审批时审批提示应保持来源顺序文件系统写入、shell/进程调用及其他独占资源可由描述符/配置档策略指定串行结果消息应按 assistant 来源顺序追加除非后续契约明确选择完成顺序。推荐的批次选择逻辑if any call requires exclusive/sequential execution: execute whole batch sequentially else: preflight/authorize each call and execute approved calls concurrently这一机制在源码中有对应测试executor/tests/parallel_batch.rs 专门验证并行批次行为capability_results.rs 验证结果消息的追加语义。8. 挂起与恢复审批/认证/资源等待不是普通工具错误随附的参考循环必须支持结构化挂起structured suspension。能力结果outcome类型pub enum CapabilityOutcome { Completed(CapabilityResult), ApprovalRequired(ApprovalGate), AuthRequired(AuthGate), ResourceBlocked(ResourceGate), Failed(CapabilityError), }遇到ApprovalRequiredcheckpoint loop state - ApprovalManager.open_pending_gate - RunStateManager.blocked(approval) - EventStreamManager.publish(approval_needed) - stop loop until resume遇到AuthRequiredcheckpoint loop state - AuthFlowManager.begin - RunStateManager.blocked(auth) - TransportAdapter presents auth flow - stop loop until secret lease/auth completion恢复resume流程RunStateManager.resume - reload checkpoint and durable transcript snapshot - rebuild instruction/capability surface - continue or replay the pending invocation using idempotent invocation fingerprinting恢复依赖幂等调用指纹invocation fingerprinting来决定是继续还是重放待处理调用。契约还给出务实的降级说明MVP 纯本地实现可以在短审批期间阻塞一个 promise但托管hosted与持久durable会话要求显式挂起。源码侧executor/tests/gates.rs 与 auth_resume.rs 分别覆盖审批/资源门控与认证恢复路径CapabilityOutcome类型的实际使用可在 ironclaw_host_runtime 的能力响应处理器及其契约测试中查证。9. 工作上下文 vs 持久转录谁是事实源循环可以维护一个内存中的工作上下文类似AgentMessage[]但它不是事实源。事实源划分如下working context turn-local projection ConversationManager durable transcript source of truth RunStateManager run lifecycle source of truth EventStreamManager realtime delivery source ProjectionReducer derived read models契约给出持久化行为指引表逐行继承原文Loop eventDurable behaviorassistant stream start/updatelive event only, optional ephemeral partialassistant finalizedtranscript milestonecapability batch startrun/event milestonecapability call start/update/endcapability audit live progresscapability result messagetranscript milestoneturn boundarycheckpoint/milestoneblocked approval/auth/resourcerun-state transition eventfinal replytranscript milestone run complete并有一条硬约束实时流丢失不得损坏持久转录状态Realtime stream loss must not corrupt durable transcript state。这意味着流式增量只是“活的投影”而转录里程碑milestone写入才是可恢复的持久事实。10. 引导Steering与后续Follow-up双队列循环可支持两个宿主拥有的输入队列steering messages引导消息在循环活跃期间、下一次 assistant 响应之前注入follow-up messages后续消息在循环本应停止后被消费从而触发另一个 assistant 轮次。active run receives steering - append as pending message before next model call agent would stop, follow-up exists - append follow-up and continue两个队列必须保留作用域scope与顺序且不得绕过运行状态规则。远程/托管部署还必须遵守每线程单活跃运行one-active-run-per-thread与传输层授权约束。11. 动态能力面版本化、门控与“仅示能”选择可见能力面在扩展激活、认证完成、授权变更或配置档变化之后都可能改变。循环应在每次模型调用前请求带版本的能力面visible_capabilities(run) - { version, capabilities }若版本变化循环重新生成模型可见工具 schema。循环本身不直接发现扩展。即便能力已可见操作时授权action-time authorization仍然必需。源码中VisibleCapabilitySurface结构正携带versionCapabilitySurfaceVersion与descriptors并额外区分了callable_capability_ids在渐进式工具披露下“广告集”token 经济考虑收窄过的子集与“可调用集”可以不同调用时授权必须针对更宽的“可调用”集合校验host/capability.rs——这是对契约“可见面是推理辅助而非授权捷径”的直接落实。11.1 可见面的过滤管线与“仅示能”原则循环应避免隐藏的策略启发式例如if estimated tool calls 5, force ActionScript if task mentions tests, force shell取而代之的做法是宿主在每次模型调用前塑造模型可见面模型从清晰的语义示能affordance中选择宿主再通过正常能力策略执行或阻断这些请求visible surface CapabilityCatalog filtered by DeploymentMode filtered by RuntimeProfile filtered by tenant/org/user/project grants filtered by auth/installation state filtered by run/thread policy rendered as LlmToolViews契约给出“该隐藏还是该暴露”的判断表逐行继承原文ContextHide or expose?Reasonhosted multi-tenant sessionhideLocalHostshell/file capabilitiesprovider host access is never validlocal safe profile before write approvalexpose write capability with ask policyuser may approve writesno GitHub extension installedhide GitHub provider capabilities or expose install/auth capability onlyavoid pointless API retriesGitHub installed but token expiredexpose GitHub capability as auth-blockable if auth flow can resumemodel can request semantic action; host opens auth gateActionScript disabled by tenant policyhideaction_script.runno amount of retrying can make it validExperiment sandbox unavailable due quotaexpose only if resource-blocked resume is supported; otherwise hide or ask useravoid loop churn也就是说对于调用方/配置档绝对不可能或类别性禁止的能力通常应当直接不出现在可见面而不是暴露后在调用时反复拒绝。可见面是 UX 与推理辅助不是授权捷径。每个可见能力仍然会接受操作时授权原因是授权/租约可能在提示词与调用之间过期参数影响风险与审批要求资源配额可能变化认证可能缺失或已撤销并发运行可能消耗共享限额配置档或租户策略可能在执行前改变。模型可以在action_script.run、shell.run、experiment.*可见时选择它们但不选择运行时后端——后端选择始终是宿主/配置档的职责。结构化拒绝structured denial只用于“可见但因参数特定或时变条件被拒绝”的选择不要依赖拒绝/重试循环来解决静态配置档约束。12. 与 QuickJS/ActionScript 及运行时配置档的关系12.1 QuickJS 是能力不是父循环lightweight loop - action_script.run(code, allowed_capabilities) - QuickJS executes real JS with no ambient fs/net/env/process - QuickJS ic.call(...) - CapabilityHost for every internal call适用action_script.run的场景循环loops、扇出/扇入fan-out/fan-in、分页、过滤/排序/分组、结构化 JSON 转换、基于先前结果的动态调用。简单/静态的工具调用应使用直接能力调用shell/包管理/构建/测试类工作应使用experiment.*或script.run。12.2 同一个循环跑在所有配置档下LocalDev profile: filesystem.read/write - HostWorkspace shell.run - LocalHost HostedMultiTenant profile: filesystem.read/write - tenant workspace shell.run - tenant-scoped sandbox EnterpriseDedicated profile: filesystem.read/write - org-dedicated workspace shell.run - org-dedicated runner/container/VM循环只看到带脱敏描述符、访问状态与选定资源估计的可见能力由配置档解析器与运行时后端决定它们在哪里、如何执行。13. 扩展姿态、最小实现目标与后续契约测试13.1 参考循环的扩展姿态该循环可以随附第一方包元数据交付但元数据不等于授权extension role: agent_loop trust ceiling: assigned by host policy host surface: AgentLoopHost facade only生成的扩展不能创建新的父循环授权面它们可以提供该循环可调用的能力受正常的能力注册、授权、审批与运行时分发约束。ironclaw_extension_registry可以注册内置包元数据但不得执行循环——循环执行属于持有AgentLoopHost门面的已配置循环 runner/服务并继续受内核中介策略约束。13.2 最小实现应包含与不应包含第一个实现应包含provider 无关的Reply | CapabilityCalls归一化流式 assistant 消息事件从可见能力生成能力封装器串行/并行批次执行结构化的审批/认证/资源挂起在 assistant-finalized、batch-start、result-appended 与 blocked 状态的检查点steering 与 follow-up 队列钩子到EventStreamManager的事件映射通过ConversationManager的持久里程碑写入运行时配置档无关的行为。不应包含直接的 filesystem/shell/HTTP 调用扩展发现密钥解析secret resolution运行时分发绕过指令/工具选择之外的产品特定编码 agent 行为把 QuickJS 嵌入为父协议分支。13.3 待补充的契约测试清单契约要求实现完成后补充通过宿主门面驱动循环的调用方级测试原文逐条继承最终回复完成运行且无副作用provider 原生 tool call 归一化为能力调用可见能力仍接受操作时授权串行能力强制整个批次串行执行并行只读调用并发执行但结果按来源顺序追加需审批的调用挂起运行且不追加伪造的错误 tool result需认证的调用独立于审批挂起运行从审批检查点恢复后以调用指纹继续或重放steering 消息在下一次模型调用前注入follow-up 消息在自然停止后重启循环能力面版本变化在下次模型调用前重建工具 schema配置档禁止的能力在模型调用前就不出现在可见面中可见但因参数被拒的能力返回结构化拒绝且不改选后端本地与托管配置档运行同一循环但解析出不同后端。14. 延伸阅读仓库内的关键坐标围绕本契约仓库中值得继续深入的坐标契约 crateironclaw_loop_contracts——宿主边界 DTO 与端口的单一定义点LoopSafeSummary、VisibleCapabilitySurface、ParentLoopOutput均在此 crate模型可见观察值model_observation.rs——ModelVisibleToolObservation的边界常量与validate()校验循环实现ironclaw_agent_loop——executor 及其按主题划分的测试并行批次、门控、认证恢复、检查点、预算、取消宿主侧端口ironclaw_loop_host——能力端口、capability_info合成工具与能力面快照调用方级契约测试agent_loop_host_contract.rs兄弟契约文档agent-loop-protocol.md、capabilities.md、run-state.md、approvals.md、runtime-profiles.md。需要说明的适用前提本文描述的是该契约文档日期 2026-04-26状态为“Decision guide / reference loop contract”所定义的参考循环契约。文档中的AgentLoopHost单 trait 形态是契约层的设计描述当前源码已将其细化为一组LoopXxxPort端口——两者语义一致循环只经门面与宿主交互但具体类型命名以ironclaw_loop_contracts为准。赞分享人工智能AI 应用交互助手AI Agent【免费下载链接】ironclawIronClaw is an Agent OS focused on privacy, security and extensibility项目地址https://gitcode.com/gh_mirrors/iro/ironclaw点击查看免费下载相关推荐IronClaw 循环层契约解析ironclaw_loop_contracts 如何用端口与 DTO 隔离可替换的 Agent 循环IronClaw 循环层契约解析ironclaw_loop_contracts 如何用端口与 DTO 隔离可替换的 Agent 循环 本文深入剖析 IronC人工智能AI 应用交互助手AI AgentIronClaw loop 层契约解析ironclaw_loop_contracts 如何让 agent loop 与 turn 内核解耦IronClaw loop 层契约解析ironclaw_loop_contracts 如何让 agent loop 与 turn 内核解耦 本文是 IronC人工智能AI 应用交互助手AI AgentIronClaw Hooks 框架深度解析四层信任模型、类型级权限约束与 Reborn 循环的钩子调度契约IronClaw Hooks 框架深度解析四层信任模型、类型级权限约束与 Reborn 循环的钩子调度契约 本篇技术指南以 IronClaw 开源仓库中 cr人工智能AI 应用交互助手AI Agent上一篇Rust Rosetta Code内存安全所有权和借用检查器的实战解析下一篇Sol2单头文件生成教程快速集成到任何项目创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考