CopilotKit Sub-Agents 多代理委派实战基于 Claude Agent SDK 构建 Supervisor 与实时委派日志【免费下载链接】CopilotKitThe Frontend Stack for Agents Generative UI. React, Angular, Mobile, Slack, and more. Makers of the AG-UI Protocol项目地址: https://gitcode.com/GitHub_Trending/co/CopilotKit导读本篇文章围绕 CopilotKit 仓库中 Sub-Agents 演示 展开讲解如何在 CopilotKit 前端栈与 Claude Agent SDKTypeScript后端之间构建监督者Supervisor 多个专精子代理的多代理系统监督者 LLM 将任务委派给 research / writing / critique 三个子代理每一个子代理以工具的形式暴露给监督者而每一次委派都会通过 AG-UI 共享状态实时流式渲染到前端日志面板。读完本文你将掌握子代理即工具sub-agents-as-tools的实现模式、AG-UI 状态快照的实时推送机制以及useAgent/useRenderTool在前端驱动多代理可视化日志的完整接线方式。演示概览监督者编排三个专精子代理该演示的核心是一个多代理委派 实时日志的闭环一个 Supervisor LLM 编排三个通过工具暴露的专精子代理而每一次委派都会通过共享的 Agent 状态实时流式进入 UI形成一条不断增长的委派日志。三个子代理各有明确分工与独立的 Claude 模型调用research_agent研究者负责收集事实、背景、定义、统计数据writing_agent写作者负责把研究结论与简报打磨成一段连贯的文稿critique_agent评审者负责审阅草稿并提出可执行的改进建议。核心设计有三点对应原 README 的技术要点子代理即工具Sub-agents-as-tools监督者通过后端工具 schema 调用子代理每个工具 handler 运行对应的子代理并向共享的delegations状态槽追加一条记录每个子代理是独立的单次 Claude 调用拥有各自的系统提示词无工具、无递归监督者只能通过工具返回值看到子代理的输出实时委派日志Live delegation log左侧面板渲染来自 Agent 状态的delegations随着监督者把任务分发出去而不断增长。如何交互提示示例与预期流程演示页面默认提供三个建议提示词见 suggestions.ts点击建议芯片suggestion chip或自行输入提示词即可触发Produce a short blog post about the benefits of cold exposure training. Research first, then write, then critique.先研究、再写作、最后评审Explain how large language models handle tool calling. Research, write a paragraph, then critique.Summarize the current state of reusable rockets in 1 polished paragraph, with research and critique.交互时可以看到右侧聊天面板顶部出现Supervisor running徽标左侧委派日志依次填充 research → write → critique 三条记录每条记录都会经历running → completed的实时状态翻转监督者跑完流程后返回一段简短总结。原文档的 QA 测试清单 还验证了多轮对话中新委派会追加到既有日志、错误时条目显示failed且监督者不会伪造结果、总运行时间有界MAX_TOOL_ITERATIONS 10。后端原理子代理即工具的实现与状态流独立的/subagents端点演示的 Agent 后端由 agent_server.ts 提供。app.post(/subagents, ...)端点agent_server.ts#L2446-L2458负责接收来自前端的RunAgentInput从中恢复state.delegations作为初始状态并启动 agentic loopsystem promptSUPERVISOR_SYSTEM_PROMPT监督者提示词工具 schemaSUBAGENT_TOOL_SCHEMAS三个子代理工具的定义初始状态{ delegations }确保跨轮次multi-turn日志持续追加而非清空。监督者如何看到子代理三个工具 schema 在 subagents-prompts.ts 的SUBAGENT_TOOL_SCHEMAS中定义。每个工具都只接受一个task: string参数required: [task]并注明返回形状为 JSON 对象{status: completed | failed, result?: string, error?: string}。监督者系统提示词明确要求对于大多数非平凡请求应按research - write - critique顺序委派并把相关事实/草稿通过task参数透传给下游子代理若子代理失败要向用户如实反馈失败原因而不是捏造结果。委派处理的两次状态写入executeBackendTool函数agent_server.ts#L1446-L1703针对三个子代理工具名分支处理L1623-L1697其关键点是对state.delegations进行两次更新调用前生成idrandomUUID()把{ id, sub_agent, task, status: running, result: }追加进delegations并立即通过emit({ type: EventType.STATE_SNAPSHOT, snapshot: stateWithRunning })推送状态快照——这样 UI 的委派日志能立刻显示一条running行而不必等待子代理完成调用后子代理成功则把同一条记录更新为{ status: completed, result }失败则更新为{ status: failed, result: scrubbedError }并对错误信息做脱敏处理只向 UI 和监督者暴露错误类别完整 message/stack 仅写入服务端日志。对应的Delegation类型agent_server.ts#L1330-L1336为{ id, sub_agent, task, status: running | completed | failed, result }与前端 delegation-log.tsx 中的类型一一对应。子代理的一次性 Claude 调用invokeSubAgentagent_server.ts#L1380-L1402是每个子代理的执行体一次不带工具、不带流式的anthropic.messages.create调用system传入子代理专属系统提示词用户消息直接是taskmax_tokens: 1024随后提取全部 text block 拼接后返回给监督者作为工具结果。这印证了 README 中每个委派工具调用一个专门的 Claude prompt、随后把子代理结果作为工具结果返回给监督者的描述。子代理使用的模型可通过环境变量覆盖agent_server.ts#L1319-L1328优先级为CLAUDE_SUBAGENT_MODEL→ANTHROPIC_SUBAGENT_MODEL旧版兼容回退→CLAUDE_MODEL监督者模型。这样运维可以在不调整监督者模型的前提下为次要调用换用更快/更便宜的模型。三个子代理的系统提示词系统提示词集中在 subagents-prompts.tsResearchYou are a research sub-agent. Given a topic, produce a concise bulleted list of 3-5 key facts. No preamble, no closing.WritingYou are a writing sub-agent. Given a brief and optional source facts, produce a polished 1-paragraph draft. Be clear and concrete. No preamble.CritiqueYou are an editorial critique sub-agent. Given a draft, give 2-3 crisp, actionable critiques. No preamble.源码注释还说明这套提示词刻意与仓库中 LangGraph Pythonlanggraph-python/src/agents/subagents.py和 Google ADKgoogle-adk/src/agents/subagents_agent.py的参考实现保持一致的措辞使 showcase 在不同运行时上产出可对比的输出。前端实现useAgent 驱动实时委派日志接线与状态订阅页面入口 page.tsx 中CopilotKitProvider 使用runtimeUrl/api/copilotkitdemo 布局中实际指向agentsubagents由 demo-layout.tsx 中的CopilotChat agentIdsubagents配套使用与专用端点接线核心订阅逻辑为const { agent } useAgent({ agentId: subagents, updates: [UseAgentUpdate.OnStateChanged, UseAgentUpdate.OnRunStatusChanged], }); const agentState agent.state as SubagentsAgentState | undefined; const delegations agentState?.delegations ?? []; const isRunning agent.isRunning;这正是原 README 提到的前端要点useAgent订阅OnStateChanged与OnRunStatusChanged读取agent.state.delegations与agent.isRunning来驱动日志。SubagentsAgentState接口定义delegations?: Delegation[]与后端状态槽保持一致。左侧委派日志delegation-log.tsx 中的DelegationLog组件渲染delegations数组头部显示Sub-agent delegations标题、Supervisor running徽标仅isRunning时显示与{delegations.length} calls计数顶部固定展示三个子代理角色指示芯片Research / Writing / Critique无论是否已调用都可见已调用则点亮下方按顺序渲染每条委派记录包含序号、角色徽标、状态completed与任务/结果文本。空列表时显示占位文案 Ask the supervisor to complete a task. Every sub-agent it calls will appear here.聊天流内的活动卡片除了侧边日志每个子代理调用还会在聊天消息流内渲染一张内联活动卡片。page.tsx中为三个工具分别注册useRenderTool见region[subagent-tool-renderers]区块例如useRenderTool( { name: research_agent, parameters: z.object({ task: z.string() }), render: ({ parameters, status, result }) ( SubAgentActivityCard subAgentresearch_agent task{parameters?.task} status{status as SubAgentToolStatus} result{typeof result string ? result : undefined} / ), }, [], );subagent-activity-card.tsx 中的SubAgentActivityCard展示子代理角色、任务与结果其状态沿着inProgress → executing → complete流转对应徽标 starting / running / done让用户在侧边栏之外也能实时看到哪个子代理正在跑、接到的任务是什么。正在运行的子代理推断active-subagent.ts 的inferActiveSubAgent会扫描实时消息流找出最近一条监督者发起的、尚未收到 ToolMessage 回包的子代理工具调用用于驱动聊天面板顶部的 supervisor-activity-banner.tsx紧凑粘性横幅Researcher is running: 。该函数刻意采用防御性结构探测不依赖具体的 v2 消息 TS 类型并对流式中可能出现的部分 JSON 工具参数做了容错先尝试严格JSON.parse失败则用正则嗅探task: ...片段。运行时接线专用 CopilotRuntime 路由演示在前端路由层使用了一个专用运行时端点 copilotkit-subagents/route.ts通过createClaudeHttpAgent(${AGENT_URL}/subagents)默认AGENT_URLhttp://localhost:8000把 CopilotRuntime 代理到 agent_server 的/subagents端点注册名为subagents的 agent并用createCopilotRuntimeHandler({ runtime, basePath: /api/copilotkit-subagents, mode: single-route })暴露 POST 处理。错误处理只向前端返回不透明的errorId完整堆栈仅记录在服务端日志中。这就是原 README 所说CopilotKitprovider 使用agentsubagents后端由专门的/subagentsClaude 端点支撑的具体接线。验证与测试如何确认多代理编排正确QA 手册qa/subagents.md 提供了完整的逐项验收清单页面加载、单次委派流程research → writing → critique 依次 running → completed计数变为3 calls、实时状态流、多轮追加、错误处理空消息、失败条目显示failed且监督者继续/如实反馈。E2E 测试tests/e2e/subagents.spec.ts 通过 Playwright 驱动建议芯片提示词端到端运行断言三张角色卡片[data-testidsubagent-card-role]全部渲染且data-status达到complete、每张卡片的[data-testidsubagent-result]非空且不泄漏聊天欢迎语防止 Writer/Critic 卡片误带助手样板文本的回归并保证每次监督者运行只出现一张处于done状态的 critic 卡片防止 critic 循环回归。运行前提Agent 后端需配置ANTHROPIC_API_KEY如需子代理使用不同于监督者的模型可设置CLAUDE_SUBAGENT_MODEL或旧版ANTHROPIC_SUBAGENT_MODEL。小结从该演示可以提炼出一条可复用的多代理模式把每个子代理封装为一个无工具、单次调用的 Claude Messages 请求以工具 schema 暴露给监督者委派过程对共享状态做运行中→完成/失败的两次快照写入经 AG-UISTATE_SNAPSHOT实时推送前端通过useAgent订阅状态与运行状态、useRenderTool在聊天流内渲染内联活动卡片。这套监督者 子代理即工具 共享状态流式日志的组合可直接迁移到你自己的 CopilotKit 应用中用于构建研究、写作、评审等需要多角色协作的 Agent 工作流。【免费下载链接】CopilotKitThe Frontend Stack for Agents Generative UI. React, Angular, Mobile, Slack, and more. Makers of the AG-UI Protocol项目地址: https://gitcode.com/GitHub_Trending/co/CopilotKit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
CopilotKit Sub-Agents 多代理委派实战：基于 Claude Agent SDK 构建 Supervisor 与实时委派日志
CopilotKit Sub-Agents 多代理委派实战基于 Claude Agent SDK 构建 Supervisor 与实时委派日志【免费下载链接】CopilotKitThe Frontend Stack for Agents Generative UI. React, Angular, Mobile, Slack, and more. Makers of the AG-UI Protocol项目地址: https://gitcode.com/GitHub_Trending/co/CopilotKit导读本篇文章围绕 CopilotKit 仓库中 Sub-Agents 演示 展开讲解如何在 CopilotKit 前端栈与 Claude Agent SDKTypeScript后端之间构建监督者Supervisor 多个专精子代理的多代理系统监督者 LLM 将任务委派给 research / writing / critique 三个子代理每一个子代理以工具的形式暴露给监督者而每一次委派都会通过 AG-UI 共享状态实时流式渲染到前端日志面板。读完本文你将掌握子代理即工具sub-agents-as-tools的实现模式、AG-UI 状态快照的实时推送机制以及useAgent/useRenderTool在前端驱动多代理可视化日志的完整接线方式。演示概览监督者编排三个专精子代理该演示的核心是一个多代理委派 实时日志的闭环一个 Supervisor LLM 编排三个通过工具暴露的专精子代理而每一次委派都会通过共享的 Agent 状态实时流式进入 UI形成一条不断增长的委派日志。三个子代理各有明确分工与独立的 Claude 模型调用research_agent研究者负责收集事实、背景、定义、统计数据writing_agent写作者负责把研究结论与简报打磨成一段连贯的文稿critique_agent评审者负责审阅草稿并提出可执行的改进建议。核心设计有三点对应原 README 的技术要点子代理即工具Sub-agents-as-tools监督者通过后端工具 schema 调用子代理每个工具 handler 运行对应的子代理并向共享的delegations状态槽追加一条记录每个子代理是独立的单次 Claude 调用拥有各自的系统提示词无工具、无递归监督者只能通过工具返回值看到子代理的输出实时委派日志Live delegation log左侧面板渲染来自 Agent 状态的delegations随着监督者把任务分发出去而不断增长。如何交互提示示例与预期流程演示页面默认提供三个建议提示词见 suggestions.ts点击建议芯片suggestion chip或自行输入提示词即可触发Produce a short blog post about the benefits of cold exposure training. Research first, then write, then critique.先研究、再写作、最后评审Explain how large language models handle tool calling. Research, write a paragraph, then critique.Summarize the current state of reusable rockets in 1 polished paragraph, with research and critique.交互时可以看到右侧聊天面板顶部出现Supervisor running徽标左侧委派日志依次填充 research → write → critique 三条记录每条记录都会经历running → completed的实时状态翻转监督者跑完流程后返回一段简短总结。原文档的 QA 测试清单 还验证了多轮对话中新委派会追加到既有日志、错误时条目显示failed且监督者不会伪造结果、总运行时间有界MAX_TOOL_ITERATIONS 10。后端原理子代理即工具的实现与状态流独立的/subagents端点演示的 Agent 后端由 agent_server.ts 提供。app.post(/subagents, ...)端点agent_server.ts#L2446-L2458负责接收来自前端的RunAgentInput从中恢复state.delegations作为初始状态并启动 agentic loopsystem promptSUPERVISOR_SYSTEM_PROMPT监督者提示词工具 schemaSUBAGENT_TOOL_SCHEMAS三个子代理工具的定义初始状态{ delegations }确保跨轮次multi-turn日志持续追加而非清空。监督者如何看到子代理三个工具 schema 在 subagents-prompts.ts 的SUBAGENT_TOOL_SCHEMAS中定义。每个工具都只接受一个task: string参数required: [task]并注明返回形状为 JSON 对象{status: completed | failed, result?: string, error?: string}。监督者系统提示词明确要求对于大多数非平凡请求应按research - write - critique顺序委派并把相关事实/草稿通过task参数透传给下游子代理若子代理失败要向用户如实反馈失败原因而不是捏造结果。委派处理的两次状态写入executeBackendTool函数agent_server.ts#L1446-L1703针对三个子代理工具名分支处理L1623-L1697其关键点是对state.delegations进行两次更新调用前生成idrandomUUID()把{ id, sub_agent, task, status: running, result: }追加进delegations并立即通过emit({ type: EventType.STATE_SNAPSHOT, snapshot: stateWithRunning })推送状态快照——这样 UI 的委派日志能立刻显示一条running行而不必等待子代理完成调用后子代理成功则把同一条记录更新为{ status: completed, result }失败则更新为{ status: failed, result: scrubbedError }并对错误信息做脱敏处理只向 UI 和监督者暴露错误类别完整 message/stack 仅写入服务端日志。对应的Delegation类型agent_server.ts#L1330-L1336为{ id, sub_agent, task, status: running | completed | failed, result }与前端 delegation-log.tsx 中的类型一一对应。子代理的一次性 Claude 调用invokeSubAgentagent_server.ts#L1380-L1402是每个子代理的执行体一次不带工具、不带流式的anthropic.messages.create调用system传入子代理专属系统提示词用户消息直接是taskmax_tokens: 1024随后提取全部 text block 拼接后返回给监督者作为工具结果。这印证了 README 中每个委派工具调用一个专门的 Claude prompt、随后把子代理结果作为工具结果返回给监督者的描述。子代理使用的模型可通过环境变量覆盖agent_server.ts#L1319-L1328优先级为CLAUDE_SUBAGENT_MODEL→ANTHROPIC_SUBAGENT_MODEL旧版兼容回退→CLAUDE_MODEL监督者模型。这样运维可以在不调整监督者模型的前提下为次要调用换用更快/更便宜的模型。三个子代理的系统提示词系统提示词集中在 subagents-prompts.tsResearchYou are a research sub-agent. Given a topic, produce a concise bulleted list of 3-5 key facts. No preamble, no closing.WritingYou are a writing sub-agent. Given a brief and optional source facts, produce a polished 1-paragraph draft. Be clear and concrete. No preamble.CritiqueYou are an editorial critique sub-agent. Given a draft, give 2-3 crisp, actionable critiques. No preamble.源码注释还说明这套提示词刻意与仓库中 LangGraph Pythonlanggraph-python/src/agents/subagents.py和 Google ADKgoogle-adk/src/agents/subagents_agent.py的参考实现保持一致的措辞使 showcase 在不同运行时上产出可对比的输出。前端实现useAgent 驱动实时委派日志接线与状态订阅页面入口 page.tsx 中CopilotKitProvider 使用runtimeUrl/api/copilotkitdemo 布局中实际指向agentsubagents由 demo-layout.tsx 中的CopilotChat agentIdsubagents配套使用与专用端点接线核心订阅逻辑为const { agent } useAgent({ agentId: subagents, updates: [UseAgentUpdate.OnStateChanged, UseAgentUpdate.OnRunStatusChanged], }); const agentState agent.state as SubagentsAgentState | undefined; const delegations agentState?.delegations ?? []; const isRunning agent.isRunning;这正是原 README 提到的前端要点useAgent订阅OnStateChanged与OnRunStatusChanged读取agent.state.delegations与agent.isRunning来驱动日志。SubagentsAgentState接口定义delegations?: Delegation[]与后端状态槽保持一致。左侧委派日志delegation-log.tsx 中的DelegationLog组件渲染delegations数组头部显示Sub-agent delegations标题、Supervisor running徽标仅isRunning时显示与{delegations.length} calls计数顶部固定展示三个子代理角色指示芯片Research / Writing / Critique无论是否已调用都可见已调用则点亮下方按顺序渲染每条委派记录包含序号、角色徽标、状态completed与任务/结果文本。空列表时显示占位文案 Ask the supervisor to complete a task. Every sub-agent it calls will appear here.聊天流内的活动卡片除了侧边日志每个子代理调用还会在聊天消息流内渲染一张内联活动卡片。page.tsx中为三个工具分别注册useRenderTool见region[subagent-tool-renderers]区块例如useRenderTool( { name: research_agent, parameters: z.object({ task: z.string() }), render: ({ parameters, status, result }) ( SubAgentActivityCard subAgentresearch_agent task{parameters?.task} status{status as SubAgentToolStatus} result{typeof result string ? result : undefined} / ), }, [], );subagent-activity-card.tsx 中的SubAgentActivityCard展示子代理角色、任务与结果其状态沿着inProgress → executing → complete流转对应徽标 starting / running / done让用户在侧边栏之外也能实时看到哪个子代理正在跑、接到的任务是什么。正在运行的子代理推断active-subagent.ts 的inferActiveSubAgent会扫描实时消息流找出最近一条监督者发起的、尚未收到 ToolMessage 回包的子代理工具调用用于驱动聊天面板顶部的 supervisor-activity-banner.tsx紧凑粘性横幅Researcher is running: 。该函数刻意采用防御性结构探测不依赖具体的 v2 消息 TS 类型并对流式中可能出现的部分 JSON 工具参数做了容错先尝试严格JSON.parse失败则用正则嗅探task: ...片段。运行时接线专用 CopilotRuntime 路由演示在前端路由层使用了一个专用运行时端点 copilotkit-subagents/route.ts通过createClaudeHttpAgent(${AGENT_URL}/subagents)默认AGENT_URLhttp://localhost:8000把 CopilotRuntime 代理到 agent_server 的/subagents端点注册名为subagents的 agent并用createCopilotRuntimeHandler({ runtime, basePath: /api/copilotkit-subagents, mode: single-route })暴露 POST 处理。错误处理只向前端返回不透明的errorId完整堆栈仅记录在服务端日志中。这就是原 README 所说CopilotKitprovider 使用agentsubagents后端由专门的/subagentsClaude 端点支撑的具体接线。验证与测试如何确认多代理编排正确QA 手册qa/subagents.md 提供了完整的逐项验收清单页面加载、单次委派流程research → writing → critique 依次 running → completed计数变为3 calls、实时状态流、多轮追加、错误处理空消息、失败条目显示failed且监督者继续/如实反馈。E2E 测试tests/e2e/subagents.spec.ts 通过 Playwright 驱动建议芯片提示词端到端运行断言三张角色卡片[data-testidsubagent-card-role]全部渲染且data-status达到complete、每张卡片的[data-testidsubagent-result]非空且不泄漏聊天欢迎语防止 Writer/Critic 卡片误带助手样板文本的回归并保证每次监督者运行只出现一张处于done状态的 critic 卡片防止 critic 循环回归。运行前提Agent 后端需配置ANTHROPIC_API_KEY如需子代理使用不同于监督者的模型可设置CLAUDE_SUBAGENT_MODEL或旧版ANTHROPIC_SUBAGENT_MODEL。小结从该演示可以提炼出一条可复用的多代理模式把每个子代理封装为一个无工具、单次调用的 Claude Messages 请求以工具 schema 暴露给监督者委派过程对共享状态做运行中→完成/失败的两次快照写入经 AG-UISTATE_SNAPSHOT实时推送前端通过useAgent订阅状态与运行状态、useRenderTool在聊天流内渲染内联活动卡片。这套监督者 子代理即工具 共享状态流式日志的组合可直接迁移到你自己的 CopilotKit 应用中用于构建研究、写作、评审等需要多角色协作的 Agent 工作流。【免费下载链接】CopilotKitThe Frontend Stack for Agents Generative UI. React, Angular, Mobile, Slack, and more. Makers of the AG-UI Protocol项目地址: https://gitcode.com/GitHub_Trending/co/CopilotKit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
