DeepAgent 与 harness

为什么还要一层

ReActAgent 只管"想一步、做一步"的循环。真正干活的智能体还需要很多周边设施：读写文件的工作空间、待办清单、子代理、技能、安全约束、模型异常检测……这些都是 harness（openjiuwen/harness/）提供的，DeepAgent 把它们装到一个 ReActAgent 外面。

DeepAgent（外层）
 ├─ 外层任务循环（可选）：把大任务拆成多轮
 ├─ 工作空间、子代理、技能、工具
 ├─ 默认 Rail：安全、模型异常检测……
 └─ 内层 ReActAgent：每轮任务里真正"想一步、做一步"

源码DeepAgentagent-core/openjiuwen/harness/deep_agent.py:320@fbe6a0d9

一个工厂函数装配全部

from openjiuwen.harness.factory import create_deep_agent

agent = create_deep_agent(
    model,                          # 已构造好的 Model 实例
    system_prompt="你负责回答客户的交期询问。",
    tools=[check_inventory, calc_promise, create_order],
    subagents=[...],                # 子代理：可以用不同模型、工具和提示词
    rails=[PromiseGateRail(store)],  # 先排队，第一次 invoke 时注册
    workspace="./workspace",        # 文件工具的工作目录
    enable_task_loop=True,          # 开启外层任务循环
)

源码create_deep_agentagent-core/openjiuwen/harness/factory.py:464@fbe6a0d9

几个默认值值得记住：

传了 subagents 会自动加 SubagentRail，传了 skills 会自动加 SkillUseRail，enable_task_planning=True 会加 TaskPlanningRail。如果你自己已经传了同类 Rail，工厂不会重复添加。

源码默认 Rail 列表agent-core/openjiuwen/harness/factory.py:398@fbe6a0d9

事件分两层

这是 DeepAgent 最容易踩的地方。Rail 关卡里讲的 13 个事件，在 DeepAgent 上由两个对象分别触发：

源码三个事件集合agent-core/openjiuwen/harness/deep_agent.py:166@fbe6a0d9

开了任务循环以后，每轮任务先触发 BEFORE_TASK_ITERATION，再调用一次内层 react_agent.invoke()，最后触发 AFTER_TASK_ITERATION。这一轮即使失败，AFTER_TASK_ITERATION 也会补触发一次。

于是有两种"轮"：任务的一轮（外层）和 ReAct 的一轮（内层）。一轮任务里可能有好几轮 ReAct。

动手：选对事件

三个任务都只让你选一个事件，看它在两轮任务里触发几次、在哪一层。

小结

• DeepAgent = 内层 ReActAgent + harness 周边设施，用 create_deep_agent 一次装配。
• 默认已经挂了安全和模型异常检测两道 Rail，传子代理、技能等会自动补对应的 Rail。
• 事件分内外两层；"任务一轮"和"ReAct 一轮"是两回事，按你要的频率选事件。