openJiuwen Agent 团队生命周期(持久团队模式):从提示词设计到运行时自动待命机制

原创2026-10-12 10:40:541,961 阅读
文章标签:人工智能大模型AI AgentAgent 框架Agent 工作流多智能体工具调用MCP 服务Agent 记忆RAG后端Agent 沙箱

openJiuwen Agent 团队生命周期(持久团队模式):从提示词设计到运行时自动待命机制

导读

本文深入解析 openJiuwen agent-core-java 中 Agent 团队的生命周期管理机制,聚焦 LeaderTeammateAgentTeam(队长-队员型团队)的"持久团队(Persistent Team)"运行模式。文章以 agent/prompts/en/lifecycle_persistent.md 提示词模板为骨架,结合团队策略构建、运行时调度、事件总线与测试用例等源码,完整呈现"长期运行、任务完成后自动进入待命状态、等待新指令"这一生命周期模式的配置方式、底层实现原理与工程实践建议。读完本文,你将掌握如何将团队配置为持久运行模式、理解"自动待命"背后的 TEAM_COMPLETED 事件与 concludeCompletedRound 调用链,并能依据场景正确选择持久 / 临时两种生命周期。


一、生命周期模板:持久团队的"行为宪法"

1.1 模板内容全解

在 agent-core-java 仓库中,Agent 团队(LeaderTeammateAgentTeam)的每个成员都会在其系统提示词(system prompt)中注入一段"团队生命周期"说明,用于约束该成员在任务收尾阶段的行为。持久团队对应的英文模板位于 core/src/main/resources/openjiuwen/agent_teams/agent/prompts/en/lifecycle_persistent.md,其核心内容如下:

Team Nature: Persistent Team This is a persistent team that continues running and awaits new instructions after completing current tasks. After all tasks are done:

  1. Summarize the current round of work results
  2. Do not close members or dissolve the team
  3. The team will automatically enter standby mode, awaiting new tasks from the user

Wrap up efficiently: Use send_message(to="*") to broadcast the round summary and standby notice once. Do not address members individually, and do not reply to members' acknowledgements/thanks — avoid pointless back-and-forth courtesies.

模板以三句话点明持久团队的三大行为规则:

  1. 汇总当轮成果:任务全部完成后,队长(Leader)需先汇总本轮工作结果;
  2. 不解散团队:不得调用 shutdown_member 关闭成员、不得调用 clean_team 解散团队;
  3. 自动进入待命:团队保持运行,等待用户下发新一轮任务。

此外模板还规定了高效收尾协议:使用 send_message(to="*") 做一次性广播(该调用会发送到团队频道,所有成员可见),明确禁止逐个成员致意、禁止回复成员的致谢/确认消息,以避免无意义的来回寒暄拖慢收尾流程。

仓库同时提供简体中文版本 agent/prompts/cn/lifecycle_persistent.md,内容与英文版一一对应("团队性质:长期团队"),多语言模板由 Agent 团队的 language 配置决定加载哪一份。

1.2 与临时团队模板的对比

持久团队与临时团队(Temporary Team)是 openJiuwen 团队体系中的两种对称生命周期,其模板并列存放于同一目录:

维度 持久团队(Persistent) 临时团队(Temporary)
模板文件 lifecycle_persistent.md lifecycle_temporary.md
任务完成后 汇总成果 → 保持运行 汇总成果 → shutdown_member 关闭所有成员 → clean_team 解散团队
成员去向 不解散、进入待命 全部关闭并清理
收尾方式 send_message(to="*") 广播总结与待命通知 send_message(to="*") 广播总结与解散通知后立即执行关闭流程

两者的"高效收尾"约定完全一致,差异仅在"解散与否":临时团队明确要求 Leader 依次调用 shutdown_member 关闭所有成员、等待成员状态转为 SHUTDOWN 后再调用 clean_team(详见 clean_team.md 的说明:若存在非 SHUTDOWN 状态的成员,clean_team 会失败);而持久团队则明令禁止这两步。


二、生命周期如何被注入系统提示词:模板装载与条件拼接

2.1 AgentTeamPolicy:按角色与生命周期选择模板

团队策略构建入口位于 AgentTeamPolicy.java 的 buildTeamPolicy 方法。关键逻辑(对应源码约 128–137 行)如下:

String lifecycleSection = "";
if (builder.role == TeamRole.LEADER) {
    String lifecycleName =
        Objects.equals(builder.lifecycle, "persistent") ? "lifecycle_persistent" : "lifecycle_temporary";
    lifecycleSection = loadTemplate(lifecycleName, language);
}

String template = loadSharedTemplate("system_prompt");
return template.replace("{{member_name_section}}", memberNameSection)
        .replace("{{role_policy}}", rolePolicyText)
        .replace("{{workflow_section}}", workflowSection)
        .replace("{{lifecycle_section}}", lifecycleSection)
        ...

从源码结构可以归纳出两个要点:

  • 仅 Leader 注入生命周期段:lifecycleSection 只在 role == TeamRole.LEADER 时拼接,普通队员(Teammate)的系统提示词不含此段——解散、关闭、待命等收尾动作的执行权在 Leader 手中;
  • 按 lifecycle 取值二选一:lifecycle 取值为 "persistent" 时加载 lifecycle_persistent 模板,否则加载 lifecycle_temporary 模板(loadTemplate 会依据 language 在 en / cn 目录间选择)。

2.2 TeamRail:PromptSection 级别的生命周期注入

在 DeepAgent 化的团队线路(TeamRail)中,生命周期段以独立 PromptSection 注入。参见 TeamRail.java 的 buildTeamLifecycleSection(约 335–347 行):

public static PromptSection buildTeamLifecycleSection(TeamRole role, String lifecycle, String language) {
    if (role != TeamRole.LEADER) {
        return nullValue();
    }
    String lang = normalizeLanguage(language);
    return new PromptSection(LIFECYCLE,
            Map.of(lang, labels(lang, "lifecycle_heading") + "\n\n"
                    + AgentTeamPolicy.loadTemplateForRail(
                            "persistent".equals(lifecycle) ? "lifecycle_persistent" : "lifecycle_temporary", lang)
                            .trim()
                    + "\n"),
            14);
}

这段代码印证了与 AgentTeamPolicy 一致的两条规则:非 Leader 返回 nullValue()(不注入),Leader 则按 "persistent" 与否加载对应模板,并以 LIFECYCLE("team_lifecycle")为 section 标识、优先级序号 14 挂载进系统提示词。也就是说,无论团队走普通 Agent 策略还是 DeepAgent/TeamRail 线路,生命周期模板都会以同一份内容进入 Leader 的上下文。


三、生命周期配置:如何构建一个持久团队

3.1 生命周期常量的定义

LeaderTeammateAgentTeam 在 LeaderTeammateAgentTeam.java 中定义了生命周期常量(约 69–81 行):

public static final String LIFECYCLE_TEMPORARY = "temporary";
public static final String LIFECYCLE_PERSISTENT = "persistent";

同时其 Builder 的默认值为 private String lifecycle = LIFECYCLE_TEMPORARY;(约 466 行),即默认创建的是临时团队;要构建持久团队,必须显式调用 .lifecycle(LeaderTeammateAgentTeam.LIFECYCLE_PERSISTENT) 或直接传入字符串 "persistent"。

3.2 配置示例

以仓库测试 TeamLifecycleCompatibilityTest.java 中的用法为参照,持久团队的构建方式如下:

TeamAgent agent = TeamFactory.createAgentTeam(TeamAgentSpec.builder()
        .name("persistent-team")
        .lifecycle("persistent")
        .members(List.of(
                TeamMemberSpec.builder().name("leader1").role(TeamRole.LEADER).build()))
        .build());

对应的运行时事实(均有测试断言支撑):

  • 构建完成后,团队生命周期状态为 TeamLifecycle.CREATED,start() 后转为 RUNNING(见测试 persistentTeam_lifecycleIsCreatedBeforeStart,TeamLifecycleCompatibilityTest.java);
  • 若不显式指定,spec.getLifecycle() 返回默认值 "temporary"(见测试 temporaryTeam_defaultLifecycle,同文件 L129-L137);
  • 持久模式下,成员状态允许 READY → READY 自环迁移(见测试 persistentTeam_memberReadyToReadyIsValid,同文件 L139-L143)——这为"成员保持就绪、等待下一轮任务"提供了状态机层面的合法性依据。

lifecycle 值最终会写入 TeamAgentSpec(getLifecycle()),并在团队构建时随 spec 传入,供上述模板装载与运行时调度共用。

3.3 持久化与恢复的兼容性

仓库还提供会话恢复场景下的持久团队测试:TeamAgentSessionRecoveryCompatibilityTest.java 中多次以 .name("persistent-team") 构建 agent 并验证其会话恢复行为,说明"持久团队 + 会话中断恢复"是一组被测试覆盖的成熟组合:待命中的持久团队可以承接同一会话的恢复流继续运行。


四、运行时行为:持久团队如何"自动进入待命"

提示词只约束了模型层面的行为,真正让"自动待命"落地的是一套事件驱动机制。核心链路如下:

4.1 完成判定:Leader 空闲轮询触发 TEAM_COMPLETED

团队完成状态由 TeamCompletionHandler(core/src/main/java/com/openjiuwen/agentteams/agent/coordination/handlers/TeamCompletionHandler.java)负责判定。它在 POLL_TASK 轮询事件中执行(仅 Leader 且 Leader 空闲时),通过 TeamBackend.isTeamCompleted() 检查三项完成条件,返回 TeamCompletionSnapshot(成员数、任务数);一旦满足且处于上升沿(isTeamCompletedEmitted 守卫保证每轮只发一次),便通过 Messager 向团队频道发布 TEAM_COMPLETED 事件,payload 携带 team_name、member_count、task_count(见 publishTeamCompleted,约 145–176 行)。

4.2 持久团队专属:concludeCompletedRound 关闭 Leader 流以触发待命

关键差异点位于 onPollTask(约 109–143 行):

// Persistent teams auto-pause on completion: close the leader stream
// so the Runner finally drives finalize -> pause. Temporary teams are
// torn down by their leader via clean_team, not here.
if ("persistent".equalsIgnoreCase(blueprint.lifecycle().orElse(null))
        && !snapshot.isTeamDeleted()) {
    lifecycle.concludeCompletedRound(snapshot.memberCount(), snapshot.taskCount());
}

即:当 blueprint.lifecycle() 为 "persistent" 且团队未被删除时,系统主动调用 concludeCompletedRound 结束 Leader 的流,由 Runner 最终驱动 finalize → pause,团队因此进入待命(standby)状态;而临时团队不走此路径,由 Leader 在收到收尾提示后调用 clean_team 自行拆除。

concludeCompletedRound 的接口契约定义在 TeamLifecycleController.java("Emit a team-completed marker chunk, then close the leader stream",约 32 行),其类注释还指出:当团队被解散时,非 Leader 成员通过 shutdownSelf() 放弃自己的循环;concludeCompletedRound 则专门服务"持久团队完成一轮"的场景——它横跨流 / 会话 / 成员状态三处状态,因此放在生命周期控制器而非轮次控制器中。

4.3 待命提示词:dispatcher.all_done_persistent

Leader 空闲且任务看板清空时,调度器会向其投递收尾提示。参见 TaskBoardHandler.java 的 nudgeIdleAgent(约 226–238 行):

if (incomplete.isEmpty()) {
    String lifecycle = blueprint.lifecycle().orElse(null);
    String prompt = "persistent".equalsIgnoreCase(lifecycle)
            ? I18n.t("dispatcher.all_done_persistent")
            : I18n.t("dispatcher.all_done_temporary");
    round.deliverInput(prompt);
    return;
}

dispatcher.all_done_persistent 的中文文案定义于 I18n.java(约 83–86 行):"所有任务已完成。请汇总本轮工作成果。团队继续保持运行,等待新的任务指令。"——与生命周期模板中"汇总成果 + 保持运行"的指示完全呼应。也就是说,任务清空后 Leader 收到的不是"结束吧",而是"汇总并待命"。

4.4 事件消费与状态机配合

  • TeamCompletionHandler 同时消费 TASK_LIST_DRAINED(任务看板排空)与 TEAM_COMPLETED 事件,分别用于触发完成回调(如团队技能演进 TeamSkillRail.notifyTeamCompleted)与结构化日志记录(onTeamCompleted,约 219–226 行);
  • 待命状态在消息总线层同样可见:测试 CoordinationManagerCompatibilityTest.java 断言团队发布 team_standby 类型事件(payload 含 team_name),验证了"团队进入待命"在事件层面的可观测性;
  • 成员状态机方面,AgentLifecycleHandler.java 负责驱动本机 agent 的生命周期(bootstrap 用户输入、待命时暂停轮询等);其类注释特别强调"持久团队的 Leader 必须能挺过 clean_team 以接受下一轮任务",从反面说明了持久模式对 Leader 存活性的要求。

五、收尾协议背后的工具语义:为什么"广播一次"是高效解

模板强调用 send_message(to="*") 一次性广播,这一约定与 send_message 工具的真实成本模型直接相关。工具描述见 send_message.md,要点如下:

  • to="*" 表示广播到团队频道(类似 IM 的共享群组频道),全体成员可见;描述中明确提示该操作成本随团队规模线性增长,仅应用于全局决策、约束变更或全员公告——本轮总结与待命通知正属于此类;
  • to 为成员名数组时是组播:相同内容分别以点对点消息发给每个目标,成本同样线性增长,且若收件人恰好覆盖除自己外的全部成员,工具会直接拒绝并强制使用 "*" 广播——这是"广播一次"比"逐个致意"更省的根本原因;
  • to 为单个成员名时是点对点私聊,仅发送方与该成员可见。模板禁止"逐个成员致意",正是为了避免 N 次私聊 + N 次致谢回执造成的指数级无意义开销。

另外一点值得注意:队长(Leader)的纯文本输出会直接展示给用户,因此 Leader 回复用户不需要走 send_message;而队员的纯文本对其他 agent 和用户均不可见,队员必须调用该工具才能沟通。 这也解释了为何"总结与待命通知"这类面向全员的公告由 Leader 用广播一次性发出即可。


六、工程实践建议与适用场景

6.1 何时选择持久团队

  • 多轮会话型任务:同一团队需要连续承接用户多轮指令(如持续的调研、迭代开发、运维值班),避免每轮都重建团队、重载记忆;
  • 需要保留团队上下文:成员人设、任务看板历史、协作关系在轮次间保持,团队进入待命而非销毁;
  • 与检查点 / 会话恢复结合:持久团队 + 会话中断恢复的组合已被测试覆盖(见 TeamAgentSessionRecoveryCompatibilityTest.java),适合长时间运行且需要容灾恢复的生产场景。

6.2 实践注意点

  1. 显式指定生命周期:默认值为 temporary,构建持久团队务必调用 .lifecycle("persistent") 或使用 LeaderTeammateAgentTeam.LIFECYCLE_PERSISTENT 常量,避免模板与运行时行为错配;
  2. Leader 收尾三不原则:不调用 shutdown_member、不调用 clean_team、不逐个寒暄——这些行为在持久模式提示词中已明确禁止,运行时 concludeCompletedRound 会自动完成"待命"动作,Leader 只需汇总成果并广播一次;
  3. 关注资源占用:待命团队仍持有流、会话与成员状态,属于"常驻资源",应与临时团队按需求配比,避免大量持久团队闲置堆积;
  4. 利用事件可观测性:TEAM_COMPLETED、team_standby 等事件均可通过消息总线观测,可作为团队状态监控与告警的接入点。

七、源码路径速查

登录后查看全文
agent-core-java