openJiuwen 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:
- Summarize the current round of work results
- Do not close members or dissolve the team
- 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.
模板以三句话点明持久团队的三大行为规则:
- 汇总当轮成果:任务全部完成后,队长(Leader)需先汇总本轮工作结果;
- 不解散团队:不得调用
shutdown_member关闭成员、不得调用clean_team解散团队; - 自动进入待命:团队保持运行,等待用户下发新一轮任务。
此外模板还规定了高效收尾协议:使用 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 实践注意点
- 显式指定生命周期:默认值为
temporary,构建持久团队务必调用.lifecycle("persistent")或使用LeaderTeammateAgentTeam.LIFECYCLE_PERSISTENT常量,避免模板与运行时行为错配; - Leader 收尾三不原则:不调用
shutdown_member、不调用clean_team、不逐个寒暄——这些行为在持久模式提示词中已明确禁止,运行时concludeCompletedRound会自动完成"待命"动作,Leader 只需汇总成果并广播一次; - 关注资源占用:待命团队仍持有流、会话与成员状态,属于"常驻资源",应与临时团队按需求配比,避免大量持久团队闲置堆积;
- 利用事件可观测性:
TEAM_COMPLETED、team_standby等事件均可通过消息总线观测,可作为团队状态监控与告警的接入点。
七、源码路径速查
- 生命周期模板(英文 / 中文):agent/prompts/en/lifecycle_persistent.md、agent/prompts/cn/lifecycle_persistent.md,临时团队对照见 lifecycle_temporary.md
- 模板装载: AgentTeamPolicy.java、TeamRail.java
- 生命周期常量与 Builder 默认值: LeaderTeammateAgentTeam.java、L463-L466
- 完成判定与自动待命: TeamCompletionHandler.java、TeamLifecycleController.java
- 待命提示投递: TaskBoardHandler.java、I18n.java
- 工具语义: send_message.md、shutdown_member.md、clean_team.md
- 测试用例: TeamLifecycleCompatibilityTest.java、TeamAgentSessionRecoveryCompatibilityTest.java、CoordinationManagerCompatibilityTest.java