FastAgency

将多智能体工作流快速投入生产环境的最高效方式。

---

---

什么是FastAgency？

首先，FastAgency并不是又一个代理式AI框架。如今市面上已有很多此类框架，其中最受欢迎的开源框架是AG2（原名AutoGen）。FastAgency为您提供了一个统一的编程接口，用于在开发和生产环境中部署基于AG2代理框架编写的代理式工作流。只需几行代码，您就可以创建一个与所选智能体交互的Web聊天应用或REST API服务。如果您需要扩展工作负载，FastAgency可以帮助您部署一个完全分布式的系统，利用内部消息代理协调多个数据中心中的多台机器，而无需对本地开发环境进行大量修改。

FastAgency是一个开源框架，旨在加速多智能体AI工作流从原型到生产的过渡。对于使用AG2（原名AutoGen）框架的开发者来说，FastAgency使您能够无缝地将Jupyter Notebook中的原型扩展为功能齐全、可直接投入生产的应用程序。凭借多框架支持、统一的编程接口以及强大的API集成能力，FastAgency简化了部署流程，节省了时间和精力，同时保持了灵活性和高性能。

无论您是在编排复杂的AI智能体，还是将外部API集成到工作流中，FastAgency都提供了将概念快速转化为生产所需的工具，从而缩短开发周期，让您专注于优化多智能体系统。

核心特性

• 跨用户界面的统一编程接口：FastAgency提供了一个通用编程接口，使您只需开发一次核心工作流，即可在各种用户界面中重复使用，而无需重写代码。这包括通过ConsoleUI支持基于控制台的应用程序，以及通过MesopUI支持基于Web的应用程序。无论您需要命令行工具还是完全交互式的Web应用，FastAgency都允许您在不同环境中部署相同的底层工作流，从而节省开发时间并确保一致性。

• 无缝集成外部API：FastAgency的一大亮点是能够轻松地将外部API集成到您的智能体工作流中。只需几行代码，您就可以导入OpenAPI规范，并再添加一行代码将其连接到您的智能体。这极大地简化了用实时数据、外部处理或第三方服务增强AI智能体的过程。例如，您可以轻松集成天气API，为用户提供动态的实时天气信息，以最小的努力让您的应用更具互动性和实用性。

• 用于持续集成的测试器类：FastAgency还提供了一个测试器类，使开发者能够为多智能体工作流编写和执行测试。这一特性对于保持应用程序的可靠性和健壮性至关重要，它允许您自动验证智能体的行为和交互。测试器类设计用于与**持续集成（CI）**流水线无缝集成，帮助您尽早发现并修复错误，确保工作流在扩展到生产环境时仍能正常运行。

• 用于编排的命令行界面（CLI）：FastAgency包含一个功能强大的命令行界面（CLI），用于直接从终端编排和管理多智能体应用程序。CLI使开发者能够快速运行工作流、传递参数并监控智能体之间的交互，而无需完整的GUI。这对于自动化部署以及将工作流集成到更广泛的DevOps管道中尤为有用，使开发者能够在管理AI驱动的应用程序时保持控制力和灵活性。

为什么选择FastAgency？

FastAgency弥合了快速原型开发与生产就绪部署之间的差距，赋能开发者快速高效地将多智能体系统付诸实践。通过集成熟悉的框架如AG2（原名AutoGen），提供强大的API集成能力，并配备稳健的CI测试工具，FastAgency降低了通常与在实际应用中部署AI智能体相关的复杂性和开销。

无论您是在构建交互式控制台工具、开发功能齐全的Web应用，还是编排大规模的多智能体系统，FastAgency都能帮助您更快、更可靠、更灵活地完成部署。

支持的运行时

目前，唯一支持的运行时是 AG2（前身为 AutoGen）。

支持的用户界面

FastAgency 当前支持使用 AG2（前身为 AutoGen）定义的工作流，并提供了适用于不同类型应用的选项：

• 控制台：使用 ConsoleUI 界面进行基于命令行的交互。这非常适合在文本环境中开发和测试工作流。

• Mesop：利用 MesopUI 构建基于 Web 的应用。该界面适合创建具有友好用户界面的 Web 应用程序。

支持的网络适配器

FastAgency 可以使用可链式的网络适配器，从而轻松构建可扩展、生产就绪的架构来部署您的工作流。目前，我们支持以下网络适配器：

• 通过 FastAPI 提供的 REST API：使用 FastAPIAdapter 通过 FastAPI 服务器部署您的工作流。此设置允许您在多个工作进程中运行工作流，并使用高度可扩展且稳定的 ASGI 服务器进行服务。

• 通过 FastStream 使用 NATS.io：利用 NatsAdapter 将 NATS.io MQ 消息代理用于高度可扩展、生产就绪的部署。该接口适用于 VPN 环境中的部署，或者与 FastAPIAdapter 结合使用，以身份验证和安全的方式公开服务工作流。

快速入门

项目设置

我们 强烈建议 使用 Cookiecutter 来设置 FastAgency 项目。它会创建项目文件夹结构、默认工作流，自动安装所有必要的依赖项，并生成一个可用于 Visual Studio Code 开发的 devcontainer。

1. 使用以下命令安装 Cookiecutter：

   pip install cookiecutter
   

2. 运行 cookiecutter 命令：

   cookiecutter https://github.com/ag2ai/cookiecutter-fastagency.git
   

3. 假设您使用了默认值，您应该会看到如下输出：

   [1/4] project_name (My FastAgency App):
   [2/4] project_slug (my_fastagency_app):
   [3/4] Select app_type
       1 - fastapi+mesop
       2 - mesop
       3 - nats+fastapi+mesop
       Choose from [1/2/3] (1): 1
   [4/4] Select python_version
       1 - 3.12
       2 - 3.11
       3 - 3.10
       Choose from [1/2/3] (1):
   [5/5] Select authentication
       1 - none
       2 - google
       Choose from [1/2] (1):
   

4. 要运行基于 LLM 的应用，您需要所使用的 LLM 的 API 密钥。最常用的 LLM 是 OpenAI。要使用它，请创建一个 OpenAI API Key，并使用以下命令将其设置为终端中的环境变量：

   export OPENAI_API_KEY=openai_api_key_here
   

5. 使用以下命令在 Visual Studio Code 中打开生成的项目：

   code my_fastagency_app
   

6. 项目打开后，您将看到以下选项，提示您在 devcontainer 中重新打开该项目：

   

7. 在 devcontainer 中重新打开项目后，您可以通过运行提供的测试来验证设置是否正确，命令如下：

   pytest -s
   

   如果一切设置正确，您应该会看到如下输出：

   =================================== test session starts ===================================
   platform linux -- Python 3.12.7, pytest-8.3.3, pluggy-1.5.0
   rootdir: /workspaces/my_fastagency_app
   configfile: pyproject.toml
   plugins: asyncio-0.24.0, anyio-4.6.2.post1
   asyncio: mode=Mode.STRICT, default_loop_scope=None
   collected 1 item
   
   tests/test_workflow.py .                                                            [100%]
   
   ==================================== 1 passed in 1.02s ====================================
   

---

工作流开发

定义工作流

你需要定义应用程序将使用的工作流。在这里，你可以指定代理之间的交互方式以及它们的具体行为。以下是一个由 Cookiecutter 在 my_fastagency_app/workflow.py 中生成的简单工作流定义示例：

import os
from typing import Any

from autogen import ConversableAgent, LLMConfig
from fastagency import UI
from fastagency.runtimes.ag2 import Workflow

llm_config = LLMConfig(
    model="gpt-4o-mini",
    api_key=os.getenv("OPENAI_API_KEY"),
    temperature=0.8,
)

wf = Workflow()


@wf.register(name="simple_learning", description="学生和教师的学习聊天")  # type: ignore[misc]
def simple_workflow(ui: UI, params: dict[str, Any]) -> str:
    initial_message = ui.text_input(
        sender="Workflow",
        recipient="User",
        prompt="我可以帮助你学习数学。你想探讨哪个主题呢？",
    )

    with llm_config:
      student_agent = ConversableAgent(
          name="Student_Agent",
          system_message="你是一位愿意学习的学生。",
      )
      teacher_agent = ConversableAgent(
          name="Teacher_Agent",
          system_message="你是一位数学老师。",
      )

    response = student_agent.run(
        teacher_agent,
        message=initial_message,
        summary_method="reflection_with_llm",
        max_turns=3,
    )

    return ui.process(response)

这段代码设置了一个学生与教师之间的简单学习聊天场景。它定义了代理及其交互方式，并指定了对话的总结方法。

运行与调试工作流

为了确保我们定义的工作流正常运行，可以使用 MesopUI 在本地进行测试。以下代码位于 my_fastagency_app/local/main_mesop.py 中，用于导入已定义的工作流并设置 MesopUI。

在 Linux 和 macOS 上，你可以通过以下命令在本地运行 Mesop 应用程序：

gunicorn my_fastagency_app.local.main_mesop:app

在 Windows 上，请使用以下命令：

waitress-serve --listen=0.0.0.0:8000 my_fastagency_app.local.main_mesop:app

在浏览器中打开 MesopUI 的 URL http://localhost:8000。现在你可以使用图形用户界面手动启动、运行、测试和调试 AutoGen 工作流。

部署

构建 Docker 镜像

如果你是使用 Cookiecutter 创建的项目，那么构建 Docker 镜像只需运行提供的脚本即可，如下所示：

./scripts/build_docker.sh

运行 Docker 容器

同样地，运行 Docker 容器也只需执行提供的脚本，如下所示：

./scripts/run_docker.sh

部署到 Fly.io

如果你是使用 Cookiecutter 创建的项目，那么内置的脚本可以帮助你将工作流部署到 Fly.io。由于 Fly.io 的应用命名空间是全局的，你选择的应用名称可能已被占用。要检查应用名称是否可用并预留该名称，可以运行以下脚本：

./scripts/register_to_fly_io.sh

一旦预留好应用名称，你可以使用以下脚本来测试是否能够成功部署到 Fly.io：

./scripts/deploy_to_fly_io.sh

不过，这仅用于测试目的。实际部署应使用 GitHub Actions{target="_blank"}，具体说明如下。

Cookiecutter 已经生成了所有必要的文件，以便通过 GitHub Actions 将你的应用部署到 Fly.io。你只需将代码推送到 GitHub 仓库的 main 分支，GitHub Actions 就会自动将你的应用部署到 Fly.io。为此，你需要在 GitHub 仓库中设置以下密钥：

• FLY_API_TOKEN
• OPENAI_API_KEY

有关如何创建这些密钥并将其添加为秘密的详细信息，请参考以下链接：

• 创建 Fly.io API 令牌
• 创建 OpenAI API 密钥
• 将秘密添加到 GitHub 仓库

未来计划

我们正在积极扩展 FastAgency 的功能。除了支持 AG2（原 AutoGen）之外，我们还计划集成对其他框架、其他网络提供商以及其他 UI 框架的支持。

⭐⭐⭐ 保持联系 ⭐⭐⭐

请关注我们的文档和社区更新，及时了解新功能和集成信息，访问我们的 Discord 服务器。FastAgency 不断发展，以支持新的框架、API 和部署策略，确保你在 AI 驱动开发领域始终处于前沿。

最后但同样重要的是，请为我们GitHub 仓库 点个赞，以表达你的支持！

你的支持使我们能够与你保持紧密联系，并激励我们继续开发和改进这个框架。感谢你的支持！

---

贡献者

感谢所有让这个项目变得更优秀的杰出人士！

FastAgency 快速上手指南

FastAgency 是一个开源框架，旨在加速多智能体（Multi-Agent）AI 工作流从原型到生产环境的部署。它专为使用 AG2（原 AutoGen）框架的开发者设计，提供统一的编程接口，支持快速构建控制台应用、Web 聊天应用或可扩展的 REST API 服务。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统: Linux, macOS 或 Windows (推荐在 WSL2 上运行)
• Python 版本: 3.10, 3.11 或 3.12
• 开发工具:
  • Visual Studio Code (推荐，用于 DevContainer 支持)
  • Docker (用于运行 DevContainer)
• API Key: 您需要一个大语言模型（LLM）的 API Key（例如 OpenAI API Key）。

安装步骤

官方强烈建议使用 Cookiecutter 模板来初始化项目，它将自动创建目录结构、默认工作流、依赖配置以及 VS Code 的开发容器环境。

1. 安装 Cookiecutter

pip install cookiecutter

2. 生成项目

运行以下命令启动项目向导：

cookiecutter https://github.com/ag2ai/cookiecutter-fastagency.git

3. 配置项目参数

根据提示输入项目信息（括号内为默认值）：

• project_name: 项目名称 (例如: My FastAgency App)
• project_slug: 项目文件夹名 (例如: my_fastagency_app)
• app_type: 选择应用类型
  • 1: fastapi + mesop (Web API + Web UI，推荐)
  • 2: mesop (仅 Web UI)
  • 3: nats + fastapi + mesop (分布式消息队列架构)
• python_version: 选择 Python 版本 (推荐 3.12)
• authentication: 选择认证方式 (开发阶段可选 none)

4. 设置环境变量

进入项目目录并配置 LLM API Key。以 OpenAI 为例：

cd my_fastagency_app
export OPENAI_API_KEY=your_openai_api_key_here

(Windows PowerShell 用户请使用 $env:OPENAI_API_KEY="your_openai_api_key_here")

5. 启动开发环境

使用 VS Code 打开项目：

code my_fastagency_app

当 VS Code 提示 "Reopen in Container" 时，点击确认。这将自动构建包含所有依赖的 Docker 开发环境。

6. 验证安装

在终端中运行测试以确保环境配置正确：

pytest -s

如果看到 1 passed 且无报错，说明安装成功。

基本使用

FastAgency 的核心优势在于只需少量代码即可将 AG2 工作流转换为可交互的应用。以下是基于模板生成的简单使用示例。

1. 定义工作流 (workflow.py)

在项目根目录下的 workflow.py 文件中，定义您的多智能体逻辑。这是一个简单的回声示例：

from typing import Annotated
from fastagency import UI, Workflow
from ag2 import ConversableAgent

# 定义一个简单的 Agent
agent = ConversableAgent(
    name="EchoAgent",
    system_message="You are a helpful assistant that echoes back what the user says.",
    llm_config={"config_list": [{"model": "gpt-4o-mini", "api_key": "sk-placeholder"}]}, # 实际运行时需配置真实 Key
    human_input_mode="NEVER",
)

# 创建工作流
wf = Workflow()

@wf.register(name="echo_workflow", description="Echo user input")
async def echo_workflow(ui: UI, user_message: str) -> str:
    # 启动对话
    chat_result = await agent.a_initiate_chat(
        agent, # 这里简化为自问自答或与其他 agent 对话
        message=user_message,
        max_turns=1,
    )
    return chat_result.summary

2. 运行应用

方案 A：运行 Web 应用 (Mesop UI + FastAPI)

如果您在初始化时选择了 fastapi+mesop，可以直接运行主入口文件（通常是 main.py 或通过 CLI）：

# 启动 FastAPI 服务器和 Mesop UI
python main.py

启动后，终端会显示访问地址（通常为 http://localhost:8000），在浏览器中打开即可与智能体进行网页对话。

方案 B：运行命令行应用 (Console UI)

如果您只想在终端测试工作流逻辑，可以创建一个简单的脚本 run_console.py：

import asyncio
from fastagency.ui.console import ConsoleUI
from workflow import wf # 导入上面定义的 workflow

async def main():
    ui = ConsoleUI()
    # 运行注册的工作流
    result = await ui.run(wf, name="echo_workflow", user_message="Hello FastAgency!")
    print(f"Result: {result}")

if __name__ == "__main__":
    asyncio.run(main())

运行脚本：

python run_console.py

3. 集成外部 API (可选)

FastAgency 支持通过 OpenAPI 规范快速集成外部服务。只需几行代码即可让智能体调用天气、搜索等第三方 API：

# 示例：加载 OpenAPI 规范并连接到 Agent
from fastagency.helpers import load_openapi_spec

spec = load_openapi_spec("path/to/openapi.json")
# 将 spec 绑定到 agent，使其具备调用能力
# (具体绑定方法参考 AG2 文档中的 Function Calling 部分)

现在您已经完成了 FastAgency 的基础设置，可以开始构建复杂的多智能体生产级应用了。