Agent Squad

Flexible, lightweight open-source framework for orchestrating multiple AI agents — in the cloud with Python and TypeScript, and now on device with Swift.

Now available in Swift

On-device agent orchestration for iPhone, iPad, and Mac — agents, MCP tools, realtime voice, and tracing, running entirely on device.
See what's included ↓ · Swift README →

Explore the full documentation

New home: previously hosted at awslabs/agent-squad, the project is now maintained at 2fastlabs/agent-squad (and was formerly named multi-agent-orchestrator). Please update bookmarks, clone URLs, and dependencies.

What is Agent Squad?

Agent Squad routes each user query to the most suitable of your specialized agents and maintains conversation context across them. You get pre-built agents, classifiers, and storage for quick deployment, plus small, well-defined seams to plug in your own.

• 🧠 Intelligent intent classification — route queries by context and content.
• 🌊 Streaming and non-streaming agent responses.
• 📚 Context management — coherent conversations across agents and sessions.
• 🔧 Extensible by design — custom agents, classifiers, storage, and retrievers.
• 📦 Pre-built agents — Bedrock, Anthropic, OpenAI, Lex, Lambda, and more.

Three runtimes, one framework

Python and TypeScript maintain feature parity and run anywhere — AWS Lambda, containers, your laptop. The new Swift runtime brings the same orchestration model to Apple platforms and runs entirely on device: classifier routing, tools (native and MCP), realtime voice, tracing, and local-first chat storage.

How it works

1. User input is analyzed by a Classifier.
2. The Classifier uses the agents' descriptions and the conversation history to select the best agent for the turn.
3. The selected Agent processes the input (calling tools as needed).
4. The Orchestrator saves the exchange and returns the response.

Quick start

TypeScript

npm install agent-squad

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);
}

Python

pip install "agent-squad[aws]"   # or [anthropic], [openai], [all] — see the docs

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,
)))

async def main():
    response = await orchestrator.route_request("What is AWS Lambda?", "user123", "session456", {}, 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())

Swift

Add the package to your Package.swift (or via Xcode → Add Package Dependencies):

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

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: "") }
}

Full walkthrough in the Swift README.

SupervisorAgent — team coordination

A lead agent coordinates a team of specialized agents in parallel using an agent-as-tools architecture, maintaining shared context and delivering one coherent response.

• Team coordination with parallel sub-agent queries and smart shared context.
• Dynamic delegation of subtasks to the right team member.
• Works with all agent types — and can itself be registered in the classifier to build hierarchical teams of teams.

Learn more about SupervisorAgent →

GroundedAgent — answers that can't drift from your data

Available in all three runtimes, GroundedAgent is the framework's anti-hallucination pattern: two LLMs instead of one.

• A gatherer calls your tools and sees the raw results — but never speaks to the user.
• An isolated presenter writes the reply from the curated tool output alone: no tools, no tool transcript, no chat history. It cannot invent a price, a rating, or a stock status that wasn't actually fetched.
• A no-tool turn skips the presenter and answers in one pass.

Use it wherever answers must match the data exactly — prices, odds, balances, availability.

Learn more about GroundedAgent →

New: the Swift runtime — on-device orchestration

The orchestration model above, rebuilt for Apple platforms as a protocol-driven Swift 6 package — designed to run the whole loop on device:

• 🧠 Swappable agents — Agent, GroundedAgent, or your own AgentProtocol conformance, routed by an optional LLMClassifier.
• 🧰 Tools from any source — native Swift functions, declarative HTTP tools, or any MCP server, composed behind one seam.
• 🎙️ Realtime voice — natural spoken conversations with interrupt-to-speak, sharing the same grounded gatherer → presenter core.
• 📈 First-class tracing — OSLog during development, OTLP export (Langfuse, LangSmith, Datadog, …) in production.
• 💾 Local-first chat history — JSON-file or SwiftData persistence on device, swappable like everything else.

Start with the Swift README and the Swift docs.

Examples & demos

Watch the demo app route a conversation across six specialized agents (travel, weather, restaurants, math, tech, health) while preserving context through brief follow-ups:

• Streamlit Global Demo — AI Movie Production Studio, AI Travel Planner, and more in one app.
• chat-demo-app — web chat interface with multiple specialized agents (guide).
• ecommerce-support-simulator — AI-powered customer support with human-in-the-loop (guide).
• chat-chainlit-app — chat application built with Chainlit.
• fast-api-streaming — FastAPI with streaming.
• text-2-structured-output — natural language to structured data.
• bedrock-inline-agents · bedrock-prompt-routing — Bedrock samples.

Articles & podcasts

• Multilingual AI chatbot for flight reservations — Amazon Lex as an agent, many languages in a few lines.
• Building an AI-powered e-commerce support system — email ingestion, routing, and human verification.
• Voicing your agents with Amazon Connect, Lex, and Bedrock — an AI customer call center.
• Unlock Bedrock InvokeInlineAgent API's hidden potential — dynamic agent creation at enterprise scale.
• Supercharging Amazon Bedrock Flows — conversation memory and multi-flow orchestration.
• Podcasts: An Orchestrator for Your AI Agents (EN) (Spotify) · L'orchestrateur multi-agents (FR)

Building with an AI assistant

Each runtime ships a skill — a single, assistant-agnostic guide that gives an AI assistant the mental model, real API signatures, task recipes, and gotchas it needs to write correct code with the framework:

These files are not auto-installed — point your assistant at the relevant one. For example:

Read python/SKILL.md before writing any agent-squad Python code.

Works with any assistant (Claude, Cursor, Copilot, …).

Community & contributing

Questions, ideas, or something to show off? Join the discussions: Show & Tell · General · Ideas.

Contributions are welcome. This repository follows an issue-first policy: every pull request must be linked to an issue (Fixes #123 in the PR body, or GitHub's "Link an issue"); a required CI check enforces it. Open an issue to discuss your proposal, then see the Contributing Guide for build and test instructions per runtime.

Star the repository to be notified about new features and releases.

Authors

• Corneliu Croitoru
• Anthony Bernabeu

Contributors

Big shout out to our awesome contributors! Thank you for making this project better!

Support Agent Squad

If Agent Squad has helped you or your organization build AI applications faster, consider sponsoring its development. Your sponsorship funds maintenance, documentation, and new features — keeping the project healthy for the entire community.

License

This project is licensed under the Apache 2.0 license — see the LICENSE file for details.

This project uses the JetBrainsMono NF font, licensed under the SIL Open Font License 1.1.