Flower AgentApp 实战指南基于 OpenAI SDK 构建首个 Flower Agent 应用【免费下载链接】flowerFlower: A Friendly Federated AI Framework项目地址: https://gitcode.com/GitHub_Trending/flo/flower导读本文以 Flower 仓库中现成的 hub/apps/agent 最小 AgentApp 为教学骨架完整讲解如何构建 Flower App BundleFAB、理解其源码结构、在本机登录 SuperGrid 并流式运行一个 AI Agent以及如何通过--run-config覆盖每次运行的输入。读完本文你将掌握 Flower AgentApp 的注册机制、运行时环境变量注入原理与流式事件转发模式能够基于此模板快速定制自己的 Flower Agent。一、什么是 Flower AgentAppFlower 是面向联邦 AI 的友好框架而AgentApp是 Flower 应用家族中的一种新形态它不再围绕ClientApp/ServerApp的模型训练循环展开而是把一个AI Agent 的完整执行逻辑封装为可分发、可运行的应用单元。本文介绍的 hub/apps/agent 是最小可用的参考实现它的核心行为只有三件事通过 OpenAI SDK 将配置项agent.input作为提示词发送给大模型通过 Flower Runtime 把每一个流式响应事件实时转发给前端--stream在终端打印最终拼接出的完整响应文本。最关键的一点是AgentApp 本身不需要任何云厂商的 API 凭据。Flower Runtime 会为每次运行注入 SDK 的 base URL 和任务令牌task token应用的 OpenAI client 只需从环境变量中读取即可。这使得 Agent 可以在联邦基础设施上安全、统一地执行而不用把密钥写死在代码里。二、项目结构与核心文件先看目录布局hub/apps/agent/ ├── agent/ │ ├── __init__.py # 包标识仅含 docstring │ └── agent_app.py # AgentApp 核心实现 ├── LICENSE ├── README.md # 本文对应的官方说明 └── pyproject.toml # 项目元数据 Flower 应用配置其中两个文件决定了应用行为agent/agent_app.pyAgent 主逻辑定义了app与main入口pyproject.toml声明依赖、FAB 打包规则以及agent.input的默认值和组件入口路径。三、构建 Flower App BundleFABFlower 应用需要先被构建成可分发、可运行的Flower App BundleFAB。按 README 中的标准流程uv sync uv run flwr builduv sync根据 pyproject.toml 解析并安装依赖该应用要求python 3.11,4.0依赖flwr1.35.0,2.0与openai2.16.0,3.0.0uv run flwr build读取[tool.flwr.app]段中的fab-format-version 1、fab-include [agent/**/*.py, LICENSE]等配置把源码与元数据打包成 FAB。构建产物随后会被flwr run使用或在运行时由 SuperGrid 按 FAB 内容安装见第六节运行时流程。四、逐行解读 AgentApp 核心实现4.1 注册入口AgentApp()app.main()agent_app.py 的第一段代码是from flwr.agentapp import AgentApp, AgentSession from flwr.app import Context from openai import OpenAI MODEL openai/gpt-5.6-sol app AgentApp() app.main() def main(agent: AgentSession, context: Context) - None: ...AgentApp的底层实现在 framework/py/flwr/agentapp/agent_app.pyAgentApp内部维护一个_main回调main()方法返回装饰器把被装饰函数注册为唯一入口如果重复注册会抛出ValueError调用时若尚未注册则会抛出AgentApp has no main function错误。入口函数的签名是固定的(agent: AgentSession, context: Context) - NoneagentAgentSession是运行时能力句柄见 4.4 与第五节contextContext携带运行配置本示例用它读取提示词。4.2 读取并校验输入prompt context.run_config.get(agent.input) if not isinstance(prompt, str) or not prompt.strip(): raise ValueError(agent.input must be a non-empty string)agent.input是应用默认输入键。它的默认值定义在 pyproject.toml 的[tool.flwr.app.config.agent]段[tool.flwr.app.config.agent] input Explain why flowers turn toward light.即默认提示词为 Explain why flowers turn toward light.解释花朵为何向光生长。运行时会把项目配置与运行覆盖配置融合后注入context.run_config见第六节因此agent.input既可以是默认值也可以被--run-config临时覆盖。源码在读取后还做了严格的类型与空值校验非字符串或空白字符串都会直接抛错终止运行。4.3 凭据来自 Runtime而非云厂商client OpenAI( base_urlos.environ[FLWR_RUNTIME_BASE_URL], api_keyos.environ[FLWR_RUNTIME_API_KEY], max_retries0, )这是整个应用零凭据设计的关键。运行时进程会通过_set_runtime_environment注入两个环境变量实现在 framework/py/flwr/supercore/task_process/agent/run_agentapp.pyFLWR_RUNTIME_BASE_URL值为{scheme}://{runtime_api_address}/v1/runtimescheme依据是否启用 TLS 自动选择http/https即一个 OpenAI Responses API 兼容的 Runtime 端点FLWR_RUNTIME_API_KEY值为本次任务的 token。同时max_retries0表明该应用选择把重试策略交给上层联邦基础设施而非在应用内自行重试。4.4 流式调用与事件转发stream client.responses.create( modelMODEL, inputprompt.strip(), streamTrue, ) output_text [] for event in stream: agent.events.emit(event.to_dict()) if event.type in {error, response.failed}: raise RuntimeError(fModel response failed: {event}) if event.type response.output_text.delta: output_text.append(event.delta) print(.join(output_text))执行逻辑非常清晰以streamTrue发起 OpenAI Responses API 流式请求模型为源码中定义的openai/gpt-5.6-sol遍历每一个流式事件调用agent.events.emit(...)将其结构化转发——这正是--stream模式下前端能实时看到 token 的原因遇到error或response.failed事件立即抛出RuntimeError终止累积response.output_text.delta增量片段结束后一次性print出完整文本。AgentEvents.emit是AgentSession暴露的运行时能力之一其抽象定义见 framework/py/flwr/agentapp/base.pyAgentSession还提供connectors内置连接器的工具模式与执行 API与grid面向模型的联邦 Grid 访问等能力本示例只使用了其中的events。五、登录 SuperGrid 并运行构建完成后按 README 给出的方式在 SuperGrid 上运行uv run flwr login supergrid uv run flwr run . supergrid --streamflwr login supergrid完成对 SuperGrid 的身份认证登录令牌之后会被用于运行时凭据注入flwr run . supergrid --stream把当前目录即刚构建的应用提交到 SuperGrid 执行--stream使前端能够实时接收 4.4 节中转发的流式事件。5.1 为单次运行覆盖输入如果不想改代码或改默认配置可以用--run-config覆盖本次运行的agent.inputuv run flwr run . supergrid \ --run-config agent.inputExplain agent harness in one paragraph. \ --stream运行时的get_fused_config_from_dir会把项目配置与override_config融合见 run_agentapp.py因此覆盖值会直接替换默认提示词而源码中的类型校验必须为非空字符串依然生效。六、运行时原理AgentApp 在 SuperGrid 中的生命周期从源码结构看AgentApp 在运行时进程中经历了一条完整的任务流水线核心实现在 framework/py/flwr/supercore/task_process/agent/run_agentapp.py初始化与心跳进程启动后建立HttpGrid连接、启动心跳发送器并向 Runtime 拉取任务输入PullTaskInput取得运行上下文、运行信息与 FAB 内容安装应用安装 FAB、解析其元数据并按需在隔离环境中安装应用依赖install_app_dependencies融合配置读取项目配置用get_fused_config_from_dir融合运行覆盖配置生成context.run_config并校验agent.input必须是字符串注入环境变量调用_set_runtime_environment设置FLWR_RUNTIME_BASE_URL、FLWR_RUNTIME_API_KEY以及可选的SSL_CERT_FILE加载并调用通过load_app按[tool.flwr.app.components].agentapp agent.agent_app:app加载 AgentApp 实例构造包含connectors/events/grid的RuntimeAgentSession最后执行agent_app(agentagent, contextcontext)收尾上报正常或异常退出时关闭事件发布器、推送任务输出PushTaskOutput并以相应的ExitCode结束进程。这一生命周期印证了 README 的核心论断SDK base URL 与任务令牌全部由 Flower Runtime 供应AgentApp 本身无需携带任何 provider 凭据并且agent.input的默认值、覆盖值和校验逻辑贯穿了配置融合与代码执行两个层面。七、基于本模板的定制方向按 README 的建议定制从修改agent/agent_app.py开始。结合上一节的运行时能力常见的扩展方向包括更换模型或提示词修改MODEL常量或通过--run-config灵活调整agent.input接入更多运行时能力在main中使用agent.connectors注册工具模式并执行工具调用或通过agent.grid让模型与联邦 Grid 交互对应抽象见 framework/py/flwr/agentapp/base.py丰富事件流在agent.events.emit中附带自定义结构化事件配合--stream在前端呈现更完整的运行过程调整打包与发布信息在 pyproject.toml 的[tool.flwr.app]段修改 publisher、版本、打包包含文件或新增配置项后重新flwr build。这个最小示例是理解 Flower Agent 应用形态的最佳起点它足够短小却完整覆盖了配置 → 构建 → 运行 → 流式输出 → 运行时凭据注入的全链路可作为后续复杂 Agent 开发的骨架。【免费下载链接】flowerFlower: A Friendly Federated AI Framework项目地址: https://gitcode.com/GitHub_Trending/flo/flower创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考