在终端中对话 Flower Agent使用flwr chat在 SuperGrid 上运行 AgentApp 的完整上手指南【免费下载链接】flowerFlower: A Friendly Federated AI Framework项目地址: https://gitcode.com/GitHub_Trending/flo/flower本指南基于 Flower 官方 Agent 文档agent/docs/source/tutorials/get-started-with-flower-agent.md完整讲解如何用flwr chat从终端登录 SuperGrid、启动 AgentApp 对话、切换 Agent 与 Federation并结合仓库源码剖析每次对话背后真实的运行时结构。读完本文你将掌握 Flower Agent 终端工作流的每一步操作并理解 Run、Run Series、Federation 与AgentSession之间的协作关系。Flower 的 Agent 能力Flower Agent 与flwr chat目前仍处于实验阶段可能随版本迭代发生变化。本教程针对 Flower 稳定版本编写文档以{{ stable_flwr_version }}占位符指代该版本所有命令通过uvx --from flwr稳定版本号固定到同一版本执行保证命令行为一致。前置条件在开始之前请确认你的环境满足以下要求已安装 uv项目包管理与运行工具Python 3.11 或更高版本一个已开通 Flower Agent 访问权限的 Flower 账户一个能够打开基于浏览器的登录流程的终端登录授权需要在浏览器中完成特别需要注意的是运行 SuperGrid 对话不需要你提供任何模型凭据。模型访问、凭据注入与连接器执行全部由 SuperGrid 运行时负责这与自建模型 API 的常规流程不同。如果你想先用浏览器体验同样的流程可以参考 Chat in your browser 教程。检查 Flower 版本使用uvx在隔离环境中运行文档指定的版本避免污染全局环境$ uvx --from flwrstable_flwr_version flwr --version flwr, version stable_flwr_version显式固定版本可以让本教程中的每条命令都运行在同一个 CLI 上。如果该包在你的环境中不可用请先按照你所使用的 Flower 环境的包安装说明完成安装。后续所有独立 CLI 命令均建议采用uvx --from flwrstable_flwr_version这种写法。配置 SuperGrid 连接并登录Flower 在第一次需要时会在用户主目录下创建~/.flwr/config.toml。默认生成的文件中包含以下连接配置[superlink.supergrid] address api.flower.ai如果你维护的是自定义配置文件请确保存在该[superlink.supergrid]小节。然后执行登录$ uvx --from flwrstable_flwr_version flwr login supergrid命令会打印一个身份认证链接在浏览器中打开并完成登录后CLI 会保存登录得到的账户凭据供后续所有 SuperGrid 命令复用。从源码实现看登录与聊天都围绕supergrid这个连接名展开。在 framework/py/flwr/cli/chat/chat.py 中flwr chat命令会通过read_superlink_connection(CHAT_SUPERGRID_CONNECTION_NAME)读取该连接配置再依据连接的地址加载 CLI 认证插件并初始化 HTTP 控制客户端。如果连接没有配置地址CLI 会直接抛出ValueError(The SuperGrid connection has no address.)——这正是文档要求先确认~/.flwr/config.toml中存在[superlink.supergrid]小节的原因。启动一个聊天会话在终端执行$ uvx --from flwrstable_flwr_version flwr chat如上图所示Flower Chat 会在提示符上方显示当前选中的 Agent。启动时 Flower 会先校验已保存的登录凭据再打开全屏交互界面。默认情况下会选中你的account/personal个人Federation并在❯提示符下等待输入。此时可以输入第一个请求Explain Flower Agent in one sentence.该请求会让当前选中的 AgentApp 启动一次 SuperGrid 运行Run。模型响应、推理摘要以及 Agent 所调用的工具活动都可以实时流式进入对话记录transcript完成的响应会以 Markdown 渲染。当这次运行结束后提示符恢复可用你就可以继续输入下一条消息。从源码角度看flwr chat启动时不只是打开界面还会先调用ListFederations控制接口校验凭据并拉取账户可见的 Federation 列表随后才把控制客户端和该列表交给ChatApplication运行见 framework/py/flwr/cli/chat/chat.py。这解释了为什么登录失效时 CLI 会在打开界面之前就失败。如果全屏界面没有正常打开先参考 Troubleshoot AgentApp runs 排查再考虑修改项目或账户连接配置。继续同一场对话向当前会话发送一个依赖上一条回答的追问Rewrite that explanation for a ten-year-old.Flower 会将这两次运行归入同一个Run Series运行系列即浏览器中呈现的对话。默认的 Flower Agent 会重放该系列中已存储的消息因此它能引用你刚才的回答。需要强调的是run series 本身并不会自动把历史消息交给模型——如果你的自定义 AgentApp 需要对话连续性必须自己在应用代码里实现消息重放逻辑。选择另一个 Agent在空提示符的开头输入会弹出当前活跃 Federation 中可用 Agent 的补全菜单。选择一个 Agent附上请求内容后按Enterpublisher/agent Describe what you can help me with.只有位于开头的 app spec 才会触发 Agent 选择。选择成功后提示符上方的标签会立即变化。切换 Agent 会开启一个新的 run series因此新 Agent 不会混入之前 Agent 的上下文。如果输入后没有出现任何 Agent请确认当前 Federation 以及账户权限是否正确参考 Use agents and federations 检查账户成员身份与 entitlement。另一个值得注意的细节是一个 Agent 在其他 Federation 可用并不意味着它在当前 Federation 的目录中可用Agent 目录是跟随 Federation 隔离的。切换 Federation输入/federation打开 Federation 补全菜单选择你的账户可见的 Federation或者直接输入其完整名称/federation account/federation-name切换 Federation 时Flower 会清空当前对话记录、将 Agent 重置为默认的 Flower Agent并在新 Federation 中开启一段新对话。切换完成后补全菜单列出的将是新 Federation 中被授权的 Agent。如果你希望在非交互式命令中指定 Federation则使用flwr run . supergrid --federation account/federation-nameFederation 的完整 ID含开头的可以通过flwr federation list supergrid查询这一点在 Use agents and federations 中有详细说明。使用聊天命令在提示符输入/即可打开命令菜单Flower Chat 支持以下命令/help列出可用命令/new让下一条消息开启一个新的 run series/federation选择 Federation 并在其中开启新对话/history显示当前活跃 Federation 的历史对话/load从本地项目目录构建并选择一个 AgentApp/quit退出 Flower Chat进入/history后可以使用方向键选择历史对话按Enter继续该对话按Esc关闭列表。Flower 会把该对话的用户消息与助手消息恢复到 transcript 中并将下一条消息发送到所选的那个 run series 中。此外CtrlC在不同状态下有不同的行为运行期间请求停止当前运行查看历史时关闭历史列表有草稿时清空提示符空闲提示符下退出 Flower Chat/load命令值得展开说明详见 Use agents and federations路径相对于你启动flwr chat时的目录解析路径含空格时需要用引号包裹。Flower 会校验项目并本地构建 FAB之后每条消息发送前都会从同一目录重新构建 AgentApp 并提交最新的 FAB因此/load之后对代码的修改会自动生效。如果 FAB 发生了变化消息会开启新的 run series如果构建失败消息不会被提交之前加载的构建仍然保持选中状态。背后发生了什么每次消息都是一次 AgentApp 运行每提交一条消息就启动一次AgentApp run。在这个过程中SuperGrid 为这次运行提供了以下组件原文档What happened一节的完整内容OpenAI 兼容的模型端点运行时在 AgentApp 进程内注入FLWR_RUNTIME_BASE_URL与FLWR_RUNTIME_API_KEY两个环境变量应用通过 OpenAI SDK 即可发起模型请求无需任何外部模型 API KeyAgentSession供连接器调用与前端可见事件使用FlowerContext包含运行配置run config与跨运行持久化的系列状态series state选中的 AgentApp根据 app spec 或 FAB hash 解析Federation运行及其系列存储所在的容器。从源码结构可以进一步印证这些概念在 framework/py/flwr/agentapp/base.py 中AgentSession抽象类公开了三类能力——tools(names)返回模型可用的工具定义、call(tool_call)执行连接器调用、get_trace()获取整个 run series 的事件轨迹另有emit(event)用于发布前端可见的结构化事件。这与 Understand the AgentApp runtime 中描述的agent.responses底层 JSON 模型 API、agent.connectors连接器工具与调用、agent.events事件发布与轨迹查询一一对应。一次运行的完整生命周期在 agentapp-runtime.md 中有清晰的 8 步描述CLI 或浏览器解析 AgentApp 并提交运行 → SuperGrid 校验账户成员、应用配置与所选账户连接器 → 创建 run必要时创建 run series→ 执行器启动隔离的 AgentApp 进程并加载 FAB → 初始化AgentSession与持久化Context→ main 函数发起模型请求并按需调用连接器 → AgentApp 发布客户端应看到的事件 → 关闭阶段 Flower 一次性回写Context并记录 run 的完成/失败/停止状态。理解这条链路有助于在后续编写自己的 AgentApp 时准确把握每段代码在哪个环节生效。如需完整的心智模型mental model请阅读 Use agents and federations——其中定义了 AgentApp、Agent、Run、Run Series、Federation、Connector 六个核心概念并给出了何时开启新 run series的完整行为对照表。延伸阅读至此你已经完成了在终端中与 Flower Agent 的第一次完整对话。下一步可以按需深入Write your first AgentApp用 Flower Hub 模板创建第一个自定义 AgentAppBuild a collaborative research agent编写带受控连接器循环与对话状态的协作式研究 AgentUse connectors了解内置连接器web_search、web_fetch、start_automation与账户连接器Slack、Notion、GitHub、Attio的区别与调用方式Run an AgentApp on SuperGrid掌握flwr run、--run-config、--federation、--stream等非交互式运行参数以及flwr list、flwr log、flwr stop等运行观测命令如果遇到问题可以参考 Troubleshoot AgentApp runs 中的症状清单连接缺失、认证过期、Agent 未列出、连接器不可用、心跳超时、运行中断等逐步排查向社区求助时请保留安全的运行标识符但切勿附带任何凭据或提供方令牌。【免费下载链接】flowerFlower: A Friendly Federated AI Framework项目地址: https://gitcode.com/GitHub_Trending/flo/flower创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考