agency-swarm

环境要求

• Python 环境（用 pip 安装依赖）
• 有效的 OpenAI API Key（OPENAI_API_KEY）
• 已安装 agency-swarm 1.x（基于 OpenAI Agents SDK + Responses API）
• 可访问 OpenAI 网络环境

安装与启动步骤

1. 1安装 agency-swarm

   用 pip 安装或升级到最新版。v1.x 基于 OpenAI Agents SDK 与 Responses API，旧项目需参考迁移指南。

   pip install -U agency-swarm

   复制

2. 2配置 OpenAI 密钥

   创建 .env 文件写入 OPENAI_API_KEY=your_key（会自动加载），或在 shell 中导出环境变量。

   export OPENAI_API_KEY="sk-xxxxxxxx"

   复制

3. 3定义工具

   推荐用 @function_tool 装饰器定义函数工具，函数需带说明性 docstring，供智能体判断何时调用。

   from agency_swarm import function_tool
   
   
   @function_tool
   def my_custom_tool(example_field: str) -> str:
       """A brief description of what the custom tool does."""
       return f"Result: {example_field}"

   复制

4. 4定义智能体角色

   用 Agent 声明各角色，配置 name、description、instructions、tools、model 等；instructions 可指向 md 文件。

   from agency_swarm import Agent, ModelSettings
   
   ceo = Agent(
       name="CEO",
       description="Responsible for client communication, task planning and management.",
       instructions="You must converse with other agents to ensure complete task execution.",
       files_folder="./files",
       schemas_folder="./schemas",
       tools=[my_custom_tool],
       model="gpt-6-luna",
       model_settings=ModelSettings(max_tokens=25000),
   )

   复制

5. 5定义通信流

   用 Agency 组装智能体，第一个参数是面向用户的入口；用 > 定义有方向的通信关系，左侧可主动发起对话。

   from agency_swarm import Agency
   
   from Developer import Developer
   from VirtualAssistant import VirtualAssistant
   
   dev = Developer()
   va = VirtualAssistant()
   
   agency = Agency(
       ceo,
       communication_flows=[
           ceo > dev,
           ceo > va,
           dev > va,
       ],
       shared_instructions="agency_manifesto.md",
   )

   复制

6. 6运行演示

   可选 Web UI（copilot_demo）、终端（tui）或异步程序化调用 get_response；首次运行会自动配置终端应用。

   agency.copilot_demo()

   复制

7. 7程序化异步调用

   异步方式更推荐；也可用 agency.get_response_sync(...) 做同步调用。resp.final_output 为最终输出。

   import asyncio
   
   
   async def main():
       resp = await agency.get_response("Create a project skeleton.")
       print(resp.final_output)
   
   
   asyncio.run(main())

   复制

关键配置

如何确认成功

运行 agency.copilot_demo() 或 agency.tui() 后出现终端应用与简短设置提示；异步调用能打印 resp.final_output 即成功。

常见问题

注意事项

• 智能体之间的通信流是有方向的，> 左侧才能主动发起与右侧的对话。
• 工具推荐用 @function_tool 装饰器编写，也可继承 BaseTool（基于 Pydantic 字段校验）保持兼容。
• v1.x 目标平台是 OpenAI Agents SDK 与 Responses API，旧版接口不保证兼容。
• 官方推荐先克隆 Agency Starter Template 起步，并可用仓库根目录 .cursorrules 配合 AI 编码工具。