人工智能AI AgentAgent 框架大模型工具调用RAG提示工程强化学习【免费下载链接】agent-coreopenJiuwen agent-core可提供AI Agent开发、运行、调优与演进相关的全套SDK能力项目地址https://gitcode.com/openJiuwen/agent-core点击查看免费下载导读本文剖析 openJiuwen agent-core 中NativeHarness的设计它以「继承 DeepAgent」的方式将 DeepAgent 完整的 task_loop 内核task plan、stop-condition、SESSION_SPAWN 子 agent、interrupt/resume、plan_mode 等保留下来同时用「单 supervisor control channel」的架构把交互层重构成天然并发安全、语义清晰的 send/abort/pause/resume 模型。读完本文你将理解为什么「继承优于组合」、immediate abort 的 cancel 链如何真正停住 LLM/工具执行以及分级中断下的快照回滚机制并可直接对照仓库源码与测试用例深入验证。背景直连 react_agent.invoke 为什么行不通NativeHarness由SuperHarness迁移而来提交 e05888fa1。迁移前的实现里harness 的_run_round直接调用react_agent.invoke(_streamingTrue)绕过了 DeepAgent 的整个 task_loop 层因此一次性丢失了 18 项能力task plan任务计划与 stop-condition停止条件评估SESSION_SPAWN 异步子 agentBEFORE/AFTER_TASK_ITERATION 事件rails 挂载点follow_up 续轮interrupt / resumeplan_modeDeepAgentState 管理evolution / context_evolution rail 等同时原交互方式steer / follow_up / abort generator 流式在并发场景下存在语义模糊问题表现abort 不立即请求中断后正在执行的 LLM/工具调用仍然继续跑假 abortsteer 中间态丢失注入方向性指令时若恰好处于状态切换窗口消息被丢弃generator yield 阻塞生成器流式读取时被阻塞读不到下一条输入因此本特性的诉求非常明确NativeHarness 的能力必须与 DeepAgent 完全一致只重新设计交互方式并发安全 易用并彻底解决上述并发语义模糊问题。核心决策继承而非组合设计选型上NativeHarness采用继承方案class NativeHarness(DeepAgent): ...见 native_harness.py。它复用 task_loop 的全部内核——TaskLoopController/LoopCoordinator/TaskLoopEventHandler/TaskLoopEventExecutor/LoopQueues/ task_plan / session_spawn——仅用单协程 supervisor 替换_run_task_loop的while should_continue自驱动。为什么继承而不组合源码注释给出了根本原因native_harness.pytask-loop 的 executor 会调用agent.react_agent.invoke(...)并触发agent上的 BEFORE/AFTER_TASK_ITERATION 事件——这两个引用都必须解析到当前 harness 自身。如果写一个组合包装器去直接调react_agent.invoke就会绕过 executor从而绕过整个 task loop而「是 DeepAgent 本身」就可以原样复用_setup_task_loop/load_state/save_state/_has_remaining_tasks这些基类方法。前向构造从 DeepAgentSpec 直接物化NativeHarness.__init__采用前向构造先agent_spec.resolve_parts(build_context)解析出配置零件再super().__init__(parts.config.card)用真实的 card 构造 DeepAgent随后apply_deep_agent_parts把 config、tools、rails 直接应用到本实例——没有一次性模板 DeepAgent。构造是同步的宿主方可以在构造后立即读取deep_config上的workspace/sys_operation。构造期间还会挂载PhaseSnapshotRailnative_harness.py它通过add_rail按事件分流model/tool/react-iteration 钩子桥接到内部 ReActAgentAFTER_TASK_ITERATION 留在外层 DeepAgent——这是分级中断pause/abort与快照回滚的基石下文详述。交互层架构单 supervisor control channel新的交互层由三块组成单 supervisor control channel_supervisor协程是HarnessInternalState的唯一 writer。外部 APIsend/abort/pause/stop/resume只做一件事把ControlEvent推入asyncio.Queue然后await ack Future等待确认。由于所有状态变更都在 supervisor 串行消费事件时发生并发安全由构造保证——外部调用者永远观察不到半个过渡状态。输出走 asyncio.Queueforwarder 协程把session.stream_iterator()泵进 output queue不再暴露 generatornative_harness.py。交互契约抽象为HarnessProtocol阶段 2 的 StreamController-backed harness 将实现同一 Protocol对外表面统一protocol.py。ControlEvent 与 ack 模式ControlEvent是六种命令的联合类型全部为 frozen dataclasscontrol.pyControlEvent Union[ _CmdSend, _CmdAbort, _CmdPause, _CmdResume, _CmdRoundFinished, _CmdStop, ]其中_CmdRoundFinished是 round 任务结束时 supervisor 内部自己投递的通知成功/取消/异常都会投递携带round_id/error/result由_on_round_done驱动多轮决策。每个命令带一个ack: asyncio.Future外部调用者通过await ack获得「命令已被 supervisor 应用」的确认——例如pause()只有在真正到达 PAUSED 状态后才返回。状态机状态定义来自 provider 无关的 harness_protocol/state.py状态含义IDLE空闲无活动 roundRUNNING有 round 正在执行PAUSING已接受 pause 请求、尚未到达可恢复边界的瞬态PAUSED已暂停可在原地恢复TERMINATED已终止_transition在 supervisor 协程内更新相位并触发harness.state事件native_harness.py回调异常被框架吞掉不会压垮 supervisor。输入两语义steer 与 follow-upsend(content, immediateFalse)是唯一的外部输入入口按当前相位分派native_harness.py相位行为IDLE以content启动一个新 round_start_round转入 RUNNINGRUNNINGimmediateTruesteer注入共享 steering queueexecutor 在下次内部模型调用前排空_push_steer→LoopQueues.steeringRUNNINGimmediateFalsefollow-up缓冲进controller.enqueue_follow_up当前 round 结束后被_on_round_done排空续轮PAUSED忽略immediatecontent作为 steer 注入到续轮中而不是拼接进原 query 重启详见 pause 一节TERMINATED抛异常send返回单调递增的消息 seq id供调用方做全局 FIFO 排序。content可以是InteractiveInput——它携带 interrupt resume 语义_on_round_done对 resume round 按「单轮语义」处理完成后直接回 IDLE不继续 task plan。多轮决策follow_up pending task_plan remaining每个 round 自然结束时_settle_round_done复用DeepAgent._run_task_loop的多轮决策逻辑native_harness.py推进 coordinatorincrement_iterationset_last_result持久化 stop-condition 状态graceful abort 已置位 → 丢弃所有 follow-up回 IDLE运行时崩溃 →对入站 query 一次性重试failure_retry第二次异常死亡则放弃并回 IDLEresult_type interrupt或coordinator.is_aborted→ 回 IDLE排空 follow-up_drain_pending_follow_ups→ 启动续轮resume round → 回 IDLE_has_remaining_tasks(session)且存在original_query→ 以continues_turnTrue启动 task-plan 续轮否则回 IDLE值得注意多个 follow-up 会合并为一批驱动一个 roundbatch 保持 list 不提前 join让内部 agent 的 ON_USER_MESSAGE rails 先看到逐个输入、有机会丢弃已被新输入取代的旧输入native_harness.py——避免对一张已过期的任务看板采取行动。分级中断graceful / immediate / pauseabort与pause是两个不同语义的动词abort 丢弃当前 round回到 IDLE之后 send 开启全新 roundpause 在最近的内层 ReAct 迭代边界停下、保持 round 存活可经 resume 原地续跑。graceful abortabort(immediateFalse)合作式停止若 LLM 尚未开始在下一个before_model_call边界直接退出若一轮迭代LLM 工具已开始则运行完这一整轮在下一个模型调用边界退出。无回滚round 以正常方式结束不发射 abort marker。实现上通过ActiveRound.graceful_abort True让PhaseSnapshotRail在模型调用边界 force-finishsnapshot_rail.py_on_round_done看到 graceful 标记后丢弃 follow-up 直接 IDLE。immediate abortabort(immediateTrue)硬停 回滚task_scheduler.cancel_task取消调度器任务再把 DeepAgentState 与 context 回滚到最近的 round 边界 snapshot。工具已产生的副作用不撤销固有不一致见「已知遗留」。回滚目标优先级last_iter_snapshot最近内层迭代边界→pre_round_snapshotround 起始基线。回滚后必须coordinator.reset()否则is_aborted会永久污染下一轮的should_continuenative_harness.py。pausepause()resume()按内层循环所处位置分两种策略native_harness.pyLLM 相位model_call_in_flightTrueexec 任务停在模型调用 await 里——这是唯一可以硬取消而不会碰到运行中工具的窗口。取消之并回滚到最近干净边界。工具/边界相位已开始的迭代必须跑完工具副作用不可逆于是武装合作式停止pause_requestedTrueack 被延迟到_on_round_done结算PhaseSnapshotRail在下一个模型调用边界 force-finish。暂停的 round 会缓存paused_query。resume()有两种形态warm相位 PAUSEDround 仍在内存用缓存的 query 在原保留 context 上启动续轮_resume_continuationTrue不追加新用户轮次coldIDLE 提供 queryharness 已在 stop 后被重建、context 从 session checkpoint 恢复协调层把 pause 时记录的 query 传进来。send在 PAUSED 相位的行为也经过了精心设计在当前 context 上原地恢复续轮并把新内容作为 steer 注入而不是拼接进原 query 重启——后者会丢弃已完成的每一轮迭代对应测试test_send_while_paused_resumes_and_injects_the_new_content。相位跟踪与快照PhaseSnapshotRailPhaseSnapshotRail承担三件事snapshot_rail.py相位跟踪维护ActiveRound.iter_phaseBOUNDARY / MODEL / TOOL、model_call_in_flight、tool_started让 supervisor 判断硬取消是否安全边界快照在AFTER_REACT_ITERATION捕获last_iter_snapshot在AFTER_TASK_ITERATION捕获last_safe_snapshot——它们是回滚目标合作式停止pause/graceful abort 武装后在模型调用边界请求 force-finish保证 loop 永远停在干净迭代边界、绝不停在工具执行中途。关键实现细节rail 通过harness 反向引用harness.active_round定位活动 round而不是 ContextVar——因为内层循环跑在 TaskScheduler 的 exec task 里ContextVar 在那里读不到值。快照使用with_historyFalse只捕获当前 round 的消息段回滚时也以同样方式恢复从而保留持久化 history 段、只回卷进行中的 roundsnapshot_rail.py。命门验证immediate abort 的 cancel 链这是整个设计最要害的验证点immediate abort 必须真正停住 executor。关键背景submit_round只把任务add_task后立即返回真正的react_agent.invoke跑在 TaskScheduler 自己create_task的 exec_task 里。因此若只 cancel「跑wait_round_completion的 task」只是解除了 awaitexecutor 变成孤儿LLM/工具继续跑——这是假 abort正确的链是controller.task_scheduler.cancel_task(task_id)→executor.cancel内部执行coordinator.request_abort()task_plan.mark_cancelled→exec_task.cancel→react_agent的except asyncio.CancelledError清理当前轮 messages 后 re-raise干净停止。对应实现见 native_harness.py_hard_cancel_round与 task_loop_event_executor.pycancel。对 task_loop 的唯一侵入submit_round 加 kw-only task_id为了拿到 task_idTaskLoopController.submit_round增加了kw-only 的task_id参数注入event.metadata[task_id]由handler.handle_input读取作为调度器任务 idtask_loop_controller.py、task_loop_event_handler.py。这是对 task_loop 的唯一侵入且为纯加法team 路径不传task_id则行为不变tests/unit_tests/harness/test_deep_agent.py48 个用例全部通过证明了向后兼容。submit_round还顺带透传了turn_number与_resume_continuation标志前者让不同 async context 中的调度任务仍能拿到归属轮次后者让内层 ReAct loop 续轮时不追加新用户轮次。coordinator.reset 的必要性跨 round 复用同一个 coordinator所以 immediate abort 之后必须coordinator.reset()executor.cancel通过coordinator.request_abort()设置了is_aborted若不重置下一轮的续轮检查会看到一个永久 aborted 的 coordinatorround 永远跑不起来。对应测试test_immediate_abort_resets_coordinator_next_round_runs专门断言了这一点test_abort.py。被否决的方案方案缺陷结论直接接react_agent.invoke现状丢 task_loop 全部 18 项能力否决组合 走DeepAgent.stream如 TeamHarness能力保留但 stream 是 generator 内部 event 注入无法根治并发/中断语义immediate abort/pause 的分级回滚难以精确做本次选继承覆写精确接管 outer round 驱动cancel 跑 wait 的 task 做 immediate abort留孤儿 executor假 abort否决生命周期 API 速览NativeHarness的公开 API 全部并发安全native_harness.pyAPI说明start(sessionNone)从 spec 配置自身、构建 task-loop 内核、启动 supervisor forwarder幂等且并发安全_starting守卫stop()取消活动 round、停掉 controller、关闭输出流可多次调用结束时状态为 TERMINATEDoutputs()队列背书的AsyncIterator[OutputSchema]单消费者契约stop()后以_END哨兵正常结束outputs.pysend(content, immediateFalse)见「输入两语义」abort(immediateFalse)graceful / immediate 分级中断pause()最近内层迭代边界暂停保持可恢复resume(queryNone)warm / cold 两种恢复run_once(content, sessionNone)完全绕过 supervisor 的单次非流式执行普通DeepAgent.invoke供 swarmflow worker 等单发调用方使用subscribe(on_state, on_round)harness 私有事件总线消费方可把生命周期映射到自己的状态机回调在 supervisor 内触发顺序与相位转换严格一致launch_async_tool(...)启动被 harness 追踪的后台异步工具任务完成结果通过send(immediateFalse)注入另有属性state/session_id/active_round/paused_query/model供 rails 与协调层读取。stop()与dispose()有明确分工stop是轮次结束的拆除native 下一轮会被 TeamHarness 重建dispose是永久销毁钩子从进程级资源管理器移除本 agent 的sys_operation防止会话丢弃时泄漏。测试验证真内核 假 react_agent验证基线来自特性文档tests/unit_tests/agent_teams/harness/ 28 passed tests/unit_tests/harness/test_deep_agent.py 48 passed (submit_round 向后兼容)测试策略极具价值用真 task_loop 内核 FakeReactAgent 注入而非 mock 整个 agentfixtures.pystart()构建真内核与真 react_agent然后测试调用set_react_agent(fake, initializedTrue)让真TaskLoopEventExecutor驱动假 react_agentfake 的invoke运行一个迷你 ReAct 循环镜像真实内层循环的钩子顺序与停止点迭代顶 / BEFORE_MODEL_CALL / model sleep可取消窗口/ AFTER_MODEL_CALL / BEFORE_TOOL_CALL / tool sleep / AFTER_REACT_ITERATION因此可以按相位演练 pause/abortfake 记录每次调用的输入、排空 steering 队列、统计观察到的CancelledError次数cancel 链断言注入后必须rebind_bridge_rails把 harness 的 BRIDGE 事件钩子重注册到 fake 上否则相位跟踪失效。覆盖场景与特性文档一一对应测试文件覆盖点test_state_transitions.py单轮 IDLE→RUNNING→IDLEfollow-up FIFO 续轮多条 follow-up 合并驱动一个 round_input_parts断言并发start只初始化一次stop终止输出迭代器send-after-stop 抛异常slow round 只告警不取消test_abort.pygraceful abort 让当前 round 跑完cancelled_count 0immediate abort cancel 链cancelled_count 1abort 后 coordinator 已重置、下一轮能跑回滚到最近边界 / 无已完成 round 时回退到基线test_pause.py模型相位 pause 中断 LLM 并回卷一个边界工具相位 pause 绝不打断工具cancelled_count 0、工具跑完resume 原地续跑不追加用户轮PAUSED 时 send 恢复并 steer 注入cold resume 驱动 task-plan 续轮paused_query暴露给持久化test_protocol_and_lifecycle.pyisinstance(harness, DeepAgent)与isinstance(harness, HarnessProtocol)注入 session 复用stop无后台 task 泄漏stop幂等BEFORE/AFTER_INVOKE 每 outer round 触发一次AFTER_TASK_ITERATION 在失败路径也触发evolution rail 每轮触发test_failure_retry.pyround 异常死亡后的单次重试语义raise_exc_once已知遗留与阶段 2 规划task_plan 回滚语义immediate abort/pause 回滚 DeepAgentState 会撤销本轮的 task 进度标记与「工具外部副作用不可撤销」存在固有不一致——状态说没做、文件已改。这是 immediate 中断的固有代价已在 docstring 声明。阶段 2后续StreamController 接管 round 驱动、实现 HarnessProtocol、统一 team 与 native 两条路径。当前交付的是独立 single-agent NativeHarness接口按统一预留HarnessProtocolActiveRound.task_id统一 round 标识。代码中 round driver 相关方法_start_round/_run_round/_hard_cancel_round与快照/回滚对的组织已为阶段 2 的_RoundDriver抽取预留了接缝native_harness.py。team 路径预存在债与本特性无关e05888fa1 迁移遗留agent_teams.harness.__init__未导出_MountedRails导致test_harness.py/test_stream_controller.pycollection error修复后还暴露了 2 个 stale testpatch 不存在的harness.Runner。本特性未触碰 team 路径建议单独修复。参考路径汇总核心实现native_harness.py、control.py、state.py、snapshot_rail.py、outputs.py、protocol.py、turn.py、team_harness.pytask_loop 内核deep_agent.py、task_loop_controller.py、task_loop_event_handler.py、task_loop_event_executor.py、loop_coordinator.py、loop_queues.py状态枚举harness_protocol/state.py测试fixtures.py、test_state_transitions.py、test_abort.py、test_pause.py、test_protocol_and_lifecycle.py、test_failure_retry.py阅读建议先通读 native_harness.py 的 supervisor 与 round driver 部分再对照 test_abort.py 与 test_pause.py 中 cancel 链与相位断言即可完整复现本特性的正确性论证。赞分享人工智能AI AgentAgent 框架大模型工具调用RAG提示工程强化学习【免费下载链接】agent-coreopenJiuwen agent-core可提供AI Agent开发、运行、调优与演进相关的全套SDK能力项目地址https://gitcode.com/openJiuwen/agent-core点击查看免费下载相关推荐openJiuwen agent-core task_loop 深度解析驱动 DeepAgent 多轮自主执行的外层任务循环openJiuwen agent core task_loop 深度解析驱动 DeepAgent 多轮自主执行的外层任务循环 本文以 openjiuwen.h人工智能AI AgentAgent 框架大模型工具调用RAG提示工程强化学习Java 复用设计思想深度剖析组合、继承与多用组合少用继承原则Java 复用设计思想深度剖析组合、继承与多用组合少用继承原则 本篇技术指南以 YCBlogs 仓库的 Java 类与对象学习体系为背景系统讲解面向对象教程技术博客文档TypeGraphQL解析器继承代码复用与架构设计技巧TypeGraphQL解析器继承代码复用与架构设计技巧 你是否在TypeGraphQL项目中重复编写相似的CRUD解析器代码解析器继承Resolver I后端GraphQLAPI设计上一篇SheetJS命令行工具详解xlsx命令的15种实用用法下一篇如何快速掌握Cantera面向化学动力学模拟的完整指南 创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考