beaver_project/app-instance/backend/nanobot/agent_team/runtime_pseudocode_flow.md

Agent Team 真实运行调用链

更新时间：2026-04-08

这份文档用于代码 review。它不再写伪代码流程图，而是按当前实现列出从 spawn_agent_team 被调用，到 swarms 多 agent 执行，再到结果公告和持久化的真实函数链路。

核心原则：

nanobot 负责入口、registry、权限、skills、事件、memory、BridgeResult。
swarms 负责团队架构运行、agent 间讨论/编排、调用 adapter。

主调用链

SpawnAgentTeamTool.execute()
作用：LLM/tool 层入口，接收 task / label / skills。
-》 DelegationManager.dispatch_agent_team()
作用：把工具调用转换成 agent_team 委派请求，固定 mode="agent_team"、strategy="group"。
-》 DelegationManager._dispatch()
作用：生成 run_id、display_label、origin，创建后台 asyncio task，立即返回“Agent team started”。
-》 DelegationManager._run_dispatch()
作用：后台真正执行 agent_team 分支；发出团队开始事件，并把任务交给 orchestrator。
-》 AgentTeamOrchestrator.run_task()
作用：agent team 薄编排入口；只做 plan -> swarms -> memory，不自建 team runtime。
-》 SwarmsRunPlanner.plan()
作用：生成 SwarmsRunSpec，决定 swarm_type、agent_ids、skills、rules、max_loops。
-》 SwarmsBridge.run_spec()
作用：发出“启动 swarms runtime”事件，执行 swarms，并把 swarms 输出转成 BridgeResult。
-》 SwarmsBridge._run_swarms()
作用：把 SwarmsRunSpec.agent_ids 转成 AgentDescriptor，再包成 NanobotAgentAdapter。
-》 load_swarms_runtime()
作用：懒加载 vendored third_party/swarms，取 AutoSwarmBuilder / SwarmRouter / GroupChat。
-》 swarms.SwarmRouter(...)
作用：创建 swarms 统一路由器，传入 nanobot adapters、swarm_type、rules、max_loops。
-》 SwarmRouter.run(task=...)
作用：交给 swarms 运行对应架构，例如 GroupChat / SequentialWorkflow / ConcurrentWorkflow。
-》 NanobotAgentAdapter.run()
作用：swarms 调用每个 agent adapter；adapter 把 swarms conversation context 转回 nanobot 成员任务。
-》 DelegationManager._run_team_member_for_swarms()
作用：为该成员创建 child run，做权限检查，发 agent started/finished 事件。
-》 DelegationManager._execute_descriptor()
作用：真正执行成员 agent；local_prompt/local_fallback 走 local_executor，A2A agent 走 A2AClient。
-》 local_executor.run_local_task() 或 A2AClient.run_task()
作用：成员 agent 产出 AgentRunResult。
-》 NanobotAgentAdapter.run()
作用：收集 AgentRunResult 到 adapter.results，并把 summary 返回给 swarms。
-》 SwarmRouter.run(task=...)
作用：swarms 收集所有 adapter 响应，返回 raw_output/transcript。
-》 SwarmsBridge._normalize_swarms_output()
作用：优先用 adapter.results 生成可读 SwarmsRunResult.summary，并保留 raw_output。
-》 SwarmsBridge.run_spec()
作用：构造 BridgeAttempt、candidate ProcedureRecord、BridgeResult。
-》 AgentTeamOrchestrator.run_task()
作用：成功时 ProcedureMemory.record_candidate()，随后 RunMemory.record_run()，再返回 BridgeResult。
-》 DelegationManager._run_dispatch()
作用：发团队 finished 事件，并调用 _announce_orchestrator_result()。
-》 DelegationManager._announce_orchestrator_result()
作用：把 BridgeResult 组装成给主 agent 的总结消息。
-》 DelegationManager._publish_announcement() 或 _notify_direct_announcement()
作用：通过 bus 回流主 agent，或直连回调到本地会话。
-》 DelegationManager._emit_direct_user_message()
作用：如果有 process event sink，给 UI 发即时可见完成消息。

Plan 分支

SwarmsRunPlanner.plan() 内部有两个分支。

简单/常规任务：

SwarmsRunPlanner.plan()
作用：读取 ProcedureMemory.match_procedure(task)，判断不需要 AutoSwarmBuilder。
-》 SwarmsRunPlanner._simple_required_roles()
作用：从 skills 生成角色，例如 implementation specialist / test specialist；没有 skills 则用 general specialist / synthesis analyst。
-》 TargetResolver.resolve_team_targets()
作用：根据 task、skills、required_specialists 选择已有 registry agents；缺人时调用 provisioning。
-》 AgentRegistry.suggest_agents() / AgentRegistry.get_agent()
作用：从 workspace/plugin/skill/local registry 中查找可执行 agent。
-》 ProvisioningManager.ensure_local_specialist()
作用：缺少合适 agent 时创建 managed local A2A specialist，并写入 workspace agent registry。
-》 SwarmsRunSpec(...)
作用：返回默认 GroupChat 运行规格，带 agent_ids、skills、rules、target_plan metadata。

复杂/开放任务：

SwarmsRunPlanner.plan()
作用：如果任务较长、命中复杂关键词，或有 ProcedureMemory hint，则进入自动建队。
-》 SwarmsRunPlanner._run_auto_swarm_builder()
作用：调用 swarms.AutoSwarmBuilder 生成 router config 建议。
-》 SwarmsRunPlanner._auto_builder_prompt()
作用：把 task、skills、memory_hint 和硬约束写入 AutoSwarmBuilder prompt。
-》 SwarmsPolicy.validate_auto_config()
作用：只允许安全的 swarm_type，限制 max_agents/max_loops，剥掉 tools、MCP、API key 等越权字段。
-》 SwarmsRunPlanner._roles_from_auto_config()
作用：从 AutoSwarmBuilder 输出提取需要的角色描述。
-》 TargetResolver.resolve_team_targets()
作用：把角色描述映射成 nanobot registry 中真实可执行的 agent_ids。
-》 SwarmsRunPlanner._rearrange_flow()
作用：如果 swarm_type 是 AgentRearrange，则用 safe_swarms_name(agent_id) 生成 flow。
-》 SwarmsRunSpec(...)
作用：返回经过 policy 清洗后的 swarms 运行规格。

Swarms 执行链

SwarmsBridge.run_spec()
作用：接收 SwarmsRunSpec，发 process_run_progress(stage_label="启动 swarms runtime")。
-》 SwarmsBridge._run_swarms()
作用：解析 spec.agent_ids，构造 adapters，并实例化 SwarmRouter。
-》 NanobotAgentAdapter.__post_init__()
作用：设置 swarms 可识别的 agent_name/name/__name__/system_prompt。
-》 SwarmsBridge._rules_with_skills()
作用：生成 swarms rules，加入“不要新增工具/凭证/外部 endpoint”和 skills 约束。
-》 SwarmsBridge._task_with_skills()
作用：把 spec.task 和 spec.skills 合并成传给 SwarmRouter.run(task=...) 的任务文本。
-》 SwarmRouter.run(task=...)
作用：swarms 按 spec.swarm_type 创建并运行实际 swarm。
-》 GroupChat / SequentialWorkflow / ConcurrentWorkflow / AgentRearrange / MixtureOfAgents / HierarchicalSwarm
作用：由 swarms 负责具体多 agent 架构的讨论、顺序、并行、动态流程或层级协作。
-》 NanobotAgentAdapter.run()
作用：当 swarms 需要某个 agent 响应时，调用 nanobot adapter。
-》 SwarmsBridge._normalize_swarms_output()
作用：把 swarms raw_output 和 adapter.results 合并成 SwarmsRunResult。
-》 SwarmsBridge._candidate_procedure()
作用：成功时构造可选 ProcedureRecord，供 ProcedureMemory 学习复用。
-》 BridgeResult(...)
作用：统一返回 success、summary、member_results、candidate_procedure、attempts、raw。

成员执行链

NanobotAgentAdapter.run(task)
作用：接收 swarms 传入的 conversation/task。
-》 NanobotAgentAdapter._task_with_skills()
作用：把 skills 注入成员任务文本，形成 delegated_task。
-》 asyncio.run_coroutine_threadsafe(member_runner(...))
作用：从 swarms 的同步调用线程切回 nanobot 当前事件循环。
-》 DelegationManager._run_team_member_for_swarms(descriptor, task, parent_run_id, skills)
作用：创建 child_run_id，保持父子 process tree。
-》 DelegationManager._ensure_descriptor_allowed()
作用：检查 local/plugin/A2A agent 是否允许被委派。
-》 DelegationManager._emit_agent_started()
作用：发出成员开始事件。
-》 DelegationManager._execute_descriptor()
作用：根据 AgentDescriptor.kind / protocol 选择执行方式。
-》 local_executor.run_local_task()
作用：执行 local_prompt / local_fallback agent，并传入 skill_context、skill_names、progress_callback。
-》 A2AClient.run_task()
作用：执行远端或本地 gateway 暴露的 A2A agent。
-》 DelegationManager._emit_agent_finished()
作用：发出成员完成事件。
-》 NanobotAgentAdapter.run()
作用：把 AgentRunResult 存入 adapter.results；成功时返回 result.summary，失败时返回 error 文本给 swarms。

skills 注入链

SpawnAgentTeamTool.execute(skills)
作用：接收工具参数里的 skills。
-》 DelegationManager.dispatch_agent_team(skills=skills)
作用：把 skills 放进后台 dispatch 参数。
-》 DelegationManager._dispatch(skills=skills)
作用：把 skills 保存到后台 task 调用参数。
-》 DelegationManager._run_dispatch(skills=skills)
作用：把 skills 传给 AgentTeamOrchestrator.run_task()。
-》 AgentTeamOrchestrator.run_task(skills=skills)
作用：把 skills 传给 planner 和 swarms bridge。
-》 SwarmsRunPlanner.plan(skills=skills)
作用：skills 参与角色选择和 AutoSwarmBuilder prompt。
-》 SwarmsRunSpec.skills
作用：skills 固化到运行规格，供 events、rules、task、adapter 使用。
-》 SwarmsBridge._rules_with_skills()
作用：把 skills 写入 SwarmRouter rules。
-》 SwarmsBridge._task_with_skills()
作用：把 skills 写入 SwarmRouter.run(task=...) 的任务文本。
-》 NanobotAgentAdapter._task_with_skills()
作用：把 skills 写入每个成员看到的 delegated task。
-》 DelegationManager._execute_descriptor(skill_names=skills)
作用：本地 agent 获得 skill_context / skill_names；A2A agent 获得 augment 后的任务文本。

结果返回链

SwarmsBridge._normalize_swarms_output()
作用：生成 SwarmsRunResult(summary, raw_output, member_results)。
-》 SwarmsBridge.run_spec()
作用：生成 BridgeAttempt 和 BridgeResult。
-》 AgentTeamOrchestrator.run_task()
作用：写 ProcedureMemory 和 RunMemory。
-》 DelegationManager._emit_group_finished()
作用：把团队 run 标记为 done/error，metadata 带 attempts 和成员状态。
-》 DelegationManager._announce_orchestrator_result()
作用：把 BridgeResult 整理成主 agent 可读的系统消息。
-》 DelegationManager._publish_announcement()
作用：announce_via_bus=True 时，把消息 publish 到 inbound bus，让主 agent 继续总结。
-》 DelegationManager._notify_direct_announcement()
作用：announce_via_bus=False 时，直接调用本地回调回流会话。
-》 DelegationManager._emit_direct_user_message()
作用：有 process event sink 时，给前端/UI 发一条即时完成消息。

当前放行的 swarms 架构

SwarmsPolicy.allowed_swarm_types 当前只放行能消费 nanobot adapters 的架构：

GroupChat
SequentialWorkflow
ConcurrentWorkflow
AgentRearrange
MixtureOfAgents
HierarchicalSwarm

GraphWorkflow / HeavySwarm 暂不直接放行，因为当前 vendored SwarmRouter 的相关 factory 还不能稳定消费 nanobot 提供的 NanobotAgentAdapter、registry、skills 和权限边界。

文件职责速查

agent/tools/spawn.py
作用：定义 spawn_agent_team 工具入口。

agent/delegation.py
作用：后台调度、process events、成员执行、结果公告。

agent_team/orchestrator.py
作用：agent team 主 glue，负责 plan -> swarms -> memory。

agent_team/swarms_planner.py
作用：生成 SwarmsRunSpec；需要时调用 AutoSwarmBuilder。

agent_team/swarms_policy.py
作用：清洗 AutoSwarmBuilder 输出，限制 swarm_type、agents、loops 和越权字段。

agent_team/target_resolver.py
作用：把角色需求解析成真实 agent_ids。

agent_team/provisioning.py
作用：缺少合适成员时创建 managed local A2A specialist。

agent_team/swarms_adapter.py
作用：懒加载 vendored swarms，并把 nanobot agent 包成 swarms 可调用 adapter。

agent_team/swarms_bridge.py
作用：构造 SwarmRouter、运行 swarms、归一化 BridgeResult。

agent_team/memory.py
作用：记录 RunMemory / ProcedureMemory。

agent_team/types.py
作用：定义 SwarmsRunSpec、SwarmsRunResult、BridgeAttempt、BridgeResult 等共享类型。