CopilotKit 子代理Sub-Agents实战指南基于 Claude Agent SDKTypeScript的多代理委派与实时日志【免费下载链接】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本指南聚焦于当前仓库showcase/integrations/claude-sdk-typescript演示应用中的Sub-Agents子代理功能它通过监督者Supervisor 子代理即工具Sub-agents-as-tools的架构让一个 Claude 模型协调三个专职子代理完成研究 → 写作 → 评审的工作流并借助 AG-UI 协议把每一次委派以实时状态流STATE_SNAPSHOT的方式渲染到前端。读完本文你将掌握该演示从部署前置条件、页面交互到端到端验证的完整操作路径同时理解后端如何通过共享 agent state 驱动delegations日志的实时更新。前置条件与运行环境在开始测试 Sub-Agents 演示之前请确认以下条件全部满足详见 QA 文档前置条件说明Demo 已部署且可访问/demos/subagents前端页面路由由 Next.js 应用提供Agent 后端健康检查GET /api/copilotkit-subagents是否返回正常响应ANTHROPIC_API_KEY已设置必须配置在 agent 后端而非前端否则无法发起 Anthropic Messages API 调用可选ANTHROPIC_SUBAGENT_MODEL或CLAUDE_SUBAGENT_MODEL若希望次级调用子代理调用使用与监督者不同的模型可单独指定从后端实现看模型名还支持额外的环境变量兜底agent_server.ts 中CLAUDE_MODEL依次读取CLAUDE_MODEL→ANTHROPIC_MODEL→ 默认claude-opus-4-8并会对claude-sonnet-4.6这类带点号的历史命名做归一化处理normalizeAnthropicModel。这意味着如果仓库中其他 demo 已配置过CLAUDE_MODELSub-Agents 的监督者默认也会沿用该模型而子代理则可通过ANTHROPIC_SUBAGENT_MODEL单独覆盖。页面加载检查清单导航到/demos/subagents后按以下清单逐项核对页面是否正常渲染主面板显示一张Sub-agent delegations卡片头部标题为0 calls初始委派次数为 0正文有斜体占位文案 Ask the supervisor to complete a task.右侧面板聊天输入框的占位符为 Give the supervisor a task...三个建议提示词suggestion chips可见 Write a blog post、Explain a topic、Summarize a topic 三个按钮无控制台报错浏览器 Console 面板不应出现任何 unhandled error这三个建议提示词与 e2e 测试 中定义的PILLS完全一致测试也使用它们作为端到端用例的输入。前端页面由 page.tsx 提供CopilotKit runtimeUrl/api/copilotkit agentsubagents声明了运行时端点与 agent iddemo 通过useAgent({ agentId: subagents, updates: [OnStateChanged, OnRunStatusChanged] })订阅 agent 状态变化与运行状态变化。单次委派流程监督者编排三级流水线点击 Explain a topic或输入类似提示词观察完整的委派编排过程监督者运行徽标出现页面头部出现 Supervisor running 状态徽标表示监督者 LLM 正在执行第一条委派记录出现research_agentResearch条目进入日志状态为running附带斜体占位文案 Waiting for sub-agent…约 15 秒内翻转为completedResearch 条目完成展示一条项目符号列表形式的事实清单第二条委派Writingwriting_agent出现并进入running随后完成展示一段成稿1-paragraph draft第三条委派Critiquecritique_agent运行并完成给出 2–3 条评审意见委派计数变为3 calls头部标题从0 calls更新为3 calls运行结束监督者 running 徽标消失最终总结监督者的最后一条聊天消息是简短总结这套流水线由监督者系统提示词强制约束。subagents-prompts.ts 中的SUPERVISOR_SYSTEM_PROMPT明确指示模型对于大多数非平凡请求按 research → write → critique 顺序委派通过每个工具的task参数传递相关事实/草稿并要求保持自己的消息简短——规划一次、委派、完成后返回简明总结把细节输出交给委派日志承载。子代理本质一次专用系统提示词的 Anthropic 调用三个子代理并非独立智能体进程而是一次带专用系统提示词的 Anthropic Messages API 单次调用无工具、无递归。每个子代理的系统提示词定义如下源码子代理系统提示词要点输出形态research_agentResearchGiven a topic, produce a concise bulleted list of 3-5 key facts. No preamble, no closing.3–5 条关键事实的要点列表writing_agentWritingGiven a brief and optional source facts, produce a polished 1-paragraph draft. Be clear and concrete. No preamble.一段精炼成稿critique_agentCritiqueGiven a draft, give 2-3 crisp, actionable critiques. No preamble.2–3 条可执行的评审建议文件头注释还说明了设计意图这套提示词与仓库中 LangGraph Pythonlanggraph-python/src/agents/subagents.py和 Google ADKgoogle-adk/src/agents/subagents_agent.py参考实现保持语言一致使得同一 showcase 在不同运行时上产出可比输出——即同一主题、三种运行时、结果可比的跨栈对标设计。子代理即工具监督者的委派接口监督者通过后端工具 schema 调用子代理。每个子代理对应一个工具定义SUBAGENT_TOOL_SCHEMAS结构如下以research_agent为例{ name: research_agent, description: Delegate a research task to the research sub-agent. Use for: gathering facts, background, definitions, statistics. Returns a JSON object {status, result?, error?}., input_schema: { type: object, properties: { task: { type: string, description: The research task — a topic or question., }, }, required: [task], }, }三个工具的input_schema均只有一个必填的task字符串参数返回格式统一为{status: completed | failed, result?: string, error?: string}。后端 agent_server.ts 的/subagents端点把SUPERVISOR_SYSTEM_PROMPT与SUBAGENT_TOOL_SCHEMAS一并交给runAgenticLoop运行循环执行工具调用并把子代理输出以tool_result形式回传给监督者供其下一步决策。实时状态流STATE_SNAPSHOT 驱动的委派日志后端每条委派写入两次状态快照委派日志的实时性来自后端对共享 agent state 的两次写入源码执行前在发起子代理的 Anthropic 调用之前先向state.delegations追加一条status: running的条目并立即emit({ type: EventType.STATE_SNAPSHOT, snapshot: stateWithRunning })让 UI 立刻出现一条运行中的记录执行后子代理返回后再以status: completed成功或status: failed失败追加最终条目并发出新的STATE_SNAPSHOT。关键细节executeBackendTool中运行中快照由调用方通过onRunningEntry发出成功/失败后的最终状态则由函数返回。失败路径还会对错误信息做脱敏处理——只把sub-agent call failed: ${errorClass} (see server logs)这种不含请求 ID、提示词片段、限流细节的安全字符串传给 UI 与监督者完整堆栈仅写入服务端日志scrubbed逻辑。state.delegations存放在 AG-UI 共享状态中因此前端无需轮询即可收到推送式更新。此外 route.ts 中CopilotRuntime将subagents与default两个 agent id 都映射到该后端端点并通过mode: single-route建立运行时桥接。前端订阅 agent 状态并渲染日志前端通过两条通道消费状态page.tsxconst { agent } useAgent({ agentId: subagents, updates: [UseAgentUpdate.OnStateChanged, UseAgentUpdate.OnRunStatusChanged], }); const agentState agent.state as SubagentsAgentState | undefined; const delegations agentState?.delegations ?? []; const isRunning agent.isRunning;委派日志从agent.state.delegations读取条目列表交给DemoLayout渲染成左侧日志面板运行状态agent.isRunning驱动头部 Supervisor running 徽标与activeSubAgent的推断。同时每个子代理工具还通过useRenderTool注册了聊天流内联卡片源码research_agent、writing_agent、critique_agent各对应一个SubAgentActivityCard渲染器接收流式参数、最终结果以及一个走过inProgress → executing → complete的状态让用户在聊天流中也能看到Researcher is running task Y这类实时反馈而不必盯着侧边面板。两个通道聊天流卡片 侧边日志由同一份 agent state 驱动相互一致。多轮对话委派日志的追加语义第一轮运行结束后发送一条后续消息例如 Now do the same for renewable energy storage新委派追加到已有日志计数继续增长例如从3 calls变为6 calls历史条目保留可见前一轮的 research/writing/critique 条目不被清空日志是追加式append-only结构。这一行为在后端有明确保证每次委派时const existing Array.isArray(state.delegations) ? ... : []都会读取当前全部已有条目再以[...existing, newEntry]追加源码因此多轮会话中日志天然累积。错误处理失败可见而非幻觉补全QA 文档对错误路径提出了明确的行为要求空消息发送空消息应被优雅处理不产生崩溃或异常输出子代理调用失败例如临时吊销 API key委派条目应显示failed状态并附错误信息监督者应如实向用户呈现失败而非编造结果——这正是系统提示词中 If a sub-agent fails, surface the failure briefly to the user (dont fabricate a result) 的约束在运行时的落地快乐路径无未处理控制台错误正常运行全程不应出现 unhandled 报错。后端失败处理逻辑与上述要求一一对应invokeSubAgent抛错时捕获异常写入failed状态条目把脱敏后的错误类名作为tool_result返回给监督者源码监督者据此决定是否重试。期望结果与验收标准完整的验收标准归纳如下对应 QA 文档 的 Expected Results 部分验收项标准委派条目唯一性每次子代理调用在委派日志中恰好产生一条记录状态流转条目经 AG-UISTATE_SNAPSHOT实时流转running → completed或failed无需刷新/滚动状态徽标配色状态徽标按颜色区分黄色 running绿色 completed红色 failed文本输出策略监督者的文本回复保持简短主要输出沉淀在委派日志中运行时长有界总运行时间受限无失控循环MAX_TOOL_ITERATIONS 10MAX_TOOL_ITERATIONS定义在 agent_server.ts 的runAgenticLoop中代理循环最多迭代 10 轮工具调用从机制上杜绝监督者无限循环委派runaway loops这也是总运行时间有界的直接实现证据。端到端测试如何自动化验证仓库为该演示提供了完整的 Playwright 端到端测试subagents.spec.ts覆盖 QA 清单中的绝大部分断言页面加载测试验证聊天输入框、三个建议 pill、以及侧边面板中三个始终可见的子代理角色指示器subagent-indicator-researcher/writer/critic渲染正常三个 pill 的完整流水线测试分别点击 Write a blog post、Explain a topic、Summarize a topic断言三张角色卡片subagent-card-researcher/writer/critic均可见且进入complete状态并校验结果文本非空、非占位符、且不泄漏聊天欢迎语样板BOILERPLATE_FRAGMENTS断言Critic 去重回归测试点击 pill 后断言 critic 卡片恰好渲染 1 张停留 5 秒后复查数量仍为 1、状态仍为complete——防止监督者重复进入 critic 环节导致的死循环回归。测试还记录了历史回归背景summarizepill 曾因delegations状态键缺少 reducer 而返回INVALID_CONCURRENT_GRAPH_UPDATEHTTP 400如今该用例作为回归护栏保留。测试运行需依赖 aimock fixtureshowcase/aimock/d5-all.json等三条 pill 链这也是整个 showcase 在无真实 API key 环境下可重复验证的基础设施。小结Sub-Agents 演示展示了 CopilotKit 多代理编排的典型形态一个监督者 多个单次专用调用的子代理 共享 agent state 的实时回传。从实操角度你只需准备后端ANTHROPIC_API_KEY访问/demos/subagents点按任一建议提示词即可看到委派日志从0 calls生长到3 calls的完整过程从原理角度state.delegations的两次写入与STATE_SNAPSHOT推送、MAX_TOOL_ITERATIONS 10的有界循环以及失败脱敏上报的设计都是可以直接借鉴到自有 Agent 应用中的实现模式。相关文档与源码索引QA 文档、demo 说明、提示词与工具 schema、后端端点、前端页面、e2e 测试。【免费下载链接】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（TypeScript）的多代理委派与实时日志
CopilotKit 子代理Sub-Agents实战指南基于 Claude Agent SDKTypeScript的多代理委派与实时日志【免费下载链接】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本指南聚焦于当前仓库showcase/integrations/claude-sdk-typescript演示应用中的Sub-Agents子代理功能它通过监督者Supervisor 子代理即工具Sub-agents-as-tools的架构让一个 Claude 模型协调三个专职子代理完成研究 → 写作 → 评审的工作流并借助 AG-UI 协议把每一次委派以实时状态流STATE_SNAPSHOT的方式渲染到前端。读完本文你将掌握该演示从部署前置条件、页面交互到端到端验证的完整操作路径同时理解后端如何通过共享 agent state 驱动delegations日志的实时更新。前置条件与运行环境在开始测试 Sub-Agents 演示之前请确认以下条件全部满足详见 QA 文档前置条件说明Demo 已部署且可访问/demos/subagents前端页面路由由 Next.js 应用提供Agent 后端健康检查GET /api/copilotkit-subagents是否返回正常响应ANTHROPIC_API_KEY已设置必须配置在 agent 后端而非前端否则无法发起 Anthropic Messages API 调用可选ANTHROPIC_SUBAGENT_MODEL或CLAUDE_SUBAGENT_MODEL若希望次级调用子代理调用使用与监督者不同的模型可单独指定从后端实现看模型名还支持额外的环境变量兜底agent_server.ts 中CLAUDE_MODEL依次读取CLAUDE_MODEL→ANTHROPIC_MODEL→ 默认claude-opus-4-8并会对claude-sonnet-4.6这类带点号的历史命名做归一化处理normalizeAnthropicModel。这意味着如果仓库中其他 demo 已配置过CLAUDE_MODELSub-Agents 的监督者默认也会沿用该模型而子代理则可通过ANTHROPIC_SUBAGENT_MODEL单独覆盖。页面加载检查清单导航到/demos/subagents后按以下清单逐项核对页面是否正常渲染主面板显示一张Sub-agent delegations卡片头部标题为0 calls初始委派次数为 0正文有斜体占位文案 Ask the supervisor to complete a task.右侧面板聊天输入框的占位符为 Give the supervisor a task...三个建议提示词suggestion chips可见 Write a blog post、Explain a topic、Summarize a topic 三个按钮无控制台报错浏览器 Console 面板不应出现任何 unhandled error这三个建议提示词与 e2e 测试 中定义的PILLS完全一致测试也使用它们作为端到端用例的输入。前端页面由 page.tsx 提供CopilotKit runtimeUrl/api/copilotkit agentsubagents声明了运行时端点与 agent iddemo 通过useAgent({ agentId: subagents, updates: [OnStateChanged, OnRunStatusChanged] })订阅 agent 状态变化与运行状态变化。单次委派流程监督者编排三级流水线点击 Explain a topic或输入类似提示词观察完整的委派编排过程监督者运行徽标出现页面头部出现 Supervisor running 状态徽标表示监督者 LLM 正在执行第一条委派记录出现research_agentResearch条目进入日志状态为running附带斜体占位文案 Waiting for sub-agent…约 15 秒内翻转为completedResearch 条目完成展示一条项目符号列表形式的事实清单第二条委派Writingwriting_agent出现并进入running随后完成展示一段成稿1-paragraph draft第三条委派Critiquecritique_agent运行并完成给出 2–3 条评审意见委派计数变为3 calls头部标题从0 calls更新为3 calls运行结束监督者 running 徽标消失最终总结监督者的最后一条聊天消息是简短总结这套流水线由监督者系统提示词强制约束。subagents-prompts.ts 中的SUPERVISOR_SYSTEM_PROMPT明确指示模型对于大多数非平凡请求按 research → write → critique 顺序委派通过每个工具的task参数传递相关事实/草稿并要求保持自己的消息简短——规划一次、委派、完成后返回简明总结把细节输出交给委派日志承载。子代理本质一次专用系统提示词的 Anthropic 调用三个子代理并非独立智能体进程而是一次带专用系统提示词的 Anthropic Messages API 单次调用无工具、无递归。每个子代理的系统提示词定义如下源码子代理系统提示词要点输出形态research_agentResearchGiven a topic, produce a concise bulleted list of 3-5 key facts. No preamble, no closing.3–5 条关键事实的要点列表writing_agentWritingGiven a brief and optional source facts, produce a polished 1-paragraph draft. Be clear and concrete. No preamble.一段精炼成稿critique_agentCritiqueGiven a draft, give 2-3 crisp, actionable critiques. No preamble.2–3 条可执行的评审建议文件头注释还说明了设计意图这套提示词与仓库中 LangGraph Pythonlanggraph-python/src/agents/subagents.py和 Google ADKgoogle-adk/src/agents/subagents_agent.py参考实现保持语言一致使得同一 showcase 在不同运行时上产出可比输出——即同一主题、三种运行时、结果可比的跨栈对标设计。子代理即工具监督者的委派接口监督者通过后端工具 schema 调用子代理。每个子代理对应一个工具定义SUBAGENT_TOOL_SCHEMAS结构如下以research_agent为例{ name: research_agent, description: Delegate a research task to the research sub-agent. Use for: gathering facts, background, definitions, statistics. Returns a JSON object {status, result?, error?}., input_schema: { type: object, properties: { task: { type: string, description: The research task — a topic or question., }, }, required: [task], }, }三个工具的input_schema均只有一个必填的task字符串参数返回格式统一为{status: completed | failed, result?: string, error?: string}。后端 agent_server.ts 的/subagents端点把SUPERVISOR_SYSTEM_PROMPT与SUBAGENT_TOOL_SCHEMAS一并交给runAgenticLoop运行循环执行工具调用并把子代理输出以tool_result形式回传给监督者供其下一步决策。实时状态流STATE_SNAPSHOT 驱动的委派日志后端每条委派写入两次状态快照委派日志的实时性来自后端对共享 agent state 的两次写入源码执行前在发起子代理的 Anthropic 调用之前先向state.delegations追加一条status: running的条目并立即emit({ type: EventType.STATE_SNAPSHOT, snapshot: stateWithRunning })让 UI 立刻出现一条运行中的记录执行后子代理返回后再以status: completed成功或status: failed失败追加最终条目并发出新的STATE_SNAPSHOT。关键细节executeBackendTool中运行中快照由调用方通过onRunningEntry发出成功/失败后的最终状态则由函数返回。失败路径还会对错误信息做脱敏处理——只把sub-agent call failed: ${errorClass} (see server logs)这种不含请求 ID、提示词片段、限流细节的安全字符串传给 UI 与监督者完整堆栈仅写入服务端日志scrubbed逻辑。state.delegations存放在 AG-UI 共享状态中因此前端无需轮询即可收到推送式更新。此外 route.ts 中CopilotRuntime将subagents与default两个 agent id 都映射到该后端端点并通过mode: single-route建立运行时桥接。前端订阅 agent 状态并渲染日志前端通过两条通道消费状态page.tsxconst { agent } useAgent({ agentId: subagents, updates: [UseAgentUpdate.OnStateChanged, UseAgentUpdate.OnRunStatusChanged], }); const agentState agent.state as SubagentsAgentState | undefined; const delegations agentState?.delegations ?? []; const isRunning agent.isRunning;委派日志从agent.state.delegations读取条目列表交给DemoLayout渲染成左侧日志面板运行状态agent.isRunning驱动头部 Supervisor running 徽标与activeSubAgent的推断。同时每个子代理工具还通过useRenderTool注册了聊天流内联卡片源码research_agent、writing_agent、critique_agent各对应一个SubAgentActivityCard渲染器接收流式参数、最终结果以及一个走过inProgress → executing → complete的状态让用户在聊天流中也能看到Researcher is running task Y这类实时反馈而不必盯着侧边面板。两个通道聊天流卡片 侧边日志由同一份 agent state 驱动相互一致。多轮对话委派日志的追加语义第一轮运行结束后发送一条后续消息例如 Now do the same for renewable energy storage新委派追加到已有日志计数继续增长例如从3 calls变为6 calls历史条目保留可见前一轮的 research/writing/critique 条目不被清空日志是追加式append-only结构。这一行为在后端有明确保证每次委派时const existing Array.isArray(state.delegations) ? ... : []都会读取当前全部已有条目再以[...existing, newEntry]追加源码因此多轮会话中日志天然累积。错误处理失败可见而非幻觉补全QA 文档对错误路径提出了明确的行为要求空消息发送空消息应被优雅处理不产生崩溃或异常输出子代理调用失败例如临时吊销 API key委派条目应显示failed状态并附错误信息监督者应如实向用户呈现失败而非编造结果——这正是系统提示词中 If a sub-agent fails, surface the failure briefly to the user (dont fabricate a result) 的约束在运行时的落地快乐路径无未处理控制台错误正常运行全程不应出现 unhandled 报错。后端失败处理逻辑与上述要求一一对应invokeSubAgent抛错时捕获异常写入failed状态条目把脱敏后的错误类名作为tool_result返回给监督者源码监督者据此决定是否重试。期望结果与验收标准完整的验收标准归纳如下对应 QA 文档 的 Expected Results 部分验收项标准委派条目唯一性每次子代理调用在委派日志中恰好产生一条记录状态流转条目经 AG-UISTATE_SNAPSHOT实时流转running → completed或failed无需刷新/滚动状态徽标配色状态徽标按颜色区分黄色 running绿色 completed红色 failed文本输出策略监督者的文本回复保持简短主要输出沉淀在委派日志中运行时长有界总运行时间受限无失控循环MAX_TOOL_ITERATIONS 10MAX_TOOL_ITERATIONS定义在 agent_server.ts 的runAgenticLoop中代理循环最多迭代 10 轮工具调用从机制上杜绝监督者无限循环委派runaway loops这也是总运行时间有界的直接实现证据。端到端测试如何自动化验证仓库为该演示提供了完整的 Playwright 端到端测试subagents.spec.ts覆盖 QA 清单中的绝大部分断言页面加载测试验证聊天输入框、三个建议 pill、以及侧边面板中三个始终可见的子代理角色指示器subagent-indicator-researcher/writer/critic渲染正常三个 pill 的完整流水线测试分别点击 Write a blog post、Explain a topic、Summarize a topic断言三张角色卡片subagent-card-researcher/writer/critic均可见且进入complete状态并校验结果文本非空、非占位符、且不泄漏聊天欢迎语样板BOILERPLATE_FRAGMENTS断言Critic 去重回归测试点击 pill 后断言 critic 卡片恰好渲染 1 张停留 5 秒后复查数量仍为 1、状态仍为complete——防止监督者重复进入 critic 环节导致的死循环回归。测试还记录了历史回归背景summarizepill 曾因delegations状态键缺少 reducer 而返回INVALID_CONCURRENT_GRAPH_UPDATEHTTP 400如今该用例作为回归护栏保留。测试运行需依赖 aimock fixtureshowcase/aimock/d5-all.json等三条 pill 链这也是整个 showcase 在无真实 API key 环境下可重复验证的基础设施。小结Sub-Agents 演示展示了 CopilotKit 多代理编排的典型形态一个监督者 多个单次专用调用的子代理 共享 agent state 的实时回传。从实操角度你只需准备后端ANTHROPIC_API_KEY访问/demos/subagents点按任一建议提示词即可看到委派日志从0 calls生长到3 calls的完整过程从原理角度state.delegations的两次写入与STATE_SNAPSHOT推送、MAX_TOOL_ITERATIONS 10的有界循环以及失败脱敏上报的设计都是可以直接借鉴到自有 Agent 应用中的实现模式。相关文档与源码索引QA 文档、demo 说明、提示词与工具 schema、后端端点、前端页面、e2e 测试。【免费下载链接】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），仅供参考
` 原理及 curr-domain 配置实战)
