# awslabs/agent-squad architecture

> Architecture diagram of the GitHub repository awslabs/agent-squad, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/awslabs/agent-squad
- Repository: https://github.com/awslabs/agent-squad

## Overview

Agent Squad is a multi-runtime framework for routing user queries to specialized AI agents while preserving conversation context. Its main workflow is query → intent classification → selected agent response → saved exchange. Python and TypeScript provide cloud-oriented agent and storage choices; Swift adds on-device orchestration, realtime voice, MCP tooling, and tracing. The README documents the shared workflow and major capabilities; source excerpts are incomplete, so links for unsampled subsystems are included only where documentation supports them.

Main entry points: [`swift/Sources/AgentSquad/Orchestrator.swift`](https://github.com/awslabs/agent-squad/blob/main/swift/Sources/AgentSquad/Orchestrator.swift) (Swift orchestrator), [`python/src/agent_squad/orchestrator.py`](https://github.com/awslabs/agent-squad/blob/main/python/src/agent_squad/orchestrator.py) (Python orchestrator), [`typescript/src/orchestrator.ts`](https://github.com/awslabs/agent-squad/blob/main/typescript/src/orchestrator.ts) (TypeScript orchestrator), [`typescript/src/agents`](https://github.com/awslabs/agent-squad/tree/main/typescript/src/agents) (TypeScript agents)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Request orchestration"]
  node_py_orchestrator["Python orchestrator<br/>[orchestrator.py]"]
  node_ts_orchestrator["TypeScript orchestrator<br/>[orchestrator.ts]"]
  node_swift_orchestrator["Swift orchestrator<br/>[Orchestrator.swift]"]
end

subgraph group_routing["Intent routing"]
  node_py_classifier["Python classifiers"]
  node_ts_classifier["TypeScript classifiers"]
  node_swift_classifier["Swift classifier"]
  node_overlap["Agent overlap analyzer"]
end

subgraph group_agents["Agent execution"]
  node_py_agents["Python agents"]
  node_ts_agents["TypeScript agents"]
  node_swift_agents["Swift agents"]
  node_swift_llm["Chat completions client"]
  node_retrievers["Retrievers<br/>[retriever.ts]"]
end

subgraph group_context["Context and tools"]
  node_py_storage["Python chat storage<br/>[chat_storage.py]"]
  node_ts_storage["TypeScript chat storage<br/>[chatStorage.ts]"]
  node_swift_storage["Swift chat storage<br/>[ChatStorage.swift]"]
  node_swift_device_store[("Device chat storage")]
  node_ts_tooling["Tool utilities<br/>[tool.ts]"]
  node_logger["Logger<br/>[logger.ts]"]
  node_user_agent["AWS user-agent helper<br/>[user_agent.py]"]
end

subgraph group_swift["Swift runtime extensions"]
  node_swift_mcp["MCP tool provider"]
  node_swift_realtime["Realtime voice"]
  node_swift_tracing["Tracing<br/>[Tracing.swift]"]
  node_swift_audio["Audio I/O"]
end

node_user(("User"))

node_user -->|"submits query"| node_py_orchestrator
node_user -->|"submits query"| node_ts_orchestrator
node_user -->|"submits query"| node_swift_orchestrator
node_py_orchestrator -->|"routes through"| node_py_classifier
node_ts_orchestrator -->|"routes through"| node_ts_classifier
node_swift_orchestrator -->|"routes through"| node_swift_classifier
node_py_classifier -->|"selects agent"| node_py_agents
node_ts_classifier -->|"selects agent"| node_ts_agents
node_swift_classifier -->|"selects agent"| node_swift_agents
node_py_orchestrator -->|"dispatches query"| node_py_agents
node_ts_orchestrator -->|"dispatches query"| node_ts_agents
node_swift_orchestrator -->|"dispatches query"| node_swift_agents
node_py_orchestrator -->|"saves exchange"| node_py_storage
node_ts_orchestrator -->|"saves exchange"| node_ts_storage
node_swift_orchestrator -->|"saves exchange"| node_swift_storage
node_py_orchestrator -->|"loads history"| node_py_storage
node_ts_orchestrator -->|"loads history"| node_ts_storage
node_swift_orchestrator -->|"loads history"| node_swift_storage
node_swift_orchestrator -->|"uses store"| node_swift_device_store
node_swift_agents -.->|"uses model client"| node_swift_llm
node_ts_agents -->|"retrieves context"| node_retrievers
node_ts_agents -->|"uses tools"| node_ts_tooling
node_swift_agents -.->|"uses MCP tools"| node_swift_mcp
node_swift_orchestrator -.->|"supports voice runtime"| node_swift_realtime
node_swift_realtime -.->|"processes audio"| node_swift_audio
node_swift_orchestrator -.->|"emits traces"| node_swift_tracing
node_py_agents -->|"configures AWS client"| node_user_agent

click node_py_orchestrator "https://github.com/awslabs/agent-squad/blob/main/python/src/agent_squad/orchestrator.py"
click node_ts_orchestrator "https://github.com/awslabs/agent-squad/blob/main/typescript/src/orchestrator.ts"
click node_swift_orchestrator "https://github.com/awslabs/agent-squad/blob/main/swift/Sources/AgentSquad/Orchestrator.swift"
click node_py_classifier "https://github.com/awslabs/agent-squad/tree/main/python/src/agent_squad/classifiers"
click node_ts_classifier "https://github.com/awslabs/agent-squad/tree/main/typescript/src/classifiers"
click node_swift_classifier "https://github.com/awslabs/agent-squad/tree/main/swift/Sources/AgentSquad/Core/Classifier"
click node_py_agents "https://github.com/awslabs/agent-squad/tree/main/python/src/agent_squad/agents"
click node_ts_agents "https://github.com/awslabs/agent-squad/tree/main/typescript/src/agents"
click node_swift_agents "https://github.com/awslabs/agent-squad/tree/main/swift/Sources/AgentSquad/Agents"
click node_swift_llm "https://github.com/awslabs/agent-squad/blob/main/swift/Sources/AgentSquad/Core/LLM/ChatCompletionsClient.swift"
click node_retrievers "https://github.com/awslabs/agent-squad/blob/main/typescript/src/retrievers/retriever.ts"
click node_py_storage "https://github.com/awslabs/agent-squad/blob/main/python/src/agent_squad/storage/chat_storage.py"
click node_ts_storage "https://github.com/awslabs/agent-squad/blob/main/typescript/src/storage/chatStorage.ts"
click node_swift_storage "https://github.com/awslabs/agent-squad/blob/main/swift/Sources/AgentSquad/Core/Storage/ChatStorage.swift"
click node_swift_device_store "https://github.com/awslabs/agent-squad/blob/main/swift/Sources/AgentSquad/Storage/DeviceChatStorage.swift"
click node_ts_tooling "https://github.com/awslabs/agent-squad/blob/main/typescript/src/utils/tool.ts"
click node_swift_mcp "https://github.com/awslabs/agent-squad/blob/main/swift/Sources/AgentSquadMCP/MCPToolProvider.swift"
click node_swift_realtime "https://github.com/awslabs/agent-squad/blob/main/swift/Sources/AgentSquad/Runtimes/Realtime/RealtimeRuntime.swift"
click node_swift_tracing "https://github.com/awslabs/agent-squad/blob/main/swift/Sources/AgentSquad/Core/Tracing/Tracing.swift"
click node_swift_audio "https://github.com/awslabs/agent-squad/blob/main/swift/Sources/AgentSquadAudio/VoiceProcessedAudioIO.swift"
click node_overlap "https://github.com/awslabs/agent-squad/blob/main/typescript/src/agentOverlapAnalyzer.ts"
click node_logger "https://github.com/awslabs/agent-squad/blob/main/typescript/src/utils/logger.ts"
click node_user_agent "https://github.com/awslabs/agent-squad/blob/main/python/src/agent_squad/shared/user_agent.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_py_orchestrator,node_ts_orchestrator,node_swift_orchestrator,node_user toneBlue
class node_py_classifier,node_ts_classifier,node_swift_classifier,node_overlap toneAmber
class node_py_agents,node_ts_agents,node_swift_agents,node_swift_llm,node_retrievers toneMint
class node_py_storage,node_ts_storage,node_swift_storage,node_swift_device_store,node_ts_tooling,node_logger,node_user_agent toneRose
class node_swift_mcp,node_swift_realtime,node_swift_tracing,node_swift_audio toneIndigo
```

## Components

### Request orchestration

- [Python orchestrator](https://github.com/awslabs/agent-squad/blob/main/python/src/agent_squad/orchestrator.py): `python/src/agent_squad/orchestrator.py`
- [TypeScript orchestrator](https://github.com/awslabs/agent-squad/blob/main/typescript/src/orchestrator.ts): `typescript/src/orchestrator.ts`
- [Swift orchestrator](https://github.com/awslabs/agent-squad/blob/main/swift/Sources/AgentSquad/Orchestrator.swift): `swift/Sources/AgentSquad/Orchestrator.swift`

### Intent routing

- [Python classifiers](https://github.com/awslabs/agent-squad/tree/main/python/src/agent_squad/classifiers): `python/src/agent_squad/classifiers`
- [TypeScript classifiers](https://github.com/awslabs/agent-squad/tree/main/typescript/src/classifiers): `typescript/src/classifiers`
- [Swift classifier](https://github.com/awslabs/agent-squad/tree/main/swift/Sources/AgentSquad/Core/Classifier): `swift/Sources/AgentSquad/Core/Classifier`
- [Agent overlap analyzer](https://github.com/awslabs/agent-squad/blob/main/typescript/src/agentOverlapAnalyzer.ts): `typescript/src/agentOverlapAnalyzer.ts`

### Agent execution

- [Python agents](https://github.com/awslabs/agent-squad/tree/main/python/src/agent_squad/agents): `python/src/agent_squad/agents`
- [TypeScript agents](https://github.com/awslabs/agent-squad/tree/main/typescript/src/agents): `typescript/src/agents`
- [Swift agents](https://github.com/awslabs/agent-squad/tree/main/swift/Sources/AgentSquad/Agents): `swift/Sources/AgentSquad/Agents`
- [Chat completions client](https://github.com/awslabs/agent-squad/blob/main/swift/Sources/AgentSquad/Core/LLM/ChatCompletionsClient.swift): `swift/Sources/AgentSquad/Core/LLM/ChatCompletionsClient.swift`
- [Retrievers](https://github.com/awslabs/agent-squad/blob/main/typescript/src/retrievers/retriever.ts): `typescript/src/retrievers/retriever.ts`

### Context and tools

- [Python chat storage](https://github.com/awslabs/agent-squad/blob/main/python/src/agent_squad/storage/chat_storage.py): `python/src/agent_squad/storage/chat_storage.py`
- [TypeScript chat storage](https://github.com/awslabs/agent-squad/blob/main/typescript/src/storage/chatStorage.ts): `typescript/src/storage/chatStorage.ts`
- [Swift chat storage](https://github.com/awslabs/agent-squad/blob/main/swift/Sources/AgentSquad/Core/Storage/ChatStorage.swift): `swift/Sources/AgentSquad/Core/Storage/ChatStorage.swift`
- [Device chat storage](https://github.com/awslabs/agent-squad/blob/main/swift/Sources/AgentSquad/Storage/DeviceChatStorage.swift): `swift/Sources/AgentSquad/Storage/DeviceChatStorage.swift`
- [Tool utilities](https://github.com/awslabs/agent-squad/blob/main/typescript/src/utils/tool.ts): `typescript/src/utils/tool.ts`
- [Logger](https://github.com/awslabs/agent-squad/blob/main/typescript/src/utils/logger.ts): `typescript/src/utils/logger.ts`
- [AWS user-agent helper](https://github.com/awslabs/agent-squad/blob/main/python/src/agent_squad/shared/user_agent.py): `python/src/agent_squad/shared/user_agent.py`

### Swift runtime extensions

- [MCP tool provider](https://github.com/awslabs/agent-squad/blob/main/swift/Sources/AgentSquadMCP/MCPToolProvider.swift): `swift/Sources/AgentSquadMCP/MCPToolProvider.swift`
- [Realtime voice](https://github.com/awslabs/agent-squad/blob/main/swift/Sources/AgentSquad/Runtimes/Realtime/RealtimeRuntime.swift): `swift/Sources/AgentSquad/Runtimes/Realtime/RealtimeRuntime.swift`
- [Tracing](https://github.com/awslabs/agent-squad/blob/main/swift/Sources/AgentSquad/Core/Tracing/Tracing.swift): `swift/Sources/AgentSquad/Core/Tracing/Tracing.swift`
- [Audio I/O](https://github.com/awslabs/agent-squad/blob/main/swift/Sources/AgentSquadAudio/VoiceProcessedAudioIO.swift): `swift/Sources/AgentSquadAudio/VoiceProcessedAudioIO.swift`

### Other components

- **User**

## Connections

- User → Python orchestrator: submits query (evidence: `README.md`)
- User → TypeScript orchestrator: submits query (evidence: `README.md`)
- User → Swift orchestrator: submits query (evidence: `README.md`)
- Python orchestrator → Python classifiers: routes through (evidence: `python/src/agent_squad/orchestrator.py`)
- TypeScript orchestrator → TypeScript classifiers: routes through (evidence: `typescript/src/orchestrator.ts`)
- Swift orchestrator → Swift classifier: routes through (evidence: `README.md`)
- Python classifiers → Python agents: selects agent (evidence: `README.md`)
- TypeScript classifiers → TypeScript agents: selects agent (evidence: `README.md`)
- Swift classifier → Swift agents: selects agent (evidence: `README.md`)
- Python orchestrator → Python agents: dispatches query (evidence: `python/src/agent_squad/orchestrator.py`)
- TypeScript orchestrator → TypeScript agents: dispatches query (evidence: `typescript/src/orchestrator.ts`)
- Swift orchestrator → Swift agents: dispatches query (evidence: `README.md`)
- Python orchestrator → Python chat storage: saves exchange (evidence: `python/src/agent_squad/orchestrator.py`)
- TypeScript orchestrator → TypeScript chat storage: saves exchange (evidence: `typescript/src/orchestrator.ts`)
- Swift orchestrator → Swift chat storage: saves exchange (evidence: `README.md`)
- Python orchestrator → Python chat storage: loads history (evidence: `python/src/agent_squad/orchestrator.py`)
- TypeScript orchestrator → TypeScript chat storage: loads history (evidence: `typescript/src/orchestrator.ts`)
- Swift orchestrator → Swift chat storage: loads history (evidence: `swift/Sources/AgentSquad/Core/Storage/ChatStorage.swift`)
- Swift orchestrator → Device chat storage: uses store (evidence: `README.md`)
- Swift agents → Chat completions client: uses model client
- TypeScript agents → Retrievers: retrieves context (evidence: `typescript/src/agents/bedrockLLMAgent.ts`)
- TypeScript agents → Tool utilities: uses tools (evidence: `typescript/src/agents/bedrockLLMAgent.ts`)
- Swift agents → MCP tool provider: uses MCP tools
- Swift orchestrator → Realtime voice: supports voice runtime
- Realtime voice → Audio I/O: processes audio
- Swift orchestrator → Tracing: emits traces
- Python agents → AWS user-agent helper: configures AWS client (evidence: `python/src/agent_squad/agents/bedrock_llm_agent.py`)
