How awslabs/agent-squad works
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: Orchestrator.swift Swift orchestrator · orchestrator.py Python orchestrator · orchestrator.ts TypeScript orchestrator · agents TypeScript agents
Components 24
Request orchestration
- Python orchestrator
python/src/agent_squad/orchestrator.py - TypeScript orchestrator
typescript/src/orchestrator.ts - Swift orchestrator
swift/Sources/AgentSquad/Orchestrator.swift
Intent routing
- Python classifiers
python/src/agent_squad/classifiers - TypeScript classifiers
typescript/src/classifiers - Swift classifier
swift/Sources/AgentSquad/Core/Classifier - Agent overlap analyzer
typescript/src/agentOverlapAnalyzer.ts
Agent execution
- Python agents
python/src/agent_squad/agents - TypeScript agents
typescript/src/agents - Swift agents
swift/Sources/AgentSquad/Agents - Chat completions client
swift/Sources/AgentSquad/Core/LLM/ChatCompletionsClient.swift - Retrievers
typescript/src/retrievers/retriever.ts
Context and tools
- Python chat storage
python/src/agent_squad/storage/chat_storage.py - TypeScript chat storage
typescript/src/storage/chatStorage.ts - Swift chat storage
swift/Sources/AgentSquad/Core/Storage/ChatStorage.swift - Device chat storage
swift/Sources/AgentSquad/Storage/DeviceChatStorage.swift - Tool utilities
typescript/src/utils/tool.ts - Logger
typescript/src/utils/logger.ts - AWS user-agent helper
python/src/agent_squad/shared/user_agent.py
Swift runtime extensions
- MCP tool provider
swift/Sources/AgentSquadMCP/MCPToolProvider.swift - Realtime voice
swift/Sources/AgentSquad/Runtimes/Realtime/RealtimeRuntime.swift - Tracing
swift/Sources/AgentSquad/Core/Tracing/Tracing.swift - Audio I/O
swift/Sources/AgentSquadAudio/VoiceProcessedAudioIO.swift
Other components
- User
Connections 27
- User → Python orchestrator: submits query
README.md - User → TypeScript orchestrator: submits query
README.md - User → Swift orchestrator: submits query
README.md - Python orchestrator → Python classifiers: routes through
python/src/agent_squad/orchestrator.py - TypeScript orchestrator → TypeScript classifiers: routes through
typescript/src/orchestrator.ts - Swift orchestrator → Swift classifier: routes through
README.md - Python classifiers → Python agents: selects agent
README.md - TypeScript classifiers → TypeScript agents: selects agent
README.md - Swift classifier → Swift agents: selects agent
README.md - Python orchestrator → Python agents: dispatches query
python/src/agent_squad/orchestrator.py - TypeScript orchestrator → TypeScript agents: dispatches query
typescript/src/orchestrator.ts - Swift orchestrator → Swift agents: dispatches query
README.md - Python orchestrator → Python chat storage: saves exchange
python/src/agent_squad/orchestrator.py - TypeScript orchestrator → TypeScript chat storage: saves exchange
typescript/src/orchestrator.ts - Swift orchestrator → Swift chat storage: saves exchange
README.md - Python orchestrator → Python chat storage: loads history
python/src/agent_squad/orchestrator.py - TypeScript orchestrator → TypeScript chat storage: loads history
typescript/src/orchestrator.ts - Swift orchestrator → Swift chat storage: loads history
swift/Sources/AgentSquad/Core/Storage/ChatStorage.swift - Swift orchestrator → Device chat storage: uses store
README.md - Swift agents → Chat completions client: uses model client
- TypeScript agents → Retrievers: retrieves context
typescript/src/agents/bedrockLLMAgent.ts - TypeScript agents → Tool utilities: uses tools
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
python/src/agent_squad/agents/bedrock_llm_agent.py