2FastLabs/agent-squad · 上手攻略

仓库：2FastLabs/agent-squad
链接：https://github.com/2FastLabs/agent-squad
分类：ai
作者：Jay
更新：2026-07-14

是什么

Agent Squad 是一个轻量级的多 Agent 编排框架，核心思路是把用户请求通过分类器（Classifier）路由到最合适的专属 Agent，同时维护跨 Agent 的对话上下文。它最早托管于 AWS Labs（awslabs/agent-squad，原名 multi-agent-orchestrator），现由 2FastLabs 维护。

框架有三个运行时：Python（3.11+）、TypeScript（Node.js）和 Swift（iOS 16+ / macOS 14+）。三者功能对齐，可运行在 AWS Lambda、容器、笔记本或苹果设备上。Swift 运行时尤其特别——整个编排逻辑完全跑在设备端，包括实时语音、MCP 工具调用和本地聊天存储。

解决什么问题

当一个 AI 应用需要处理多种类型的请求时，单一 Agent 容易变成"万能但平庸"的解决方案。Agent Squad 的思路是：为每类任务配置专门的 Agent（技术问答 Agent、购物助手 Agent、数学 Agent……），Classifier 根据对话历史和 Agent 描述动态决定谁来响应。它还内置了 SupervisorAgent（团队协调模式）和 GroundedAgent（双 LLM 验证模式，防止幻觉），分别解决"复杂任务需要多个 Agent 协作"和"答案必须精确匹配数据"两类痛点。

快速安装

Python

pip install "agent-squad[aws]"       # AWS Bedrock
# pip install "agent-squad[anthropic]" # Anthropic
# pip install "agent-squad[openai]"    # OpenAI
# pip install "agent-squad[all]"       # 所有 provider

TypeScript

npm install agent-squad

Swift（Xcode → Add Package Dependencies，或在 Package.swift 中添加）

dependencies: [
    .package(url: "https://github.com/2FastLabs/agent-squad", branch: "main")
]

核心用法

Python：创建两个 Agent 并路由请求

import asyncio
from agent_squad.orchestrator import AgentSquad
from agent_squad.agents import BedrockLLMAgent, BedrockLLMAgentOptions, AgentStreamResponse

orchestrator = AgentSquad()

orchestrator.add_agent(BedrockLLMAgent(BedrockLLMAgentOptions(
    name="Tech Agent",
    description="Specializes in technology: software, hardware, AI, cybersecurity, cloud.",
    streaming=True,
)))

# 添加更多 Agent 示例（OpenAI）
# from agent_squad.agents import OpenAIAgent, OpenAIAgentOptions
# orchestrator.add_agent(OpenAIAgent(OpenAIAgentOptions(...)))

async def main():
    response = await orchestrator.route_request(
        "What is AWS Lambda?",
        user_id="user123",
        session_id="session456",
        params={},
        streaming=True
    )

    print(f"> Agent: {response.metadata.agent_name}\n")
    if response.streaming:
        async for chunk in response.output:
            if isinstance(chunk, AgentStreamResponse):
                print(chunk.text, end="", flush=True)
    else:
        print(response.output.content)

asyncio.run(main())

TypeScript：同样场景

import { AgentSquad, BedrockLLMAgent } from "agent-squad";

const orchestrator = new AgentSquad();

orchestrator.addAgent(
  new BedrockLLMAgent({
    name: "Tech Agent",
    description: "Specializes in technology: software, hardware, AI, cybersecurity, cloud.",
    streaming: true
  })
);

const response = await orchestrator.routeRequest(
  "What is AWS Lambda?",
  "user123",
  "session456"
);

console.log(`> Agent: ${response.metadata.agentName}\n`);
if (response.streaming) {
  for await (const chunk of response.output) {
    if (typeof chunk === "string") process.stdout.write(chunk);
  }
} else {
  console.log(response.output);
}

Swift：设备端编排（iOS/macOS）

import AgentSquad

let agent = Agent(
    name: "Shop",
    description: "Shopping assistant",
    model: ChatCompletionsClient(model: "gpt-4o-mini", apiKey: apiKey)
)
let orchestrator = Orchestrator(
    agents: [agent],
    store: try DeviceChatStorage(userId: "u1")
)

for try await event in orchestrator.route(
    .text("wireless headphones under €100?"),
    userId: "u1", sessionId: "s1"
) {
    if case .textDelta(let token) = event { print(token, terminator: "") }
}

SupervisorAgent：多 Agent 协作

SupervisorAgent 以"Agent 即工具"的方式，让一个主 Agent 协调多个子 Agent 并行处理子任务，最终汇成一条回复：

from agent_squad.orchestrator import AgentSquad
from agent_squad.agents import SupervisorAgent, OpenAIAgent, BedrockLLMAgent

orchestrator = AgentSquad()
orchestrator.add_agent(SupervisorAgent(
    name="Research Supervisor",
    description="Coordinates research tasks across multiple specialized agents",
    agents=[
        OpenAIAgent(...),
        BedrockLLMAgent(...),
    ]
))

GroundedAgent：防止幻觉的验证模式

GroundedAgent 用两个 LLM 分离职责：Gatherer 负责调用工具获取原始数据，Presenter 只能基于这些数据回复用户，不能自行发挥：

from agent_squad.agents import GroundedAgent, GroundedAgentOptions

orchestrator.add_agent(GroundedAgent(GroundedAgentOptions(
    name="Price Checker",
    description="Check product prices and availability",
    gatherer_model="anthropic/claude-3-sonnet-20240229",
    presenter_model="anthropic/claude-3-haiku-20240307",
    tools=[...],
    streaming=True,
)))

⚠️ 版本注意：agent_squad 包名在 Python 中是 agent_squad（下划线），导入路径为 from agent_squad.orchestrator import AgentSquad。TypeScript 包名为 agent-squad（横杠），导入为 from "agent-squad"。两者不要混用。

典型适用场景

客服机器人：不同问题类型（退款、售后、技术支持）路由到不同 Agent
多业务线 AI 助手：一个 App 内服务电商、金融、医疗等多个垂直领域
企业知识库问答：技术文档 Agent + 财务 Agent + HR Agent 分工
Apple 设备端应用：iOS App 内置本地 Agent 编排，支持离线使用（MCP 工具、语音）
防止幻觉的场景：价格查询、库存核对、比分播报等需要数据精确匹配的场景

坑与注意

包名不一致：Python 包名是 agent_squad，TypeScript 是 agent-squad。安装和导入时注意区分。
Python 版本要求：仅支持 Python 3.11+，旧版本无法使用。
Provider 分开安装：AWS/Anthropic/OpenAI 需要通过 extras 安装，如 pip install "agent-squad[aws]"，不装对应 extras 会报 ImportError。
SupervisorAgent 的循环风险：如果 Supervisor 自己被注册进 Classifier，可能产生递归调用；设计 Agent 层级时注意避免自指。
Swift 尚属新增：Swift 运行时功能较新，文档不如 Python/TS 完善，部分高级功能（如自定义 Classifier）可能需要参考源码。
Classifier 冷启动：第一次路由时 Classifier 需要消耗一次 LLM 调用，有额外延迟；可预先 warm up。

与同类对比

特性	Agent Squad	LangChain Agents	CrewAI	AutoGen
多 Agent 路由	✅ Classifier 自动路由	✅ 手动定义	✅ Role-based	✅ 对话式
Supervisor/层级协作	✅ SupervisorAgent	需自行组装	✅ Crew 层级	有限
防幻觉（GroundedAgent）	✅ 双 LLM 分离	❌	❌	❌
Swift/Apple 设备端	✅ 完整支持	❌	❌	❌
MCP 工具支持	✅	✅	部分	部分
云原生部署	✅ Lambda 友好	✅	✅	✅
学习曲线	低	高	中	中

Agent Squad 的最大差异化是Classifier 自动路由和GroundedAgent 防幻觉，以及Swift 设备端支持。如果你需要简单的多 Agent 分工且重视答案精确性，它比 LangChain 轻量得多；如果你需要 Apple 平台本地运行，它是目前极少数的选择之一。

一句话推荐

需要轻量多 Agent 路由编排（尤其配合 AWS Bedrock）、或追求防幻觉答案精确性、或要在 iOS/macOS 设备上跑本地 Agent 编排，Agent Squad 是目前最值得评估的开源框架。