Agno AgentOS 的 AG-UI 接口实战从事件流协议到前端交互式 Agent 构建指南【免费下载链接】agnoBuild, run, and manage agent platforms.项目地址: https://gitcode.com/GitHub_Trending/ag/agnoAG-UIAgent User Interface是一种连接 Agent 后端与交互式前端的事件流event-stream协议。在 Agno 项目中AgentOS 将 Agent 与 Team 的运行事件翻译成 AG-UI 的 text、tool、reasoning、state 与 lifecycle 事件同时把模型、工具、会话session与审批状态全部保留在服务端。本指南以 cookbook/05_agent_os/16_agui/ 目录下的 9 个独立可运行示例为主干结合 AG-UI 接口源码讲解如何把一个 Agno Agent 或 Team 挂载成标准的POST /aguiGET /status服务如何用 curl 或 CopilotKit、AG-UI Dojo 等客户端消费事件流以及如何通过 OpenUI 把 Agent 渲染成图表、跟进建议与校验表单。读完本文你将掌握AG-UI 的事件流结构与核心事件类型AGUI接口类与AgentOS的挂载方式及prefix路由机制前端定义工具与后端requires_confirmation审批两种暂停模式的区别与配合共享状态快照与 JSON Patch 增量同步多模态媒体如何送入 Gemini以及把单个 AgentOS 暴露成多个独立 AG-UI 实例、再用 OpenUI 前端渲染生成式 UI 的完整方案。一、AG-UI 在 Agno 中的定位一个 AgentOS 接口AG-UI 是一个「事件流协议」不是一个新的 Agent 框架。在 Agno 中它由 AgentOS 的一个标准接口实现对应源码为 libs/agno/agno/os/interfaces/agui/agui.py。核心类AGUI继承自BaseInterface构造参数包括agent要暴露的 Agent或RemoteAgentteam要暴露的 Team或RemoteTeam与agent二选一两者都不传会抛出ValueErrorprefix路由前缀默认源码注释中示例为/agui/v1、/chat/public示例文件中可见/tools、/reasoning等实际用法tags路由标签默认[AGUI]。get_router()内部以prefix为前缀创建APIRouter并调用 router.py 中的attach_routes挂载路由get_scope_mappings()则把POST {prefix}/agui映射到agents:run传 Agent 时或teams:run传 Team 时权限作用域。每个示例都是一个独立的服务器客户端向POST {prefix}/agui发送一个RunAgentInput服务端返回text/event-stream同一接口还暴露GET {prefix}/status。默认空前缀下这两个路由就是POST /agui与GET /status。模型、工具、会话状态与审批状态全部留在服务端前端只消费事件流——这是 AG-UI 与普通 REST 聊天接口最大的区别。二、环境准备与运行方式先安装演示环境再导出示例文件所需的服务商密钥./scripts/demo_setup.sh export OPENAI_API_KEY... export GOOGLE_API_KEY... # 仅 agent_with_media.py 需要research_team.py因使用WebSearchTools还需要联网。每个独立服务器都固定使用 7777 端口一次启动一个示例.venvs/demo/bin/python cookbook/05_agent_os/16_agui/basic.py .venvs/demo/bin/python cookbook/05_agent_os/16_agui/agent_with_tools.py .venvs/demo/bin/python cookbook/05_agent_os/16_agui/structured_output.py .venvs/demo/bin/python cookbook/05_agent_os/16_agui/reasoning_agent.py .venvs/demo/bin/python cookbook/05_agent_os/16_agui/agent_with_media.py .venvs/demo/bin/python cookbook/05_agent_os/16_agui/shared_state.py .venvs/demo/bin/python cookbook/05_agent_os/16_agui/human_in_the_loop.py .venvs/demo/bin/python cookbook/05_agent_os/16_agui/research_team.py .venvs/demo/bin/python cookbook/05_agent_os/16_agui/multiple_instances.py其中openui/示例自带 React 客户端需要按其 README 生成 OpenUI 组件提示词、运行openui/server.py并启动前端。各示例的端点一览运行文件POST 事件流状态接口basic.pyhttp://localhost:7777/aguihttp://localhost:7777/statusagent_with_tools.pyhttp://localhost:7777/tools/aguihttp://localhost:7777/tools/statusstructured_output.pyhttp://localhost:7777/structured-output/aguihttp://localhost:7777/structured-output/statusreasoning_agent.pyhttp://localhost:7777/reasoning/aguihttp://localhost:7777/reasoning/statusagent_with_media.pyhttp://localhost:7777/media/aguihttp://localhost:7777/media/statusshared_state.pyhttp://localhost:7777/shared-state/aguihttp://localhost:7777/shared-state/statushuman_in_the_loop.pyhttp://localhost:7777/human-in-the-loop/aguihttp://localhost:7777/human-in-the-loop/statusresearch_team.pyhttp://localhost:7777/research-team/aguihttp://localhost:7777/research-team/statusmultiple_instances.pyhttp://localhost:7777/chat/agui与http://localhost:7777/analyst/agui/chat/status与/analyst/statusopenui/server.pyhttp://localhost:7777/aguihttp://localhost:7777/status需要说明的是旧的「all-in-one showcase」已被有意移除你正在学习的文件启动后其对应端点直接可用不再依赖仅供 import 的辅助模块——每个示例都是自洽的最小可运行服务。三、最小事件流basic.py 与 RunAgentInputbasic.py 是理解 AG-UI 的入口。它创建SqliteDb持久化会话构造一个使用OpenAIResponses的 Agent然后通过AgentOS(agents[...], interfaces[AGUI(agentassistant)])把 Agent 挂载为默认前缀接口最后agent_os.get_app()取得 FastAPI 应用并用agent_os.serve(appapp)启动。针对该服务的最小请求如下curl -N http://localhost:7777/agui \ -H Content-Type: application/json \ -d { threadId: agui-readme-thread, runId: agui-readme-run, state: {}, messages: [ {id: message-1, role: user, content: Say hello in five words.} ], tools: [], context: [], forwardedProps: {} }请求字段含义threadId线程 ID会被用作Agno 会话 IDsession ID后续请求使用同一threadId即可延续同一段对话runId本次运行 ID用于区分同一线程内的多次运行stateAG-UI 共享状态字典示例中传空{}messages消息数组每一条包含id、role如user、contenttools请求级工具定义数组即前端提供的工具见第四节空数组表示无context上下文容器forwardedPropsAG-UI 扩展容器Agno 的RunAgentInput模型要求该字段存在OpenUI 客户端会显式发送空对象见 openui/frontend/src/agno.ts。事件流的生命周期固定为以RUN_STARTED开始 → 逐条发出消息事件或能力相关事件 → 以RUN_FINISHED结束。工具调用使用TOOL_CALL_*事件推理过程使用REASONING_*事件共享状态使用STATE_SNAPSHOT与STATE_DELTA事件。这些事件类型共同构成了前端还原完整 Agent 行为所需的信息也是 AgentOS 在 stream.py 与 handlers.py 中逐类转换的产物。四、前端工具与后端 HITL两种「暂停」的归属差异UI 上看起来相似的两种暂停模式其所有权完全不同这是使用 AG-UI 时最容易混淆的一点模式工具在哪里谁来执行示例前端定义工具Frontend-defined tool客户端在RunAgentInput.tools中发送工具 schema后端没有对应的 Python 实现浏览器执行并通过一条尾部 AG-UI 工具消息回传结果agent_with_tools.py后端确认Backend confirmationPython 注册真实的tool(requires_confirmationTrue)实现AgentOS 持久化被暂停的运行前端回发{accepted: true}或拒绝然后 AgentOS 恢复运行并有条件地执行 Pythonhuman_in_the_loop.py后端的暂停/恢复机制本身requires_confirmation、continue_run、approval记录由 cookbook/05_agent_os/05_human_in_the_loop/ 目录专门讲解本目录只覆盖 AG-UI 如何呈现它们。4.1 前端定义工具请求级 schema 的 external_executionagent_with_tools.py 同时演示了两种工具get_weather是注册在 Python 侧的真实后端工具tool装饰器 tools[get_weather]在服务端直接执行而change_background可以完全由前端提供。例如 CopilotKit 前端在请求中携带{ name: change_background, description: Change the page background to a CSS value., parameters: { type: object, properties: {background: {type: string}}, required: [background] } }AG-UI 适配器会把这份请求作用域request-scoped的定义转换为一个没有服务端入口点的external_execution函数第一条事件流返回它的工具调用 ID浏览器执行完页面背景修改后发送一条携带该 ID 的尾部工具消息恢复持久化的运行。这种模式下 Agent 的指令instructions中会提示当前端提供change_background且用户要求改背景时就调用它并传入 CSS 颜色或渐变值。4.2 后端确认requires_confirmation 的暂停与恢复human_in_the_loop.py 中的send_email是真实存在于服务端且可执行的 Python 工具但被tool(requires_confirmationTrue)标记因此在用户确认之前不会真正运行tool(requires_confirmationTrue) def send_email(to: str, subject: str, body: str) - str: Simulate sending one email after a user confirms its contents. return fEmail sent to {to} with subject {subject}.流程是Agent 调用send_email→ AgentOS 暂停该运行并把确认要求以事件流推给前端 → 前端展示确认 UI → 用户接受或拒绝 → 前端回发结果AgentOS 恢复运行并有条件地执行 Python。示例的instructions还特别强调不要在回复正文里用文字询问确认确认收集交给 AG-UI 前端工具结果可用之前不得声称send_email已执行。这保证了审批状态全程由服务端掌握前端只是确认交互的呈现层。五、结构化输出、推理与共享状态5.1 用 Pydantic schema 约束流式输出structured_output.py 为 Agent 设置output_schemaMoviePitch一个包含title、genre、setting、characters、storyline五个字段的 PydanticBaseModel。流式返回的内容会被约束为该结构前端收到的是可预测、可反序列化的字段级文本事件而非自由格式回答。把output_schema换成任意业务模型即可得到同样稳定的流式结构化输出。5.2 把推理生命周期翻译为 REASONING 事件reasoning_agent.py 在 Agent 上同时设置modelOpenAIResponses(idgpt-5.6)与reasoning_modelOpenAIResponses(ido3-mini)启用 Agno 的推理循环。AgentOS 会把推理生命周期转换成 AG-UI 的REASONING_START、推理内容与推理结束事件最终答案之前的事件流中可见完整推理过程。前端因此可以区分「思考中」与「作答中」两种状态并分别渲染。5.3 状态快照与 JSON Patch 增量shared_state.py 演示了 AG-UI 状态同步的完整闭环请求携带一个食谱形状的INITIAL_RECIPE状态字典Agent 以session_stateINITIAL_RECIPE初始化会话状态并开启add_session_state_to_contextTrue与enable_agentic_stateTrue运行前对状态字典做快照Agent 通过内置工具update_session_state修改状态工具调用后发出一个JSON Patch 增量STATE_DELTA最后以权威快照STATE_SNAPSHOT收尾。前端既可以按增量渐进式更新 UI适合大状态对象也可以在结束时用快照做一次最终对齐。指令中要求 Agent 在每次状态更新后用一句话总结变更形成「状态变更 → 用户可见反馈」的一致体验。六、多模态媒体与 Team 事件流6.1 把 AG-UI 媒体部件送入 Geminiagent_with_media.py 使用Gemini(idgemini-3.5-flash)多模态模型因此需要GOOGLE_API_KEY。媒体应当放在最新一条用户消息中作为 AG-UI 的 image、audio、video 或 document 内容部件。适配器会把 URL 或 base64 两种数据源转换成 Agno 的 media 对象再交给 Gemini。Agent 指令要求只依据所附内容作答并在细节不清时明说避免幻觉。6.2 Team 级协调活动流式化research_team.py 把Team挂到 AG-UI 上researcher带WebSearchTools负责检索writer负责综合Team 以show_members_responsesTrue公开成员响应。挂载方式是AgentOS(teams[research_team], interfaces[AGUI(teamresearch_team, prefix/research-team)])。前端在同一条事件流中既能看到成员的工具调用也能看到协调后的最终答案适合「搜索—综合」类多智能体场景。七、单 AgentOS 多接口multiple_instances.pymultiple_instances.py 演示如何用一个 AgentOS 暴露两个互相独立的 AG-UI 接口interfaces[ AGUI(agentchat_agent, prefix/chat), AGUI(agentanalyst_agent, prefix/analyst), ],每个前缀获得各自的POST /agui与GET /status路由即/chat/agui/chat/status与/analyst/agui/analyst/status两个 Agent 可以有不同的模型、指令与工具共用同一个进程与同一个SqliteDb。这正对应AGUI.__init__中prefix的设计意图在同一个 FastAPI 应用里按前缀隔离多套会话。若需要更细粒度prefix也可写成/agui/v1、/chat/public这种带版本或权限语义的路径。八、用 OpenUI 渲染生成式 UIopenui/ 是一个完整的「Agent 即生成式 UI」示例分工明确Agno拥有 Agent、工具、对话历史与 AG-UI 事件流OpenUI拥有组件提示词、流式解析器、渲染器、主题与浏览器交互。架构链路如下React AgentInterface - POST /agui with RunAgentInput - Agno AgentOS AGUI - OpenAI model returns OpenUI Lang in AG-UI text events - OpenUI parser and renderer stream interactive React components8.1 运行步骤前置条件Python 3.9、Node.js 20.19或 22.12、OPENAI_API_KEY。OPENAI_MODEL为可选环境变量默认gpt-5.5。# 1. 安装演示环境并导出密钥 ./scripts/demo_setup.sh export OPENAI_API_KEY... # 2. 安装前端依赖并生成 OpenUI 系统提示词 cd cookbook/05_agent_os/16_agui/openui/frontend npm install npm run generate:prompt # 3. 终端一从仓库根目录启动 Agno 服务器 .venvs/demo/bin/python cookbook/05_agent_os/16_agui/openui/server.py # 4. 终端二启动前端 cd cookbook/05_agent_os/16_agui/openui/frontend npm run dev打开http://localhost:5173Vite 会把/agui与/status代理到 7777 端口的 AgentOS。server.py 会在启动时检查frontend/src/generated/system-prompt.txt是否存在缺失即报错提示先执行npm install与npm run generate:prompt。8.2 前端适配细节与可尝试场景frontend/src/agno.ts用一个小型过滤器包装 OpenUI 的agUIAdapter转发 text、tool、error 事件同时抑制运行元数据与 Agno 的空 tool-parent 文本外壳让工具结果在 OpenUI 时间线中与对应的工具调用紧密配对客户端还会发送空的state与forwardedProps对象因为 Agno 的RunAgentInput模型要求这两个 AG-UI 扩展容器。值得尝试的三个场景图表 跟进建议渲染 Q1–Q4 营收图与两个可点击的后续步骤校验表单渲染必填的项目名、团队规模、备注字段空提交触发本地校验填入Aurora-731、7、Prioritize accessibility and charts后以一次结构化轮次回传给 AgnoAgno 工具调用 Python Agent 侧的get_quarterly_revenue工具并把结果渲染为图表。验证前端可用npm run typecheck、npm test、npm run build。注意生成提示词与组件规格属于构建产物修改frontend/src/library.ts后需重新生成。九、快速参考AG-UI 事件类型与接口配置事件类别事件类型触发场景生命周期RUN_STARTED/RUN_FINISHED每次运行的开始与结束构成事件流边界工具调用TOOL_CALL_*后端工具与前端external_execution工具的调用与结果回传推理REASONING_*启用reasoning_model后的推理过程状态STATE_SNAPSHOT/STATE_DELTA共享状态快照与 JSON Patch 增量AGUI接口核心配置速查见 agui.pyagent/team二选一必填其一prefix路由前缀默认控制POST {prefix}/agui与GET {prefix}/statustags路由标签默认[AGUI]。结语AG-UI 把「交互式前端」与「Agent 后端」之间的耦合收敛为一个标准化事件流Agno 负责把 Agent/Team 的运行翻译成 text、tool、reasoning、state 与 lifecycle 事件前端只需按协议消费。从basic.py的最小事件流到agent_with_tools.py与human_in_the_loop.py两种暂停模式的对比再到shared_state.py的状态增量同步、agent_with_media.py的多模态输入、research_team.py的团队流式化与multiple_instances.py的多接口挂载这 9 个独立服务器构成了从「会跑的接口」到「生产级交互前端」的完整进阶路径。若想继续深入可以阅读 AG-UI 接口源码 中的 router.py 与 stream.py 观察事件翻译细节或参照 cookbook/05_agent_os/05_human_in_the_loop/ 掌握后端审批机制的完整实现。【免费下载链接】agnoBuild, run, and manage agent platforms.项目地址: https://gitcode.com/GitHub_Trending/ag/agno创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Agno AgentOS 的 AG-UI 接口实战：从事件流协议到前端交互式 Agent 构建指南
Agno AgentOS 的 AG-UI 接口实战从事件流协议到前端交互式 Agent 构建指南【免费下载链接】agnoBuild, run, and manage agent platforms.项目地址: https://gitcode.com/GitHub_Trending/ag/agnoAG-UIAgent User Interface是一种连接 Agent 后端与交互式前端的事件流event-stream协议。在 Agno 项目中AgentOS 将 Agent 与 Team 的运行事件翻译成 AG-UI 的 text、tool、reasoning、state 与 lifecycle 事件同时把模型、工具、会话session与审批状态全部保留在服务端。本指南以 cookbook/05_agent_os/16_agui/ 目录下的 9 个独立可运行示例为主干结合 AG-UI 接口源码讲解如何把一个 Agno Agent 或 Team 挂载成标准的POST /aguiGET /status服务如何用 curl 或 CopilotKit、AG-UI Dojo 等客户端消费事件流以及如何通过 OpenUI 把 Agent 渲染成图表、跟进建议与校验表单。读完本文你将掌握AG-UI 的事件流结构与核心事件类型AGUI接口类与AgentOS的挂载方式及prefix路由机制前端定义工具与后端requires_confirmation审批两种暂停模式的区别与配合共享状态快照与 JSON Patch 增量同步多模态媒体如何送入 Gemini以及把单个 AgentOS 暴露成多个独立 AG-UI 实例、再用 OpenUI 前端渲染生成式 UI 的完整方案。一、AG-UI 在 Agno 中的定位一个 AgentOS 接口AG-UI 是一个「事件流协议」不是一个新的 Agent 框架。在 Agno 中它由 AgentOS 的一个标准接口实现对应源码为 libs/agno/agno/os/interfaces/agui/agui.py。核心类AGUI继承自BaseInterface构造参数包括agent要暴露的 Agent或RemoteAgentteam要暴露的 Team或RemoteTeam与agent二选一两者都不传会抛出ValueErrorprefix路由前缀默认源码注释中示例为/agui/v1、/chat/public示例文件中可见/tools、/reasoning等实际用法tags路由标签默认[AGUI]。get_router()内部以prefix为前缀创建APIRouter并调用 router.py 中的attach_routes挂载路由get_scope_mappings()则把POST {prefix}/agui映射到agents:run传 Agent 时或teams:run传 Team 时权限作用域。每个示例都是一个独立的服务器客户端向POST {prefix}/agui发送一个RunAgentInput服务端返回text/event-stream同一接口还暴露GET {prefix}/status。默认空前缀下这两个路由就是POST /agui与GET /status。模型、工具、会话状态与审批状态全部留在服务端前端只消费事件流——这是 AG-UI 与普通 REST 聊天接口最大的区别。二、环境准备与运行方式先安装演示环境再导出示例文件所需的服务商密钥./scripts/demo_setup.sh export OPENAI_API_KEY... export GOOGLE_API_KEY... # 仅 agent_with_media.py 需要research_team.py因使用WebSearchTools还需要联网。每个独立服务器都固定使用 7777 端口一次启动一个示例.venvs/demo/bin/python cookbook/05_agent_os/16_agui/basic.py .venvs/demo/bin/python cookbook/05_agent_os/16_agui/agent_with_tools.py .venvs/demo/bin/python cookbook/05_agent_os/16_agui/structured_output.py .venvs/demo/bin/python cookbook/05_agent_os/16_agui/reasoning_agent.py .venvs/demo/bin/python cookbook/05_agent_os/16_agui/agent_with_media.py .venvs/demo/bin/python cookbook/05_agent_os/16_agui/shared_state.py .venvs/demo/bin/python cookbook/05_agent_os/16_agui/human_in_the_loop.py .venvs/demo/bin/python cookbook/05_agent_os/16_agui/research_team.py .venvs/demo/bin/python cookbook/05_agent_os/16_agui/multiple_instances.py其中openui/示例自带 React 客户端需要按其 README 生成 OpenUI 组件提示词、运行openui/server.py并启动前端。各示例的端点一览运行文件POST 事件流状态接口basic.pyhttp://localhost:7777/aguihttp://localhost:7777/statusagent_with_tools.pyhttp://localhost:7777/tools/aguihttp://localhost:7777/tools/statusstructured_output.pyhttp://localhost:7777/structured-output/aguihttp://localhost:7777/structured-output/statusreasoning_agent.pyhttp://localhost:7777/reasoning/aguihttp://localhost:7777/reasoning/statusagent_with_media.pyhttp://localhost:7777/media/aguihttp://localhost:7777/media/statusshared_state.pyhttp://localhost:7777/shared-state/aguihttp://localhost:7777/shared-state/statushuman_in_the_loop.pyhttp://localhost:7777/human-in-the-loop/aguihttp://localhost:7777/human-in-the-loop/statusresearch_team.pyhttp://localhost:7777/research-team/aguihttp://localhost:7777/research-team/statusmultiple_instances.pyhttp://localhost:7777/chat/agui与http://localhost:7777/analyst/agui/chat/status与/analyst/statusopenui/server.pyhttp://localhost:7777/aguihttp://localhost:7777/status需要说明的是旧的「all-in-one showcase」已被有意移除你正在学习的文件启动后其对应端点直接可用不再依赖仅供 import 的辅助模块——每个示例都是自洽的最小可运行服务。三、最小事件流basic.py 与 RunAgentInputbasic.py 是理解 AG-UI 的入口。它创建SqliteDb持久化会话构造一个使用OpenAIResponses的 Agent然后通过AgentOS(agents[...], interfaces[AGUI(agentassistant)])把 Agent 挂载为默认前缀接口最后agent_os.get_app()取得 FastAPI 应用并用agent_os.serve(appapp)启动。针对该服务的最小请求如下curl -N http://localhost:7777/agui \ -H Content-Type: application/json \ -d { threadId: agui-readme-thread, runId: agui-readme-run, state: {}, messages: [ {id: message-1, role: user, content: Say hello in five words.} ], tools: [], context: [], forwardedProps: {} }请求字段含义threadId线程 ID会被用作Agno 会话 IDsession ID后续请求使用同一threadId即可延续同一段对话runId本次运行 ID用于区分同一线程内的多次运行stateAG-UI 共享状态字典示例中传空{}messages消息数组每一条包含id、role如user、contenttools请求级工具定义数组即前端提供的工具见第四节空数组表示无context上下文容器forwardedPropsAG-UI 扩展容器Agno 的RunAgentInput模型要求该字段存在OpenUI 客户端会显式发送空对象见 openui/frontend/src/agno.ts。事件流的生命周期固定为以RUN_STARTED开始 → 逐条发出消息事件或能力相关事件 → 以RUN_FINISHED结束。工具调用使用TOOL_CALL_*事件推理过程使用REASONING_*事件共享状态使用STATE_SNAPSHOT与STATE_DELTA事件。这些事件类型共同构成了前端还原完整 Agent 行为所需的信息也是 AgentOS 在 stream.py 与 handlers.py 中逐类转换的产物。四、前端工具与后端 HITL两种「暂停」的归属差异UI 上看起来相似的两种暂停模式其所有权完全不同这是使用 AG-UI 时最容易混淆的一点模式工具在哪里谁来执行示例前端定义工具Frontend-defined tool客户端在RunAgentInput.tools中发送工具 schema后端没有对应的 Python 实现浏览器执行并通过一条尾部 AG-UI 工具消息回传结果agent_with_tools.py后端确认Backend confirmationPython 注册真实的tool(requires_confirmationTrue)实现AgentOS 持久化被暂停的运行前端回发{accepted: true}或拒绝然后 AgentOS 恢复运行并有条件地执行 Pythonhuman_in_the_loop.py后端的暂停/恢复机制本身requires_confirmation、continue_run、approval记录由 cookbook/05_agent_os/05_human_in_the_loop/ 目录专门讲解本目录只覆盖 AG-UI 如何呈现它们。4.1 前端定义工具请求级 schema 的 external_executionagent_with_tools.py 同时演示了两种工具get_weather是注册在 Python 侧的真实后端工具tool装饰器 tools[get_weather]在服务端直接执行而change_background可以完全由前端提供。例如 CopilotKit 前端在请求中携带{ name: change_background, description: Change the page background to a CSS value., parameters: { type: object, properties: {background: {type: string}}, required: [background] } }AG-UI 适配器会把这份请求作用域request-scoped的定义转换为一个没有服务端入口点的external_execution函数第一条事件流返回它的工具调用 ID浏览器执行完页面背景修改后发送一条携带该 ID 的尾部工具消息恢复持久化的运行。这种模式下 Agent 的指令instructions中会提示当前端提供change_background且用户要求改背景时就调用它并传入 CSS 颜色或渐变值。4.2 后端确认requires_confirmation 的暂停与恢复human_in_the_loop.py 中的send_email是真实存在于服务端且可执行的 Python 工具但被tool(requires_confirmationTrue)标记因此在用户确认之前不会真正运行tool(requires_confirmationTrue) def send_email(to: str, subject: str, body: str) - str: Simulate sending one email after a user confirms its contents. return fEmail sent to {to} with subject {subject}.流程是Agent 调用send_email→ AgentOS 暂停该运行并把确认要求以事件流推给前端 → 前端展示确认 UI → 用户接受或拒绝 → 前端回发结果AgentOS 恢复运行并有条件地执行 Python。示例的instructions还特别强调不要在回复正文里用文字询问确认确认收集交给 AG-UI 前端工具结果可用之前不得声称send_email已执行。这保证了审批状态全程由服务端掌握前端只是确认交互的呈现层。五、结构化输出、推理与共享状态5.1 用 Pydantic schema 约束流式输出structured_output.py 为 Agent 设置output_schemaMoviePitch一个包含title、genre、setting、characters、storyline五个字段的 PydanticBaseModel。流式返回的内容会被约束为该结构前端收到的是可预测、可反序列化的字段级文本事件而非自由格式回答。把output_schema换成任意业务模型即可得到同样稳定的流式结构化输出。5.2 把推理生命周期翻译为 REASONING 事件reasoning_agent.py 在 Agent 上同时设置modelOpenAIResponses(idgpt-5.6)与reasoning_modelOpenAIResponses(ido3-mini)启用 Agno 的推理循环。AgentOS 会把推理生命周期转换成 AG-UI 的REASONING_START、推理内容与推理结束事件最终答案之前的事件流中可见完整推理过程。前端因此可以区分「思考中」与「作答中」两种状态并分别渲染。5.3 状态快照与 JSON Patch 增量shared_state.py 演示了 AG-UI 状态同步的完整闭环请求携带一个食谱形状的INITIAL_RECIPE状态字典Agent 以session_stateINITIAL_RECIPE初始化会话状态并开启add_session_state_to_contextTrue与enable_agentic_stateTrue运行前对状态字典做快照Agent 通过内置工具update_session_state修改状态工具调用后发出一个JSON Patch 增量STATE_DELTA最后以权威快照STATE_SNAPSHOT收尾。前端既可以按增量渐进式更新 UI适合大状态对象也可以在结束时用快照做一次最终对齐。指令中要求 Agent 在每次状态更新后用一句话总结变更形成「状态变更 → 用户可见反馈」的一致体验。六、多模态媒体与 Team 事件流6.1 把 AG-UI 媒体部件送入 Geminiagent_with_media.py 使用Gemini(idgemini-3.5-flash)多模态模型因此需要GOOGLE_API_KEY。媒体应当放在最新一条用户消息中作为 AG-UI 的 image、audio、video 或 document 内容部件。适配器会把 URL 或 base64 两种数据源转换成 Agno 的 media 对象再交给 Gemini。Agent 指令要求只依据所附内容作答并在细节不清时明说避免幻觉。6.2 Team 级协调活动流式化research_team.py 把Team挂到 AG-UI 上researcher带WebSearchTools负责检索writer负责综合Team 以show_members_responsesTrue公开成员响应。挂载方式是AgentOS(teams[research_team], interfaces[AGUI(teamresearch_team, prefix/research-team)])。前端在同一条事件流中既能看到成员的工具调用也能看到协调后的最终答案适合「搜索—综合」类多智能体场景。七、单 AgentOS 多接口multiple_instances.pymultiple_instances.py 演示如何用一个 AgentOS 暴露两个互相独立的 AG-UI 接口interfaces[ AGUI(agentchat_agent, prefix/chat), AGUI(agentanalyst_agent, prefix/analyst), ],每个前缀获得各自的POST /agui与GET /status路由即/chat/agui/chat/status与/analyst/agui/analyst/status两个 Agent 可以有不同的模型、指令与工具共用同一个进程与同一个SqliteDb。这正对应AGUI.__init__中prefix的设计意图在同一个 FastAPI 应用里按前缀隔离多套会话。若需要更细粒度prefix也可写成/agui/v1、/chat/public这种带版本或权限语义的路径。八、用 OpenUI 渲染生成式 UIopenui/ 是一个完整的「Agent 即生成式 UI」示例分工明确Agno拥有 Agent、工具、对话历史与 AG-UI 事件流OpenUI拥有组件提示词、流式解析器、渲染器、主题与浏览器交互。架构链路如下React AgentInterface - POST /agui with RunAgentInput - Agno AgentOS AGUI - OpenAI model returns OpenUI Lang in AG-UI text events - OpenUI parser and renderer stream interactive React components8.1 运行步骤前置条件Python 3.9、Node.js 20.19或 22.12、OPENAI_API_KEY。OPENAI_MODEL为可选环境变量默认gpt-5.5。# 1. 安装演示环境并导出密钥 ./scripts/demo_setup.sh export OPENAI_API_KEY... # 2. 安装前端依赖并生成 OpenUI 系统提示词 cd cookbook/05_agent_os/16_agui/openui/frontend npm install npm run generate:prompt # 3. 终端一从仓库根目录启动 Agno 服务器 .venvs/demo/bin/python cookbook/05_agent_os/16_agui/openui/server.py # 4. 终端二启动前端 cd cookbook/05_agent_os/16_agui/openui/frontend npm run dev打开http://localhost:5173Vite 会把/agui与/status代理到 7777 端口的 AgentOS。server.py 会在启动时检查frontend/src/generated/system-prompt.txt是否存在缺失即报错提示先执行npm install与npm run generate:prompt。8.2 前端适配细节与可尝试场景frontend/src/agno.ts用一个小型过滤器包装 OpenUI 的agUIAdapter转发 text、tool、error 事件同时抑制运行元数据与 Agno 的空 tool-parent 文本外壳让工具结果在 OpenUI 时间线中与对应的工具调用紧密配对客户端还会发送空的state与forwardedProps对象因为 Agno 的RunAgentInput模型要求这两个 AG-UI 扩展容器。值得尝试的三个场景图表 跟进建议渲染 Q1–Q4 营收图与两个可点击的后续步骤校验表单渲染必填的项目名、团队规模、备注字段空提交触发本地校验填入Aurora-731、7、Prioritize accessibility and charts后以一次结构化轮次回传给 AgnoAgno 工具调用 Python Agent 侧的get_quarterly_revenue工具并把结果渲染为图表。验证前端可用npm run typecheck、npm test、npm run build。注意生成提示词与组件规格属于构建产物修改frontend/src/library.ts后需重新生成。九、快速参考AG-UI 事件类型与接口配置事件类别事件类型触发场景生命周期RUN_STARTED/RUN_FINISHED每次运行的开始与结束构成事件流边界工具调用TOOL_CALL_*后端工具与前端external_execution工具的调用与结果回传推理REASONING_*启用reasoning_model后的推理过程状态STATE_SNAPSHOT/STATE_DELTA共享状态快照与 JSON Patch 增量AGUI接口核心配置速查见 agui.pyagent/team二选一必填其一prefix路由前缀默认控制POST {prefix}/agui与GET {prefix}/statustags路由标签默认[AGUI]。结语AG-UI 把「交互式前端」与「Agent 后端」之间的耦合收敛为一个标准化事件流Agno 负责把 Agent/Team 的运行翻译成 text、tool、reasoning、state 与 lifecycle 事件前端只需按协议消费。从basic.py的最小事件流到agent_with_tools.py与human_in_the_loop.py两种暂停模式的对比再到shared_state.py的状态增量同步、agent_with_media.py的多模态输入、research_team.py的团队流式化与multiple_instances.py的多接口挂载这 9 个独立服务器构成了从「会跑的接口」到「生产级交互前端」的完整进阶路径。若想继续深入可以阅读 AG-UI 接口源码 中的 router.py 与 stream.py 观察事件翻译细节或参照 cookbook/05_agent_os/05_human_in_the_loop/ 掌握后端审批机制的完整实现。【免费下载链接】agnoBuild, run, and manage agent platforms.项目地址: https://gitcode.com/GitHub_Trending/ag/agno创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
