agent-squad-python

agent-squad Python — assistant guide

Async-first, dependency-optional multi-agent orchestration framework (Python 3.11+). This is a guide and a map — not an API reference. Read exact signatures from the source (python/src/agent_squad/) and the docs site (docs/src/content/docs/); this file tells you what to use, when, and what to watch out for.

When to use what

• One assistant — a single Agent subclass; no orchestrator needed, call process_request directly.
• Several specialists — multiple agents + an AgentSquad orchestrator; the classifier routes each turn to the right agent automatically.
• Answers must not drift from data (prices, balances, live stock) — GroundedAgent: a gatherer LLM calls tools and sees raw results but never speaks to the user; an isolated presenter LLM writes the reply grounded only on curated facts.
• Fixed pipeline — ChainAgent: routes the output of one agent as the input to the next, sequentially.
• Team coordination — SupervisorAgent: a lead BedrockLLMAgent or AnthropicAgent delegates to a team of sub-agents via an internal tool loop, maintaining shared context. Can itself be registered in an AgentSquad.
• External tool servers — MCPToolProvider (requires agent-squad[mcp]) connects any number of MCP servers (stdio or SSE) and makes their tools available to any agent.

How to install

All third-party integrations are optional extras — never forced on users who don't need them.

pip install agent-squad                  # core only (no LLM runtime)
pip install "agent-squad[aws]"           # + boto3 — BedrockLLMAgent, BedrockClassifier, DynamoDbChatStorage, etc.
pip install "agent-squad[anthropic]"     # + anthropic SDK — AnthropicAgent, AnthropicClassifier
pip install "agent-squad[openai]"        # + openai SDK — OpenAIAgent, OpenAIClassifier
pip install "agent-squad[sql]"           # + libsql-client — SqlChatStorage (Turso/libSQL)
pip install "agent-squad[strands-agents]"# + strands-agents — StrandsAgent
pip install "agent-squad[dakera]"        # + dakera — DakeraRetriever
pip install "agent-squad[mcp]"           # + mcp — MCPToolProvider
pip install "agent-squad[all]"           # everything except strands-agents

How a turn works

AgentSquad.route_request is the one entry point worth memorising. It is a coroutine — you must await it.