RocketRide 的 CrewAI 节点家族：Agent、Manager 与 Subagent 的编排实践

【免费下载链接】rocketride-serverHigh-performance AI pipeline engine with a C core and 50 Python-extensible nodes. Build, debug, and scale LLM workflows with 13 model providers, 8 vector databases, and agent orchestration, all from your IDE. Includes VS Code extension, TypeScript/Python SDKs, and Docker deployment.项目地址https://gitcode.com/gh_mirrors/ro/rocketride-server点击查看免费下载本篇技术指南围绕 RocketRide 仓库中的agent_crewai节点家族展开它提供三个相互配合的节点——独立单 Agent 的CrewAI Agent、负责分层委派的CrewAI Manager以及仅供 Manager 调用的CrewAI Subagent。文章将完整讲解三种节点的连接方式、数据通道Lane、工具注册run_agent、全部配置字段与 Schema并结合源码剖析其底层实现CrewAI 框架绑定、进程级 kickoff 运行器、事件转发与工具包装让读者能够在 RocketRide 流水线中独立搭建从单 Agent 问答到Manager 多专家 Subagent 分层协作的完整方案。一、节点家族概览什么时候用哪一个CrewAI 是一个以Agent、Task、Crew三个对象为核心来组织语言模型工作与工具调用的编排框架。RocketRide 的这三个节点在使用 CrewAI 对象的同时不要求你在 CrewAI 侧配置任何模型供应商——LLM 与工具全部通过 RocketRide 自身的llm/tool连接注入这是本节点家族与原生 CrewAI 用法最核心的区别。三种节点的分工如下依据 README 与三个子包的 driver 实现节点角色典型使用场景CrewAI Agent独立单 Agent接收一个问题构建一个 Agent 一个 Task的串行 Crew把结果写到answers也可以作为父 Agent 的工具被调用CrewAI Manager分层委派者收集已连接 Subagent 的描述符descriptor构建分层 Crew把综合后的结果返回到同一通道或以工具结果返回CrewAI Subagent被管专家不可直接运行仅向 Manager 暴露describe()由 Manager 用其自身的 LLM 与可选工具连接构建 Agent Task 来执行委派任务选型建议单任务、不需要专家分工时选Agent任务需要显式的命名专家分工时选Manager 多个 Subagent的组合。从源码看Subagent 是Manager-only组件它的_run直接抛出NotImplementedError见 subagent.py且其services.subagent.json未声明questions通道、classType只包含crewai因此既不能从问题通道直达也不能被当作工具调用。二、连接ConnectionsLLM、工具与 crewai 通道三种节点都拥有default配置档案profile。三个连接定义来自各子包的services.*.json中的invoke段汇总如下。CrewAI Agent连接必填说明llm是独立 Agent 使用的 LLMmin: 1tool否通过控制平面调用control-plane invocation提供给 Agent 的工具min: 0CrewAI Manager连接必填说明llm是Manager 自身使用的 LLMmin: 1tool否通过控制平面调用提供给 Manager 自身的横切工具min: 0crewai是已连接的 CrewAI Subagent 节点供 Manager 描述describe与委派min: 1CrewAI Subagent连接必填说明llm是Manager 委派到该 Subagent 时使用的 LLMmin: 1tool否通过控制平面调用提供给该 Subagent 的工具min: 0需要注意两条边界规则Manager 出错条件未连接任何 Subagentcrewai通道为空或 describe 扇出后没有任何 Subagent 响应Manager 都会以错误终止。源码中对应两处RuntimeError抛出manager.py 与 manager.py。工具归属Subagent 的tool连接属于被委派的专家自己不属于ManagerManager 自己的tool连接是横切工具。二者在构建 Crew 时会被严格区分详见第六节工具执行。三、数据通道LanesLane inLane out说明questionsanswersCrewAI Agent运行独立 Crew 并输出结果questionsanswersCrewAI Manager运行分层 Crew 并输出结果CrewAI Subagent不声明任何 Lane。它必须通过crewai连接接到 Manager 上若有人直接向它发送问题会被判定为对 Subagent 的非法使用而被拒绝对应其_run中抛出的NotImplementedError。四、作为工具As a toolnodeId.run_agentCrewAI Agent 与 CrewAI Manager 各自注册一个以自身节点 ID 为前缀的工具函数nodeId.run_agent由各子包IInstance.py中的tool_function装饰器声明例如 agent 的 IInstance.py。CrewAI Subagent 不是工具不暴露任何run_agent。函数说明nodeId.run_agentCrewAI Agent为一条委派查询运行独立 Agent返回其 Agent 结果nodeId.run_agentCrewAI Manager为一条委派查询运行 Manager 及其连接的 Subagent Crew返回其 Agent 结果两个函数共通的调用契约入参必须是一个对象包含非空query: string可选的context: objectcontext会被编码为RocketRide.agent.tool_context.v1条目返回值是{content, meta, stack}结构而不是写answers通道非对象输入、空白 query 或非对象 context 会抛出ValueError见 agent 的 IInstance.py当配置了agent_description时该描述会被前置拼接到注册的工具描述中供父 Agent 决定何时委派同样见 agent 的 IInstance.py。五、配置详解Configuration所有字段的默认值、类型与条件显示规则都记录在各子包的services.*.json中并由Config.getNodeConfig在beginGlobal阶段解析应用见 agent 的 IGlobal.py。建议的起步顺序是先接好 LLM以及 Manager 到 Subagent 的crewai连接、工具连接跑通基本角色后再开启 Advanced Mode。所有高级文本字段留空时会回退到 driver 内置的默认 goal、backstory 与 expected-output 文本。5.1 Agent descriptionAgent 描述CrewAI Agent 与 CrewAI Manager 都会把这个字段暴露给父 Agent通过run_agent工具描述。它描述的是独立 Agent 本身或Manager 及其 Crew 整体的真实职责、输入与专长让父 Agent 能判断何时该委派。一个具体的描述比空泛的更有用例如Coordinates research and fact-checking specialists协调研究与事实核查专家。当没有任何节点会把这个节点当作工具调用时可以留空。5.2 Instructions指令Agent指令会以项目符号列表追加到 CrewAI Agent 的 backstory 之后Manager通过 manager backstory 引导其委派策略Subagent成为该专家 backstory 的一部分。建议写简短、持久的约束例如 cite the evidence supplied by tools——引用工具提供的证据而不要重复 Advanced Mode 里已经配置好的角色与任务文本。源码层面所有指令统一由CrewBase._merge_instructions完成拼接空条目被剔除非空时以Instructions:\n- item形式追加crewai_base.py。5.3 Require tool call要求工具调用在 Agent 与 Manager 上默认关闭开启后任何不调用工具就直接作答的运行都会因 guard 错误而失败对 Manager 而言被委派的 Subagent 产生的工具调用也计入同一个 guard源码依据Manager 构建 sub-context 时把父级的invoked_tools计数共享给各 Subagent见 manager.py当合法答案可能不需要任何工具调用时请保持关闭。此选项专为确定性与事实锚定优先的流水线设计防止输出无依据的叙述式答案。5.4 Advanced Mode高级模式默认关闭。开启后才会暴露 CrewAI 的 Agent 与 Task 字段Agent/Subagent 暴露role/goal/backstory/task_description/expected_outputManager 暴露goal/backstory/planning见各自services.json中advanced_mode的conditional段。仅在默认的 Assistant/Specialist 行为与内置回退文本不够用时开启。注意开启 Advanced Mode 并不会让 Subagent 变成可独立运行——它依然是 Manager-only 组件。5.5 Agent 与 Task 字段Agent and task fields独立 AgentCrewAI AgentRole、Goal、Backstory、Task、Expected Output分别映射到为每次问题构建的 CrewAIAgent(role.../goal.../backstory...)与Task(description.../expected_output...)Task 留空时进入的问题本身就成为任务Task 已配置时问题被追加为User request:上下文源码见 agent.py当每次运行有稳定任务分配时配置 Task通用助手场景则留空。SubagentCrewAI SubagentRole是 Manager 交给 CrewAI 的专家名Goal、Backstory、Task、Expected Output定义被委派的 Agent 与 TaskSubagent 的 Task 留空时默认使用{user_request}配置任务时可以使用 CrewAI 模板变量如{user_request}这些花括号在 Manager 组装时会保留以交给 CrewAI 的_interpolate_inputs()做模板替换manager.py建议使用唯一且具有描述性的 Role任务文本要指明该专家的产出物——Manager 正是依靠描述符来组装其 Crew 的。ManagerCrewAI ManagerManager Goal与Manager Backstory配置其委派者 Agent需要特定委派策略或领域框架时设置它们否则使用内置的管理 goal 与 backstory源码常量为_MGR_GOAL/_MGR_BACKSTORY见 manager.py。5.6 Crew PlanningCrew 规划Manager 专属选项默认关闭。开启后 CrewAI 会在分层 Crew 之前先运行一个 planner把生成的逐步计划注入各任务代价是每次 kickoff 多一次 LLM 调用。重要限制只有当连接的 LLM 能稳定返回 CrewAI 规划转换所需的 JSON 时才应开启——如果模型输出散文式计划整个运行会以Failed to get the Planning output失败源码对这条失败路径有详细注释见 manager.py。六、源码级实现剖析6.1 框架绑定CrewBase与 HostInvokeLLM / HostTool所有 driverCrewAgent、CrewManager、CrewSubagent继承自共享基类CrewBasecrewai_base.py。它把 RocketRide 的主机通道包装成 CrewAI 可用的对象_build_crew_llm(context, role)返回一个内部类HostInvokeLLM(BaseLLM)实例。它的call/acall转发到self.call_llm(context, messages, role..., stop_words...)acall通过asyncio.to_thread桥接到同步主机通道避免阻塞共享 kickoff 循环supports_function_calling()恒返回False——因为主机通道是文本进/文本出声明原生工具调用会把 CrewAI 导向本包装无法兑现的路径False能强制所有工具调用走 ReAct 路径crewai_base.py。_build_crew_tools(context, tool_descriptors)把主机工具描述符转成HostTool(BaseTool)实例。每个工具基于其声明的 JSON input schema 动态构建一个 Pydanticargs_schemacreate_model以保留真实的参数名避免 CrewAI 的参数过滤tool_usage.py静默丢弃未声明的键JSON Schema 的类型会被映射为 Python 注解string→str、integer→int、number→float、boolean→bool等无法映射的类型安全回退为Anycrewai_base.py。Schema 不会复制进 description——CrewAI 会自己把 args_schema 渲染成 prompt 中的 Tool Arguments: 块重复粘贴反而给模型两套需要对齐的契约。6.2 进程级 kickoff 运行器CrewRunnerCrewAI 的进程级单例crewai_event_bus、EventListener、ConsoleFormatter、Telemetry在多线程并发 kickoff 下不安全。因此所有 CrewAI 节点的crew.akickoff(...)都被统一提交到一个跑在单条 daemon 线程上的 asyncio 事件循环CrewKickoffLoop中执行crewai_runner.pyCrewRunner.submit(context, coro)用asyncio.run_coroutine_threadsafe提交包装协程包装协程先把crewContext这个ContextVar设为当前运行的AgentContext再 await 真正的 kickoff由于 asyncio 是单线程协作调度CrewAI 内部逻辑永远只在那一条线程上执行彻底消除竞争真正的并发仍发生在 await 点主要是 LLM 调用因此多个会话可以重叠 I/O 而互不干扰get_shared_runner()是进程级单例的惰性获取入口首次调用同时会安装持久事件监听器crewai_runner.py。模块顶部还打了两处兼容性补丁import 时应用_patch_crewai_planning把Crew._handle_crew_planning在检测到运行中事件循环时改到ThreadPoolExecutor工作线程执行_patch_crewai_delegation为DelegateWorkTool/AskQuestionTool补充异步_arun/_aexecute实现解决分层 Crew 在异步循环内退回同步execute_task而抛RuntimeError的问题crewai_base.py。6.3 事件转发CrewListener进程级单例监听器crewai_listener.py遍历BaseEvent的整棵子类树在每个相关事件类上注册同一个_dispatch处理器。_dispatch从crewContext读取发起运行的AgentContext把事件以thinkingSSE 消息转发给该运行的 invoker。由于 CrewAI 的 bus 用contextvars.copy_context().run(...)分发同步 handlercrewContext会自动传播到 handler 工作线程。以下事件被有意不转发LLMStreamChunkEvent流式分块会淹没 UI以及AgentLogsStartedEvent/AgentLogsExecutionEvent格式化终端树噪声。其余事件会映射为人类可读标签例如crew_kickoff_started → Crew started、task_started → Task started、tool_usage_started → Calling {tool_name}...等crewai_listener.py。6.4 Manager 执行流程Manager 的运行分五步manager.py对crewai通道上每个显式连接的 Subagent 调用describe扇出按nodeId逐个 invoke收集描述符为每个描述符构建一个 CrewAIAgentTask每个 Subagent 获得由AgentHostServices(d.invoke)构建的独立AgentContextLLM/工具调用路由回该 Subagent 自己的通道构建 Manager Agentallow_delegationTrue每个专家allow_delegationFalse专家任务的直接工具列表被覆盖为 manager 的工具列表task_obj.tools list(manager_tools)这样委派真正由 Manager 发出而不是让 Manager 直接占用专家工具——因为 CrewAI 的_create_manager_agent会拒绝携带工具的 Managermanager.py组装Process.hierarchical的 Crew 并提交 kickoff结果合成result.raw在分层模式下其实只是某个被委派任务的原始输出CrewAI 的_create_crew_output取最后一个非空任务输出因此 Manager 必须用自己的 LLM 通道显式执行合成步骤_synthesize_delegate_findings把每个 delegate 的干净输出按### role标注为 findings恰好一个 finding 时原样返回避免无谓的二次 LLM 往返两个及以上时发起一次综合调用合成失败则降级为按序拼接 findings绝不静默丢弃已付出的委派工作manager.py。最终答案优先取最后一个已完成任务的 cleaned output以避开整个分层 ReAct 轨迹_strip_react_preamble会剥离Final Answer:之后的痕迹或提取最后一个完整 JSON 块见 manager.py。这一合成逻辑是仓库回归测试的重点nodes/test/agent_crewai/test_manager_synthesis.py专门验证Manager 不再返回单个 Subagent 的原始输出而是三路 findings 的合成结果。6.5 工具执行CrewAI LLM 包装器HostInvokeLLM通过节点的llm连接委派调用并声明不支持原生 function calling因此 CrewAI 走其 ReAct 工具路径。每个连接的工具被包装为带参数 schema 的HostTool包装工具抛出的异常会被捕获并作为包含error与type字段的对象返回给 CrewAIcrewai_base.py让模型能看到错误原因并尝试修正。七、参数 Schema 全表以下三张表由nodes:docs-generate自动生成并同步在 agent_crewai 目录 下的services.agent.json/services.manager.json/services.subagent.json中是节点在配置面板里暴露的全部字段。CrewAI Agentservices.agent.json字段类型说明默认值advanced_modebooleanAdvanced Mode直接暴露 CrewAI Agent 与 Task 配置falseagent_crewai.agent_config_headernullAgent Config分组标题nullagent_crewai.task_config_headernullTask Config分组标题nullagent_descriptionstringAgent description描述该 Agent 的职责与能力帮助父 Agent 选择并正确调用它backstorystringBackstoryAgent 人设的背景上下文映射Agent(backstory...)空expected_outputstringExpected Output期望输出格式描述映射Task(expected_output...)空goalstringGoal该 Agent 要达成的目标映射Agent(goal...)空instructionsarrayInstructions附加指令引导 Agent 行为空require_tool_callbooleanRequire tool call要求作答前至少调用一次工具否则 guard 失败falserolestringRoleAgent 角色名如 Financial Analyst映射Agent(role...)空task_descriptionstringTaskAgent 应做什么留空时使用传入问题映射Task(description...)空CrewAI Managerservices.manager.json字段类型说明默认值advanced_modebooleanAdvanced Mode直接暴露 CrewAI Manager Agent 配置falseagent_descriptionstringAgent description该 Manager 其 Subagent Crew 的职责供父 Agent 通过nodeId.run_agent决定何时调用backstorystringManager BackstoryManager 人设背景映射Agent(backstory...)空goalstringManager GoalManager 要达成的目标映射Agent(goal...)空instructionsarrayInstructions引导 Manager 委派策略的附加指令空planningbooleanCrew PlanningCrew 执行前运行 planner 注入逐步计划。默认关闭planner 要求 LLM 返回符合 CrewAI 计划 schema 的 JSON散文式回答会让整个运行以Failed to get the Planning output失败且每次 kickoff 多一次 LLM 调用。仅在模型能稳定输出合法 JSON 时开启falserequire_tool_callbooleanRequire tool call要求至少一次工具调用含委派给 Subagent 的调用才能作答否则 guard 失败falseCrewAI Subagentservices.subagent.json字段类型说明默认值advanced_modebooleanAdvanced Mode直接暴露 CrewAI Agent 与 Task 配置falseagent_crewai_subagent.agent_config_headernullAgent Config分组标题nullagent_crewai_subagent.task_config_headernullTask Config分组标题nullbackstorystringBackstory专家能力背景映射Agent(backstory...)空expected_outputstringExpected Output被委派时的产出格式描述映射Task(expected_output...)空goalstringGoal被委派时该 Sub-agent 的目标映射Agent(goal...)空instructionsarrayInstructionsManager 委派时的附加指令空rolestringRole专家角色名如 Financial AnalystManager 据此路由委派映射Agent(role...)空task_descriptionstringTask被 Manager 委派时做什么运行时追加用户请求上下文映射Task(description...)空八、依赖与落地方式Python 依赖crewai1.14.1,2见 requirements.txt。该版本上限是刻意设置的CrewAI 在小版本中会移动BaseLLM契约例如 1.15.x 的BaseLLM移除了supports_function_calling()但多个调用点仍无保护地调用它会破坏HostInvokeLLM的适配逻辑。共享的requirements.txt位于agent_crewai/父级保证三个子包只安装一次crewai见 agent 的 IGlobal.py。在流水线中使用仓库示例examples/llm-benchmark.pipe展示了以provider: agent_crewai声明节点、从llm通道接入模型、并读取answers通道结果的最小拓扑examples/incorrect/下的多个.pipe文件则从反面演示了该节点相关的错误接线方式可用于理解合法拓扑的约束。验证与回归测试nodes/test/agent_crewai/目录下有针对性测试包括test_manager_synthesis.pyManager 综合结果回归、test_manager_planning.py规划失败路径、test_manager_tool_scoping.py工具作用域、test_tool_schema.py工具参数 schema 构建、test_stop_words.pyReAct 停止词截断与test_llm_contract.pyLLM 包装契约是理解各实现细节与边界行为的最佳入口。九、实操建议与常见陷阱从单 Agent 起步先只接llm把 Agent 的questions → answers跑通需要工具时再接tool并确认模型走 ReAct 路径后工具名与参数名能在args_schema中保留。再引入 Manager Subagent给每个 Subagent 一个唯一且描述性的 Role任务文本明确产出物Manager 的crewai通道至少连接一个 Subagent否则运行直接报错。工具作用域不要混淆Subagent 的工具属于专家自己Manager 的工具是横切工具不要指望 Manager 直接使用专家的工具委派由 Manager 的DelegateWorkTool完成。Crew Planning 谨慎开启只有确认模型能稳定输出 JSON 计划时才开启否则一次散文式回答就会让整个运行以Failed to get the Planning output终止。Require tool call 用于确定性场景需要答案必须有工具依据时开启Manager 场景下 Subagent 的调用也计入普通闲聊式问答保持关闭。进程级运行器无需干预CrewRunner是惰性创建、进程级共享的单例daemon 线程随解释器退出自动结束同一进程内的多个 CrewAI 节点共享它无需也无法手动管理。至此你已掌握 RocketRide 中 CrewAI 节点家族从单 Agent到Manager 多专家 Subagent 分层编排的完整接入方式、全部配置语义与底层实现原理可以在自己的流水线中按需组合这三种节点构建可复用、可调试的 LLM 工作流。赞分享【免费下载链接】rocketride-serverHigh-performance AI pipeline engine with a C core and 50 Python-extensible nodes. Build, debug, and scale LLM workflows with 13 model providers, 8 vector databases, and agent orchestration, all from your IDE. Includes VS Code extension, TypeScript/Python SDKs, and Docker deployment.项目地址https://gitcode.com/gh_mirrors/ro/rocketride-server点击查看免费下载相关推荐RocketRide 中 CrewAI Subagent 节点完全指南被 Manager 托管的层级委托子代理RocketRide 中 CrewAI Subagent 节点完全指南被 Manager 托管的层级委托子代理 本篇技术指南围绕 RocketRide 仓库中RocketRide DeepAgent Subagent 节点深度解析构建由 Deep Agent 编排的分层子智能体流水线RocketRide DeepAgent Subagent 节点深度解析构建由 Deep Agent 编排的分层子智能体流水线 DeepAgent SubagRocketRide 中的 CrewAI Agent 节点在管道中运行单智能体 CrewAI Crew 的完整指南RocketRide 中的 CrewAI Agent 节点在管道中运行单智能体 CrewAI Crew 的完整指南 CrewAI Agent 是 Rocket上一篇libsndfile常见问题解答解决音频处理中的痛点下一篇推荐使用 React Idle Timer智能管理用户活动的利器创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考