基于 Agno 的 CopilotKit 子代理编排实战监督者委派模式与实时委派日志【免费下载链接】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 演示 为核心深入剖析一套可复用的**多智能体委派Multi-agent Delegation**实现方案一个监督者SupervisorLLM 通过工具调用将任务分派给三个专业子代理研究、写作、评审并把每次委派实时推送到前端形成委派日志。读完本文你将掌握如何用 AgnoAgent定义子代理即工具的完整链路、如何借 AG-UI 协议的StateSnapshotEvent把后端共享状态回传到前端、以及如何用useAgent/useRenderTool渲染实时委派状态。本文以仓库内真实源码为唯一依据所有代码片段均来自当前仓库。演示总览监督者 三个专业子代理该演示位于showcase/integrations/agno/src/app/demos/subagents/其核心思路一句话概括监督者不亲自干活而是把任务拆解后委派给三个各司其职的子代理并将每笔委派记录写入共享状态。三个子代理各自是独立的 AgnoAgent实例见 subagents.pyresearch_agent收集事实输出 3–5 条要点列表writing_agent根据简报与事实产出一段润色好的草稿critique_agent对草稿给出 2–3 条可执行的评审意见。每个子代理都有独立的系统提示词互不共享内存与工具监督者只能看到子代理的最终文本输出。子代理统一使用gpt-4o-mini模型_SUB_MODEL_ID gpt-4o-mini并设置 120 秒超时。监督者本身也是一个 AgnoAgentsubagents.pyagent Agent( modelOpenAIChat(id_SUB_MODEL_ID, timeout120), tools[research_agent, writing_agent, critique_agent], descriptionSupervisor agent coordinating research / writing / critique sub-agents., instructions_SUPERVISOR_INSTRUCTION, tool_call_limit10, )其系统提示词_SUPERVISOR_INSTRUCTION明确要求对大多数非平凡请求按research → write → critique的顺序依次委派把相关事实/草稿通过每个工具的task参数传递如果某个子代理失败如实向用户说明失败原因而非编造结果并自行决定是否重试。子代理即工具委派工具的实现细节演示的关键模式是子代理以工具的形式暴露给监督者。在 subagents.py 中三个委派工具research_agent(task)、writing_agent(task)、critique_agent(task)都收敛到同一个_delegate流程def _delegate(run_context, *, sub_agent_name, sub_agent, task): entry_id _append_delegation( run_context, sub_agentsub_agent_name, tasktask, statusrunning, result, ) try: result _invoke_sub_agent(sub_agent, task) except Exception as exc: # 只把异常类名暴露给上层完整堆栈留在服务端日志 _update_delegation(run_context, entry_identry_id, statusfailed, resultmessage) return {status: failed, error: message} _update_delegation(run_context, entry_identry_id, statuscompleted, resultresult) return {status: completed, result: result}委派条目写入共享状态_append_delegationsubagents.py把每次委派追加到run_context.session_state[delegations]entry { id: entry_id, # uuid4 sub_agent: sub_agent, # research_agent / writing_agent / critique_agent task: task, status: status, # running / completed / failed result: result, } run_context.session_state[delegations] delegations_update_delegationsubagents.py则按entry_id定位并更新条目的状态与结果。如果条目已丢失被其他环节替换了delegations数组只记录一条logger.warning而绝不追加合成条目——这一保守行为与仓库中 google-adk 参考实现保持一致。值得注意的是委派失败的错误信息只暴露异常类名避免把携带 URL、请求 ID 或部分凭据的提供方错误串泄露到前端。一次委派的完整生命周期从状态槽视角看一次委派经历三个阶段running_append_delegation先插入一条statusrunning的条目子代理执行_invoke_sub_agent同步调用sub_agent.run(inputtask)取回result.contentcompleted / failed_update_delegation把最终结果写回同一条记录。工具返回的字典{status: completed, result: ...}同时成为监督者的工具结果ToolMessage供其下一步决策如把研究结果作为写作任务的输入。说明该演示的同名 README 沿用了跨框架共享的表述如 LangGraph 的Command与create_agent。在当前 Agno 实现中这一模式由run_context.session_state的delegations槽位等价实现其追加共享状态 以工具消息回传结果的语义完全一致。共享状态如何到达前端AG-UI 与 StateSnapshotEventAgno 自带的 AGUI 路由器默认不会向后端客户端发射StateSnapshotEvent这会导致依赖useAgent({ updates: [OnStateChanged] })的前端收不到共享状态变化。为此仓库在 agent_server.py 中实现了一个状态感知的 AGUI 处理器_run_agent_with_state_snapshot复刻官方agno.os.interfaces.agui.router.run_agent的流式逻辑抑制内层流的RUN_STARTED/RUN_FINISHED在流结束后、发出自己的RunFinishedEvent之前发射一条携带最终session_state的StateSnapshotEvent快照优先通过agent.aget_session_state(session_idthread_id)或同步的get_session_state读取确保合并了会话数据库中落盘的任何额外状态读取失败则回退到内存快照。随后通过_attach_state_aware_route将该处理器挂载到/subagents/agui路由agent_server.py。这是双向共享状态契约的关键/subagents/agui与共享状态读写演示/shared-state-rw/agui使用同一套路由器。在前端侧Next.js 运行时通过 copilotkit/route.ts 把subagents代理名映射到该后端端点function createSubagentsAgent() { return new HttpAgent({ url: ${AGENT_URL}/subagents/agui }); } // ... agents[subagents] createSubagentsAgent();后端默认跑在AGENT_URL || http://localhost:8000与agent_server.py中/subagents前缀的 AGUI 端点对应。前端实时委派日志的实现1. Provider 与 useAgent 订阅page.tsx 中CopilotKit提供者指定agentsubagents页面组件用useAgent订阅状态变化与运行状态变化CopilotKit runtimeUrl/api/copilotkit agentsubagents DemoContent / /CopilotKit const { agent } useAgent({ agentId: subagents, updates: [UseAgentUpdate.OnStateChanged, UseAgentUpdate.OnRunStatusChanged], });前端据此读取agent.state.delegations委派列表与agent.isRunning监督者是否在运行两者共同驱动左侧委派日志。2. 委派日志组件delegation-log.tsx 的DelegationLog组件负责左侧面板渲染头部显示标题、Supervisor running 状态徽章isRunning为真时出现以及{delegations.length} calls计数中部始终渲染三个子代理的指示徽章subagent-indicator-role无论是否已委派过——便于用户和 e2e 套件一眼看清存在哪些子代理、哪些已被触发data-fired列表中每个delegation-entry展示序号、角色徽章、状态completed、任务描述与最终结果空列表时提示Ask the supervisor to complete a task...。Delegation的 TypeScript 类型与后端写入结构一一对应export interface Delegation { id: string; sub_agent: SubAgentName; // research_agent | writing_agent | critique_agent task: string; status: completed; result: string; }3. 当前活跃子代理推断active-subagent.ts 的inferActiveSubAgent采用防御式结构探测遍历消息流找出最近一条尚未收到ToolMessage回应的监督者工具调用对research/writing/critique三个工具名精确匹配并尽力从流式的部分 JSON 工具参数中解析出task字段先严格JSON.parse失败则用正则嗅探task: ...最终回退占位文案。若消息流为空则回退到委派列表中最新一条非completed条目作为软信号。该结果驱动聊天面板顶部的 supervisor-activity-banner.tsx 粘性横幅——即使内联卡片滚出视口用户也能看到某子代理正在运行哪个任务。4. 聊天流内的内联活动卡片除左侧日志外page.tsx 还用三个useRenderTool为每个子代理工具注册内联渲染器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 中的卡片状态沿inProgress → executing → complete推进对应徽章文案starting → running → donecomplete前显示正在工作…占位完成后才挂载data-testidsubagent-result的结果区块。三个子代理分别有独立的 emoji、角色文案与配色研究 紫、写作 ✍️ 绿、评审 橙。5. 建议提示词suggestions.ts 通过useConfigureSuggestions提供三个常驻建议 chip每个都明确要求按 research → write → critique 顺序执行Write a blog postProduce a short blog post about the benefits of cold exposure training. Research first, then write, then critique.Explain a topicExplain how large language models handle tool calling. Research, write a paragraph, then critique.Summarize a topicSummarize the current state of reusable rockets in 1 polished paragraph, with research and critique.如何运行与体验启动方式见 agno 集成包的 package.json 中的dev脚本npm run dev该命令同时启动两部分next dev --turbopackNext.js 前端含/api/copilotkit运行时路由和PYTHONPATH. python -m uvicorn agent_server:app --host 0.0.0.0 --port 8000 --reloadAgno 后端服务。前端通过AGENT_URL默认http://localhost:8000代理到后端的/subagents/agui端点依赖OPENAI_API_KEY环境变量提供模型能力。体验路径打开子代理演示页 → 点击任一建议 chip 或自行输入提示词 → 观察聊天流中的内联活动卡片依次出现研究 → 写作 → 评审同时左侧委派日志逐条增长、计数更新、指示徽章点亮。用户也可以给监督者下达任意任务例如让它在撰写段落前先做研究、再对成稿给出评审意见。测试验证端到端守护核心行为仓库为这一演示配套了完整的 Playwright 端到端测试 tests/e2e/subagents.spec.ts覆盖了四条关键行为页面加载完整性输入框、3 个建议 pill、3 个常驻子代理指示徽章均可见三条提示词链路每个 pill 点击后三个角色卡片subagent-card-role都达到complete且每个卡片的subagent-result非空、不含Hi there! Im your showcase assistant等助手样板文本——该断言专门防止回归中 Writer/Critic 卡片泄漏聊天欢迎语的问题Summarize 回归专门标注该 pill 历史上曾因delegations状态键未声明 reducer 而返回INVALID_CONCURRENT_GRAPH_UPDATE的 400 错误测试确认当前实现可稳定到达全部三个卡片done状态Critic 恰好运行一次点击后断言 critic 卡片数量为 1 且状态保持complete再停留 5 秒复查数量与状态不变防止评审循环supervisor 反复重新进入 critic回归。测试通过data-testid系列选择器copilot-suggestion、subagent-indicator-*、subagent-card-*、subagent-status、subagent-result与前端组件解耦前后端职责清晰。小结纵观整条链路本演示给出了一套可直接复用的多智能体委派范式的完整参考实现后端Agno子代理即Agent监督者通过普通 Python 函数工具委派委派记录写入session_state[delegations]状态经历 running → completed/failed协议层AG-UI自定义路由器在每次 run 结束时发射StateSnapshotEvent补齐 Agno 默认 AGUI 不推送状态的缺口前端CopilotKit v2useAgent订阅OnStateChanged/OnRunStatusChanged驱动委派日志useRenderTool在聊天流内渲染每笔委派的活动卡片。如果你需要在其他 Agno 集成中复用此模式需要三处配套改动定义子代理与委派工具、挂载状态感知的 AGUI 路由、在 CopilotKit 运行时中把代理名映射到/xxx/agui端点。三者缺一实时委派日志都无法工作。【免费下载链接】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），仅供参考 基于 Agno 的 CopilotKit 子代理编排实战：监督者委派模式与实时委派日志
基于 Agno 的 CopilotKit 子代理编排实战监督者委派模式与实时委派日志【免费下载链接】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 演示 为核心深入剖析一套可复用的**多智能体委派Multi-agent Delegation**实现方案一个监督者SupervisorLLM 通过工具调用将任务分派给三个专业子代理研究、写作、评审并把每次委派实时推送到前端形成委派日志。读完本文你将掌握如何用 AgnoAgent定义子代理即工具的完整链路、如何借 AG-UI 协议的StateSnapshotEvent把后端共享状态回传到前端、以及如何用useAgent/useRenderTool渲染实时委派状态。本文以仓库内真实源码为唯一依据所有代码片段均来自当前仓库。演示总览监督者 三个专业子代理该演示位于showcase/integrations/agno/src/app/demos/subagents/其核心思路一句话概括监督者不亲自干活而是把任务拆解后委派给三个各司其职的子代理并将每笔委派记录写入共享状态。三个子代理各自是独立的 AgnoAgent实例见 subagents.pyresearch_agent收集事实输出 3–5 条要点列表writing_agent根据简报与事实产出一段润色好的草稿critique_agent对草稿给出 2–3 条可执行的评审意见。每个子代理都有独立的系统提示词互不共享内存与工具监督者只能看到子代理的最终文本输出。子代理统一使用gpt-4o-mini模型_SUB_MODEL_ID gpt-4o-mini并设置 120 秒超时。监督者本身也是一个 AgnoAgentsubagents.pyagent Agent( modelOpenAIChat(id_SUB_MODEL_ID, timeout120), tools[research_agent, writing_agent, critique_agent], descriptionSupervisor agent coordinating research / writing / critique sub-agents., instructions_SUPERVISOR_INSTRUCTION, tool_call_limit10, )其系统提示词_SUPERVISOR_INSTRUCTION明确要求对大多数非平凡请求按research → write → critique的顺序依次委派把相关事实/草稿通过每个工具的task参数传递如果某个子代理失败如实向用户说明失败原因而非编造结果并自行决定是否重试。子代理即工具委派工具的实现细节演示的关键模式是子代理以工具的形式暴露给监督者。在 subagents.py 中三个委派工具research_agent(task)、writing_agent(task)、critique_agent(task)都收敛到同一个_delegate流程def _delegate(run_context, *, sub_agent_name, sub_agent, task): entry_id _append_delegation( run_context, sub_agentsub_agent_name, tasktask, statusrunning, result, ) try: result _invoke_sub_agent(sub_agent, task) except Exception as exc: # 只把异常类名暴露给上层完整堆栈留在服务端日志 _update_delegation(run_context, entry_identry_id, statusfailed, resultmessage) return {status: failed, error: message} _update_delegation(run_context, entry_identry_id, statuscompleted, resultresult) return {status: completed, result: result}委派条目写入共享状态_append_delegationsubagents.py把每次委派追加到run_context.session_state[delegations]entry { id: entry_id, # uuid4 sub_agent: sub_agent, # research_agent / writing_agent / critique_agent task: task, status: status, # running / completed / failed result: result, } run_context.session_state[delegations] delegations_update_delegationsubagents.py则按entry_id定位并更新条目的状态与结果。如果条目已丢失被其他环节替换了delegations数组只记录一条logger.warning而绝不追加合成条目——这一保守行为与仓库中 google-adk 参考实现保持一致。值得注意的是委派失败的错误信息只暴露异常类名避免把携带 URL、请求 ID 或部分凭据的提供方错误串泄露到前端。一次委派的完整生命周期从状态槽视角看一次委派经历三个阶段running_append_delegation先插入一条statusrunning的条目子代理执行_invoke_sub_agent同步调用sub_agent.run(inputtask)取回result.contentcompleted / failed_update_delegation把最终结果写回同一条记录。工具返回的字典{status: completed, result: ...}同时成为监督者的工具结果ToolMessage供其下一步决策如把研究结果作为写作任务的输入。说明该演示的同名 README 沿用了跨框架共享的表述如 LangGraph 的Command与create_agent。在当前 Agno 实现中这一模式由run_context.session_state的delegations槽位等价实现其追加共享状态 以工具消息回传结果的语义完全一致。共享状态如何到达前端AG-UI 与 StateSnapshotEventAgno 自带的 AGUI 路由器默认不会向后端客户端发射StateSnapshotEvent这会导致依赖useAgent({ updates: [OnStateChanged] })的前端收不到共享状态变化。为此仓库在 agent_server.py 中实现了一个状态感知的 AGUI 处理器_run_agent_with_state_snapshot复刻官方agno.os.interfaces.agui.router.run_agent的流式逻辑抑制内层流的RUN_STARTED/RUN_FINISHED在流结束后、发出自己的RunFinishedEvent之前发射一条携带最终session_state的StateSnapshotEvent快照优先通过agent.aget_session_state(session_idthread_id)或同步的get_session_state读取确保合并了会话数据库中落盘的任何额外状态读取失败则回退到内存快照。随后通过_attach_state_aware_route将该处理器挂载到/subagents/agui路由agent_server.py。这是双向共享状态契约的关键/subagents/agui与共享状态读写演示/shared-state-rw/agui使用同一套路由器。在前端侧Next.js 运行时通过 copilotkit/route.ts 把subagents代理名映射到该后端端点function createSubagentsAgent() { return new HttpAgent({ url: ${AGENT_URL}/subagents/agui }); } // ... agents[subagents] createSubagentsAgent();后端默认跑在AGENT_URL || http://localhost:8000与agent_server.py中/subagents前缀的 AGUI 端点对应。前端实时委派日志的实现1. Provider 与 useAgent 订阅page.tsx 中CopilotKit提供者指定agentsubagents页面组件用useAgent订阅状态变化与运行状态变化CopilotKit runtimeUrl/api/copilotkit agentsubagents DemoContent / /CopilotKit const { agent } useAgent({ agentId: subagents, updates: [UseAgentUpdate.OnStateChanged, UseAgentUpdate.OnRunStatusChanged], });前端据此读取agent.state.delegations委派列表与agent.isRunning监督者是否在运行两者共同驱动左侧委派日志。2. 委派日志组件delegation-log.tsx 的DelegationLog组件负责左侧面板渲染头部显示标题、Supervisor running 状态徽章isRunning为真时出现以及{delegations.length} calls计数中部始终渲染三个子代理的指示徽章subagent-indicator-role无论是否已委派过——便于用户和 e2e 套件一眼看清存在哪些子代理、哪些已被触发data-fired列表中每个delegation-entry展示序号、角色徽章、状态completed、任务描述与最终结果空列表时提示Ask the supervisor to complete a task...。Delegation的 TypeScript 类型与后端写入结构一一对应export interface Delegation { id: string; sub_agent: SubAgentName; // research_agent | writing_agent | critique_agent task: string; status: completed; result: string; }3. 当前活跃子代理推断active-subagent.ts 的inferActiveSubAgent采用防御式结构探测遍历消息流找出最近一条尚未收到ToolMessage回应的监督者工具调用对research/writing/critique三个工具名精确匹配并尽力从流式的部分 JSON 工具参数中解析出task字段先严格JSON.parse失败则用正则嗅探task: ...最终回退占位文案。若消息流为空则回退到委派列表中最新一条非completed条目作为软信号。该结果驱动聊天面板顶部的 supervisor-activity-banner.tsx 粘性横幅——即使内联卡片滚出视口用户也能看到某子代理正在运行哪个任务。4. 聊天流内的内联活动卡片除左侧日志外page.tsx 还用三个useRenderTool为每个子代理工具注册内联渲染器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 中的卡片状态沿inProgress → executing → complete推进对应徽章文案starting → running → donecomplete前显示正在工作…占位完成后才挂载data-testidsubagent-result的结果区块。三个子代理分别有独立的 emoji、角色文案与配色研究 紫、写作 ✍️ 绿、评审 橙。5. 建议提示词suggestions.ts 通过useConfigureSuggestions提供三个常驻建议 chip每个都明确要求按 research → write → critique 顺序执行Write a blog postProduce a short blog post about the benefits of cold exposure training. Research first, then write, then critique.Explain a topicExplain how large language models handle tool calling. Research, write a paragraph, then critique.Summarize a topicSummarize the current state of reusable rockets in 1 polished paragraph, with research and critique.如何运行与体验启动方式见 agno 集成包的 package.json 中的dev脚本npm run dev该命令同时启动两部分next dev --turbopackNext.js 前端含/api/copilotkit运行时路由和PYTHONPATH. python -m uvicorn agent_server:app --host 0.0.0.0 --port 8000 --reloadAgno 后端服务。前端通过AGENT_URL默认http://localhost:8000代理到后端的/subagents/agui端点依赖OPENAI_API_KEY环境变量提供模型能力。体验路径打开子代理演示页 → 点击任一建议 chip 或自行输入提示词 → 观察聊天流中的内联活动卡片依次出现研究 → 写作 → 评审同时左侧委派日志逐条增长、计数更新、指示徽章点亮。用户也可以给监督者下达任意任务例如让它在撰写段落前先做研究、再对成稿给出评审意见。测试验证端到端守护核心行为仓库为这一演示配套了完整的 Playwright 端到端测试 tests/e2e/subagents.spec.ts覆盖了四条关键行为页面加载完整性输入框、3 个建议 pill、3 个常驻子代理指示徽章均可见三条提示词链路每个 pill 点击后三个角色卡片subagent-card-role都达到complete且每个卡片的subagent-result非空、不含Hi there! Im your showcase assistant等助手样板文本——该断言专门防止回归中 Writer/Critic 卡片泄漏聊天欢迎语的问题Summarize 回归专门标注该 pill 历史上曾因delegations状态键未声明 reducer 而返回INVALID_CONCURRENT_GRAPH_UPDATE的 400 错误测试确认当前实现可稳定到达全部三个卡片done状态Critic 恰好运行一次点击后断言 critic 卡片数量为 1 且状态保持complete再停留 5 秒复查数量与状态不变防止评审循环supervisor 反复重新进入 critic回归。测试通过data-testid系列选择器copilot-suggestion、subagent-indicator-*、subagent-card-*、subagent-status、subagent-result与前端组件解耦前后端职责清晰。小结纵观整条链路本演示给出了一套可直接复用的多智能体委派范式的完整参考实现后端Agno子代理即Agent监督者通过普通 Python 函数工具委派委派记录写入session_state[delegations]状态经历 running → completed/failed协议层AG-UI自定义路由器在每次 run 结束时发射StateSnapshotEvent补齐 Agno 默认 AGUI 不推送状态的缺口前端CopilotKit v2useAgent订阅OnStateChanged/OnRunStatusChanged驱动委派日志useRenderTool在聊天流内渲染每笔委派的活动卡片。如果你需要在其他 Agno 集成中复用此模式需要三处配套改动定义子代理与委派工具、挂载状态感知的 AGUI 路由、在 CopilotKit 运行时中把代理名映射到/xxx/agui端点。三者缺一实时委派日志都无法工作。【免费下载链接】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），仅供参考