# Agent Team 真实运行调用链 更新时间：2026-04-08 这份文档用于代码 review。它不再写伪代码流程图，而是按当前实现列出从 `spawn_agent_team` 被调用，到 swarms 多 agent 执行，再到结果公告和持久化的真实函数链路。 核心原则： ```text nanobot 负责入口、registry、权限、skills、事件、memory、BridgeResult。 swarms 负责团队架构运行、agent 间讨论/编排、调用 adapter。 ``` ## 主调用链 ```text 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()` 内部有两个分支。 简单/常规任务： ```text 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。 ``` 复杂/开放任务： ```text 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 执行链 ```text 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。 ``` ## 成员执行链 ```text 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 注入链 ```text 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 后的任务文本。 ``` ## 结果返回链 ```text 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 的架构： ```text GroupChat SequentialWorkflow ConcurrentWorkflow AgentRearrange MixtureOfAgents HierarchicalSwarm ``` `GraphWorkflow` / `HeavySwarm` 暂不直接放行，因为当前 vendored `SwarmRouter` 的相关 factory 还不能稳定消费 nanobot 提供的 `NanobotAgentAdapter`、registry、skills 和权限边界。 ## 文件职责速查 ```text 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 等共享类型。 ```