Yuxi 子智能体（SubAgent）管理指南：配置、调用与运行时边界全解析

Yuxi 子智能体SubAgent管理指南配置、调用与运行时边界全解析【免费下载链接】Yuxi可私有部署的多租户知识智能体平台统一 RAG、知识图谱、多智能体、MCP/Skills、沙盒与权限管理。Self-hosted knowledge agent platform for RAG, knowledge graphs and multi-agent workflows.项目地址: https://gitcode.com/GitHub_Trending/yu/Yuxi子智能体是 Yuxi 知识智能体平台中一类特殊的 Agent它仍然是agents表中的一级智能体只是被打上is_subagenttrue标记并使用专用的SubAgentBackend后端运行。本文以官方文档 docs/agents/subagents-management.md 为骨架结合仓库源码subagent_task.py、subagent/graph.py、subagent_run_service.py深入讲解如何在页面配置子智能体、主智能体如何通过task与生命周期工具调用它、父子运行之间如何共享文件系统却隔离 LangGraph 上下文以及背后完整的 API 与数据模型。读完本文你将掌握在 Yuxi 中编排多智能体协作的完整实战能力。子智能体是什么共享入口的一级智能体在 Yuxi 中子智能体并不是一个独立的实体类型而是一种标记 后端的组合它仍然是agents表中的记录与普通智能体共用创建、权限和配置入口仅当记录的is_subagenttrue且后端类型选择SubAgentBackend时它才被识别为子智能体。从源码看SubAgentBackend 继承自BaseAgent其name为子智能体description明确写着用于被主智能体通过 task 工具调用的专用智能体后端capabilities包含file_upload与files。它使用独立的 SubAgentContext 作为上下文模式其中包含两个不可配置的隐藏字段parent_thread_id记录父线程 IDis_subagent_runtime标记当前是否处于子智能体运行态。正因为共享了普通 Agent 的存储与权限体系子智能体可以像普通智能体一样配置名称、提示词、模型、工具、知识库、MCP 和 Skills由管理员统一在智能体管理页面维护。三个硬性限制作为被编排的执行单元子智能体有三个刻意设计的限制原文档明确列出不会出现在普通聊天的智能体切换列表中不能设置为默认智能体不能继续调用其他子智能体因此不会形成孙级调用链。第 3 条限制在 subagent_run_service.py 中有直接实现start方法会校验父运行记录若creator_run.run_type subagent则直接抛出ValueError(子智能体不能创建子智能体)。同时子智能体运行时会校验creator_run.status必须为running父运行已结束时也不能再创建子任务。在页面中配置子智能体配置入口与普通智能体完全一致进入智能体管理页点击新增智能体在后端类型中选择SubAgentBackend像配置普通智能体一样设置名称、提示词、模型、工具、知识库、MCP 和 Skills。主智能体则在运行配置的子智能体字段中选择允许调用的对象选择语义如下配置方式运行时行为未配置或保存空列表使用当前用户可见的全部子智能体显式选择若干项只允许调用所选项每个子智能体使用自己的config_json.context不继承主智能体的模型或工具选择用户权限变化后新运行会重新计算可见范围而非缓存旧列表底层可见范围收敛逻辑源码 subagent_task.py 的create_subagent_task_middleware完整实现了上述语义读取父智能体上下文中的subagents字段去重后得到selected_slugs若selected_slugs非空逐个调用AgentRepository.get_visible_by_slug(slug..., useruser, kindsubagent)校验当前用户对该子智能体的可见性过滤掉不可见项若为空则调用AgentRepository.list_visible_subagents(useruser)返回当前用户可见的全部子智能体最终subagents为空时不挂载中间件return None。也就是说权限变化后新运行会重新计算可见范围这一行为正是因为这个中间件每次运行创建时都会重新查询且以发起用户的权限为过滤基准。list_visible_subagents在 agent_repository.py 中按Agent.is_subagent.is_(True)查询并按名称排序随后经过user_can_access_agent权限过滤。调用方式通过工具调用而不是 Shell 或 HTTP原文档强调主智能体通过工具调用子智能体不要通过 Shell、curl或 HTTP API 间接调用。这是因为子智能体调用依赖父运行上下文uid、父 run ID、tool_call_id、parent thread只有工具链路能提供这些绑定关系绕过工具直接调用 API 会破坏归属校验与线程关系。当可用子智能体列表非空时中间件会挂载 5 个工具源码见 subagent_task.py工具作用task同步调用阻塞等待子智能体结束后返回最终文本subagent_start异步创建 Run立即返回run_id、thread_idsubagent_status查询运行状态与最近几条进度摘要subagent_await等待终态并取得最终结果超时返回当前快照subagent_cancel请求取消子智能体运行同时中间件会把一段系统提示词TASK_SYSTEM_PROMPT追加到主智能体的系统消息中向模型说明每个工具的用法、可用subagent_slug列表Available subagent slugs:之后逐行列出slug: 描述以及不要通过 shell、curl、HTTP API 或命令行间接调用子智能体的约束。同步任务tasktask适合主智能体需要立即拿到结果的短任务。它会启动子 Run 后阻塞父智能体运行等待子 Run 终结再读取最终文本返回。工具参数JSON Schema 示例{ description: 整理这份文档的三条要点, subagent_slug: general-purpose, thread_id: null }参数语义来自源码常量定义description需要子智能体独立完成的任务描述包含必要上下文和期望输出subagent_slug要调用的子智能体 slug必须是工具描述中列出的可用项之一thread_id可选。首次调用不需要要继续之前的子任务时把上一次结果中的子智能体线程 ID 传回去工具结果会以 子智能体线程 ID: xxx前缀携带该 ID。需要特别注意的是task的等待超时行为源码中捕获AgentRunWaitTimeout后会返回一条明确的提示——子智能体仍在运行status: ...尚未返回最终文本结果并附上run_id不会把超时快照误当成任务完成结果父智能体可随后改用subagent_status或subagent_await继续查询。异步任务生命周期工具长任务或可并行任务应使用异步工具它们都是_async_only_tool构造的**仅异步coroutine-only**工具声明了coroutine而没有同步func因此同步调用链路会直接由 LangChain 报错从机制上杜绝错误用法。异步调用典型流程subagent_start立即返回 JSON 负载包含statusstarted或existing、run_id、thread_id、subagent_slug、subagent_name、created_by_run_id、continuing以及events_url/result_url父智能体继续自己的工作期间用subagent_status轮询运行终结时还会附带最终result;需要结果时用subagent_await等待终态超时返回当前快照并标注wait_timed_out: true不再需要时用subagent_cancel请求取消。并发约束同一个子智能体线程thread_id同时只能有一个运行中的 Run。忙碌时工具返回status: busy并携带active_run_id、active_run_status、message不会隐藏地把请求排队终态后的同一thread_id可以继续创建新的 Run。这一行为由 SubagentRunBusy 异常表达其源头是agent_run_service中 request id 的幂等性与 active-run 冲突检查。归属校验所有生命周期工具都按run_id操作并在每次调用前通过get_run_for_creator(uid, created_by_run_id, run_id)校验该 Run 由当前父 Run创建见 subagent_run_service.py因此无法读取或控制其他对话、其他父运行创建的子任务。子线程 ID 的确定性派生新建子任务时若未传thread_id子线程 ID 由 hash_utils.py 的subagent_child_thread_id确定性派生def subagent_child_thread_id(parent_thread_id: str, agent_slug: str, tool_call_id: str) - str: return hash_id(subagent_, f{parent_thread_id}:{agent_slug}:{tool_call_id}, length64)即同一父线程 同一子智能体 同一工具调用必然得到同一个子线程 ID这一设计保证了事件路由、状态面板与后续续跑指向一致的上下文。运行时边界共享文件系统隔离图状态一次子智能体调用会创建独立的 child checkpoint thread 和agent_runs(run_typesubagent)记录同时继承父运行的用户身份与根执行树。资源边界对比如下原文档核心表格资源主智能体子智能体LangGraph checkpoint当前thread_id独立child thread_idSandbox runtime根runtime_scope_id与根运行相同Project Workdir当前 Project 的 Workdir与根 Conversation 绑定的 Project 相同UserWorkspace当前用户的工作区同一用户的工作区共享/内置 Skills当前用户授权的只读投影同一授权投影关键事实Workdir 是共享字节不是隔离边界父子智能体看到的是同一份 Workdir 文件字节不会通过 checkpoint 复制或合并文件。child thread 只隔离 LangGraph 上下文它不是文件系统隔离边界。并发写同一路径仍按真实 POSIX 文件结果处理——即最后写入者生效父与子都能实时看到对方的文件变更。这在设计上是有意为之子智能体常用于帮我读这个文档并总结它必须能直接访问父任务工作目录中的文件。从源码看子对话的创建会绑定父对话的 Project_ensure_child_conversation创建对话时传入project_idparent_project_id并设置statussubagent、标题为SubAgent: {agent_name}同时写入parent_thread_id、created_by_run_id、parent_conversation_id、subagent_slug等元数据subagent_run_service.py。而SubagentThread关系表subagent_thread_repository.py以parent_conversation_id→child_conversation_id/child_thread_id的方式持久化父子关系child_thread_id与subagent_slug共同标识这条关系。工具过滤不适合子智能体的工具被移除子智能体可以使用自己配置的文件工具和知识库范围但所有资源访问仍以发起用户的后端权限为最终边界。以下工具会被过滤subagent/graph.py_SUBAGENT_DISABLED_TOOLS frozenset({present_artifacts, ask_user_question, install_skill})present_artifacts展示产物、ask_user_question向用户提问、install_skill安装技能这类需要与用户交互或改变系统配置的工具不适合子智能体直接使用。此外在非always_trust审批模式下还会额外隐藏SENSITIVE_BACKEND_TOOLS中的敏感后端工具避免子智能体绕过主线程的逐项审批。该过滤不只是从工具列表隐藏而是双重防线_SubAgentToolFilterMiddleware.wrap_model_call在模型可见的工具列表中去掉禁用项wrap_tool_call在执行边界拦截显式传入的禁用工具调用返回一条与原始 tool call 绑定的错误 ToolMessage内容提示请把结果交回主智能体由主线程按审批流程执行该操作。也就是说即使模型幻觉式地直接调用被禁工具也会被拒绝而不会执行。API 与数据模型子智能体沿用普通 Agent 管理 API无需单独的管理端点API语义GET /api/agent默认返回聊天可用的普通 Agent不含子智能体GET /api/agent?include_subagentstrue返回包含子智能体的列表创建/更新POST/PUT提交backendSubAgentBackend时后端校验is_subagenttrue详情、更新、删除复用同一套 Agent 权限检查从 agent_router.py 可以看到list_agents接受include_subagents: bool Query(False)参数并透传给AgentRepository.list_visible(user..., include_subagent_definitionsinclude_subagents)AgentCreate/AgentUpdate模型均包含可选的is_subagent: bool字段创建时可一并提交set_default等字段但子智能体不允许被设为默认。运行时主智能体的subagents配置会先收敛为当前用户可见的允许列表见上文可见范围收敛逻辑列表非空时挂载 task middleware子智能体自身不会挂载这一中间件因为子智能体不能继续调用子智能体挂载也没有意义。Run 记录与数据模型子智能体 Run 的数据特征agent_runs表中以run_typesubagent记录sourcesubagentchannelinternalruntime_scope_id继承自父 Rungetattr(creator_run, runtime_scope_id, None) or creator_run.conversation_thread_id保证 Sandbox runtime 与根运行一致request_id由hash_id(req:, f{creator_run.id}:{child_thread_id}:{tool_call_id})派生实现幂等同一请求重复提交不会创建重复 Run返回existing输入消息通过build_chat_input_message(description)构建并写入source: subagent元数据运行时的tool_approval_mode继承父 Run 的配置model_spec则由子智能体自身配置解析不继承父模型。父子关系的数据落点包括conversations表中statussubagent的子对话、subagent_threads表中的SubagentThread关系记录以及agent_runs上created_by_run_id与subagent_thread_relation_id两个外键字段。查看结果子智能体的运行结果会呈现在主对话中子智能体的run_id、状态、child thread 和产物显示在主对话的状态面板中前端按tool_call_id回填展示任务描述不冗余存储其唯一来源是父对话里工具调用的入参运行中的子智能体通过对应的事件流/api/agent/runs/{run_id}/events展示进度事件订阅相关逻辑位于 agent_run_service.py 与运行基础设施中完成后从持久化消息读取最终结果/api/agent/runs/{run_id}/resultRedis 原始事件只供运行基础设施和前端订阅不作为主智能体的工具结果——工具拿到的结果来自数据库持久化的 Run 状态与结果保证主智能体的上下文是可重放、可审计的。实现入口速览关注点源码路径五个调用工具与系统提示词backend/package/yuxi/agents/middlewares/subagent_task.pySubAgentBackend后端与工具过滤backend/package/yuxi/agents/buildin/subagent/graph.py子智能体上下文模式backend/package/yuxi/agents/buildin/subagent/context.py子 Run 编排、线程关系与 busy 语义backend/package/yuxi/services/subagent_run_service.pyRun 生命周期、等待与取消backend/package/yuxi/services/agent_run_service.py子线程 ID 派生backend/package/yuxi/utils/hash_utils.py子智能体可见性查询backend/package/yuxi/repositories/agent_repository.py父子线程关系存储backend/package/yuxi/repositories/subagent_thread_repository.pyAgent 管理 APIbackend/server/routers/agent_router.py最佳实践小结短任务用task长任务/并行用异步生命周期工具task会阻塞父智能体适合必须立即依赖结果的场景可并行或耗时的任务用subagent_start后继续主流程需要时再subagent_await。善用thread_id续跑工具结果中的子智能体线程 ID 是长期上下文标识同一线程终态后可继续创建新 Run适合分轮次完成同一子任务的场景。不要并行调用同一个thread_id同线程同时只能有一个运行中的 Run并发调用会得到busy。把子任务边界写清楚description应包含目标、上下文和期望输出并在工具描述列出的subagent_slug中选择避免模型幻觉式调用不存在的子智能体。理解共享边界子智能体与父任务共享 Workdir 字节与用户权限只隔离图状态不要在子智能体中执行需要向用户提问或安装技能的操作这些工具已被过滤。【免费下载链接】Yuxi可私有部署的多租户知识智能体平台统一 RAG、知识图谱、多智能体、MCP/Skills、沙盒与权限管理。Self-hosted knowledge agent platform for RAG, knowledge graphs and multi-agent workflows.项目地址: https://gitcode.com/GitHub_Trending/yu/Yuxi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考