在终端中对话 Flower Agent：使用 `flwr chat` 在 SuperGrid 上运行 AgentApp 的完整上手指南-育师

在终端中对话 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 flwr==<stable_flwr_version> flwr --version flwr, version <stable_flwr_version>

显式固定版本可以让本教程中的每条命令都运行在同一个 CLI 上。如果该包在你的环境中不可用，请先按照你所使用的 Flower 环境的包安装说明完成安装。后续所有独立 CLI 命令均建议采用uvx --from flwr==<stable_flwr_version>这种写法。

配置 SuperGrid 连接并登录

Flower 在第一次需要时会在用户主目录下创建~/.flwr/config.toml。默认生成的文件中包含以下连接配置：

[superlink.supergrid] address = "api.flower.ai"

如果你维护的是自定义配置文件，请确保存在该[superlink.supergrid]小节。然后执行登录：

$ uvx --from flwr==<stable_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 flwr==<stable_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，附上请求内容后按Enter：

@publisher/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-name，Federation 的完整 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 中。

此外，Ctrl+C在不同状态下有不同的行为：

运行期间：请求停止当前运行
查看历史时：关闭历史列表
有草稿时：清空提示符
空闲提示符下：退出 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 Key；
AgentSession：供连接器调用与前端可见事件使用；
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：使用 `flwr chat` 在 SuperGrid 上运行 AgentApp 的完整上手指南