Related Pages

Related topics: Classifiers, Agents & the Orchestrator Runtime, Storage, Retrievers, Tools & Customization

Overview & High-Level Architecture

What is Agent Squad?

Agent Squad is a flexible framework for orchestrating multiple specialized AI agents and managing complex multi-turn conversations. It intelligently routes user queries to the most appropriate agent while maintaining conversation context across interactions. The framework provides pre-built components for quick deployment while remaining extensible for custom integrations. Source: README.md:107-114

The system is delivered in two parallel SDKs — Python and TypeScript — and is designed to run anywhere from AWS Lambda functions to local development environments or any cloud platform. Source: README.md:90-94

The framework is positioned for applications ranging from simple chatbots to sophisticated, production-grade AI systems. It supports both streaming and non-streaming responses, context management across multiple agents, and pluggable storage backends. Source: README.md:85-94

High-Level Architecture Flow

At the heart of Agent Squad is a four-step request lifecycle:

1. The process begins with user input, which is analyzed by a Classifier.
2. The Classifier leverages both Agents' Characteristics and Agents' Conversation History to select the most appropriate agent for the task.
3. Once an agent is selected, it processes the user input.
4. The orchestrator then saves the conversation, updating the Agents' Conversation History, before delivering the response back to the user. Source: README.md:122-127

flowchart TD
    U[User Input] --> C[Classifier]
    C -->|selects based on characteristics + history| A[Selected Agent]
    A -->|processes request| R[Agent Response]
    R --> S[Storage / Conversation History]
    S -->|informs future routing| C
    R --> U

The framework also introduces a SupervisorAgent that implements an "agent-as-tools" architecture, allowing a lead agent to coordinate a team of specialized agents in parallel. The supervisor delegates subtasks dynamically, maintains context across all team members, and works with all underlying agent types (Bedrock, Anthropic, Lex, etc.). Source: README.md:137-148

Core Components

Agents

Agents are the specialized workers that handle individual domains. The framework ships with several built-in agent types:

• BedrockLLMAgent — invokes Amazon Bedrock-hosted foundation models (e.g., Claude 3 Sonnet, Claude 3 Haiku, Llama 3 70B) and supports tool/function calling. Source: typescript/src/agents/bedrockLLMAgent.ts:1-15
• BedrockInlineAgent — lets the model dynamically create and invoke inline sub-agents, action groups, and knowledge bases at runtime. The agent builds a prompt template enumerating available action groups and knowledge bases for the model to choose from. Source: python/src/agent_squad/agents/bedrock_inline_agent.py:1-30
• SupervisorAgent — orchestrates a team of agents in parallel, exposing them as tools to a lead LLM with explicit communication guidelines (e.g., "Make sure that you optimize your communication by contacting MULTIPLE agents at the same time whenever possible"). Source: python/src/agent_squad/agents/supervisor_agent.py:1-30
• Custom domain agents — examples include a HumanAgent extending the base Agent class to enqueue work via AWS SQS for human-in-the-loop handling. Source: examples/ecommerce-support-simulator/README.md:1-40

Classifiers and Retrievers

Classifiers decide *which* agent should handle an incoming request. Retrievers provide *grounded context* (knowledge bases, vector stores, external APIs) to agents before they generate responses.

The retriever contract is intentionally minimal: subclasses implement retrieveAndGenerate(text) which performs retrieval and then uses the results to generate new information. Source: python/src/agent_squad/retrievers/retriever.py:1-25 The TypeScript SDK mirrors this contract with an abstract retrieveAndGenerate(text: any): Promise<any> method. Source: typescript/src/retrievers/retriever.ts:1-15

Types and Configuration

The shared type system models every conversation element uniformly. Key types include ConversationMessage, ParticipantRole, TimestampedMessage, RequestMetadata, ToolInput, AgentTypes, TemplateVariables, AgentSquadConfig, and AgentProviderType. Predefined model IDs are exposed as constants for Claude 3 Haiku, Claude 3 Sonnet, Claude 3.5 Sonnet, Llama 3 70B, OpenAI GPT-o-mini, and Anthropic Claude 3.5 Sonnet. Source: python/src/agent_squad/types/__init__.py:1-26

Demo Applications and Ecosystem

Agent Squad ships with several reference implementations that illustrate the architecture in practice:

Community-Driven Roadmap Signals

Several highly-discussed feature requests map directly onto architectural extensions:

• MCP Servers & Tools (#299) — A request to integrate the Model Context Protocol so agents can consume standardized external tools. This would slot naturally alongside the existing BedrockInlineAgent tool-execution machinery. Source: python/src/agent_squad/agents/bedrock_inline_agent.py:1-30
• Observability / Langfuse traces (#152) — Production users need trace export of orchestrator and agent calls. The Langfuse demo already proves this pattern works end-to-end. Source: examples/langfuse-demo/readme.md:1-25
• "think" tool for Anthropic/Bedrock (#339) — A request for a dedicated structured-thinking tool, building on the framework's existing tool-use abstractions. Source: typescript/src/agents/bedrockLLMAgent.ts:1-15

The framework's latest release (python_1.0.2) added Strands agents integration and classifier prompt fixes, signaling continued investment in pluggable agent providers. Source: README.md:1-10

See Also

• Getting Started & Installation
• Classifier Implementations
• Agents Overview
• Storage Backends

Related Pages

Related topics: Overview & High-Level Architecture, Storage, Retrievers, Tools & Customization

Classifiers, Agents & the Orchestrator Runtime

Overview & Purpose

Agent Squad is a multi-agent orchestration framework that routes user input to specialized agents while maintaining shared conversation context. The runtime is split into three cooperating subsystems: the Orchestrator (the dispatcher and history store), Classifiers (the routing brains), and Agents (the workers that actually generate answers). Both Python and TypeScript implementations exist, sharing the same conceptual model but with language-specific clients.

The README documents the high-level flow as: user input is analyzed by a Classifier, the Classifier leverages both agent characteristics and conversation history to pick the most appropriate agent, the selected agent processes the input, and the orchestrator saves the conversation before returning the response (README.md).

flowchart LR
    U[User Input] --> O[Orchestrator]
    O --> C[Classifier]
    C -->|selected agent id| O
    O --> A[Selected Agent]
    A --> R[Response]
    O --> H[(Conversation History)]
    A --> H
    R --> U

The Orchestrator Runtime

The orchestrator is the central coordinator. It owns the registered agent set, dispatches requests to the classifier for routing, applies the chosen agent to the current conversation, and persists messages to a shared history that the classifier can re-read on the next turn. The shared history is what enables multi-turn coherence — a brief follow-up like "what about tomorrow?" is resolved by the classifier inspecting the prior turns, not by re-prompting the user.

Configuration is exposed through AgentSquadConfig and RequestMetadata in the Python types module, which carry the session, user, and custom template variables used by agents when they render their prompts (python/src/agent_squad/types/__init__.py). The orchestrator is also the integration point for storage backends and for higher-level coordination patterns such as the SupervisorAgent, which is described in the README as a "agent-as-tools" pattern that lets a lead agent coordinate specialized agents in parallel while preserving context (README.md).

The TypeScript orchestrator in typescript/src/orchestrator.ts mirrors the Python surface, allowing teams to pick the runtime language that matches their deployment target without changing the conceptual agent/classifier contract.

Classifiers

The classifier interface is a small abstract base that every concrete implementation must satisfy. The base class in python/src/agent_squad/classifiers/classifier.py defines the routing contract: given the current input and the registered agents (with their characteristics and recent conversation history), it must return the agent best suited to handle the request.

Three concrete classifiers ship with the framework:

• BedrockClassifier (python/src/agent_squad/classifiers/bedrock_classifier.py) — uses Amazon Bedrock as the routing model, with built-in model-id constants for Claude 3 Haiku, Claude 3 Sonnet, Claude 3.5 Sonnet, and Llama 3 70B exposed via BEDROCK_MODEL_ID_* (python/src/agent_squad/types/__init__.py).
• AnthropicClassifier (python/src/agent_squad/classifiers/anthropic_classifier.py) — calls Anthropic's API directly, with ANTHROPIC_MODEL_ID_CLAUDE_3_5_SONNET as the default constant.
• OpenAIClassifier (python/src/agent_squad/classifiers/openai_classifier.py) — uses OpenAI's models, with OPENAI_MODEL_ID_GPT_O_MINI as the default.

Because all three implement the same interface, you can swap them without touching the agents or the orchestrator wiring.

Agents

Agents do the actual generation. The framework defines a common Agent base with options for streaming vs. non-streaming responses, tool access, and prompt templates, then ships several prebuilt agent types.

BedrockLLMAgent (typescript/src/agents/bedrockLLMAgent.ts) wraps the Bedrock Converse API. It formats user-supplied tools into the Bedrock toolSpec shape (name, description, inputSchema.json.properties/required) and extracts name, toolUseId, and input from each tool-use block returned by the model.

BedrockInlineAgent (typescript/src/agents/bedrockInlineAgent.ts) is a higher-level variant that supports actionGroupsList, attached KnowledgeBase[], an enableTrace flag, and a configurable toolConfig with toolMaxRecursions for bounded tool loops. It defaults the foundation model to Claude 3 Sonnet and the orchestrating model to Claude 3 Haiku.

StrandsAgent (python/src/agent_squad/agents/strands_agent.py) — added in the python_1.0.2 release — bridges Agent Squad to the Strands SDK, accepting a Strands Model, Messages, tool list, system prompt, and optional MCP clients.

Tool execution is surfaced through AgentToolResult and lifecycle hooks (onToolStart, onToolEnd) on AgentToolCallbacks (typescript/src/utils/tool.ts), which is the recommended extension point for observability and for invoking retrievers such as the abstract Retriever.retrieveAndGenerate(text) contract (typescript/src/retrievers/retriever.ts).

Community-Relevant Notes

Three recurring community topics map directly onto the runtime surface described above:

• Observability — Issue #152 requests sending orchestrator and agent traces to frameworks like Langfuse. The Langfuse demo already exercises the tool-callback hook path (examples/langfuse-demo/readme.md), and enableTrace on BedrockInlineAgent provides native Bedrock traces; custom spans can be added through AgentToolCallbacks (typescript/src/utils/tool.ts).
• MCP support — Issue #299 requests Model Context Protocol servers/tools. The Strands agent constructor already accepts an mcp_clients list (python/src/agent_squad/agents/strands_agent.py), indicating that MCP wiring is being introduced at the agent layer.
• "Think" tool — Issue #339 requests Anthropic's structured thinking tool. Since agents own the tool list rendered into toolSpec (typescript/src/agents/bedrockLLMAgent.ts), a custom think tool can already be registered today through the standard AgentTools API.

See Also

• Classifiers & Routing Deep Dive
• Agent Implementations Reference
• SupervisorAgent Coordination
• Observability with Langfuse (Example)

Related Pages

Related topics: Classifiers, Agents & the Orchestrator Runtime, Observability, Deployment, Examples & Community-Tracked Integrations

Storage, Retrievers, Tools & Customization

Overview

Agent Squad is a multi-agent orchestration framework in which individual agents can be enriched with external knowledge via Retrievers, extended with executable capabilities via Tools, and wired into the broader stack with pluggable Storage backends. Although Retriever and Tool are exposed as distinct extension points, they share a common shape: an abstract interface that any concrete integration must implement. This page documents those extension points and shows how they are used to build production-grade agents.

Retrievers

A Retriever augments an agent with retrieval-augmented generation (RAG) capabilities. Both language ports expose it as an abstract base class with three required methods.

// Source: typescript/src/retrievers/retriever.ts:24-71
abstract class Retriever {
  protected options: any;
  abstract retrieve(text: any): Promise<any>;
  abstract retrieveAndCombineResults(text: any): Promise<any>;
  abstract retrieveAndGenerate(text: any): Promise<any>;
}

The Python port mirrors this contract one-for-one (python/src/agent_squad/retrievers/retriever.py). The three methods cover progressively richer behaviors:

In practice, agents such as BedrockLLMAgent and AmazonKnowledgeBasesRetriever (shown in the ecommerce-support-simulator example) use the retrieveAndGenerate flow so that the underlying Bedrock model produces the final answer rather than returning raw context.

Tools

While retrievers provide *knowledge*, Tools provide *action*. Tools are bound to an agent and serialized into the model provider's native tool format.

Tool Serialization

The TypeScript BedrockLLMAgent translates user-facing tool definitions into the Bedrock Converse toolSpec shape:

// Source: typescript/src/agents/bedrockLLMAgent.ts
private formatTools(tools: AgentTools): any[] {
  return tools.tools.map((tool) => ({
    toolSpec: {
      name: tool.name,
      description: tool.description,
      inputSchema: {
        json: { type: "object", properties: tool.properties, required: tool.required }
      }
    }
  }));
}

Each provider adapter then extracts the tool-use fields in its own way. BedrockLLMAgent reads toolUseBlock.name, toolUseBlock.toolUseId, and toolUseBlock.input (typescript/src/agents/bedrockLLMAgent.ts), while AnthropicAgent reads toolUseBlock.id instead of toolUseId and looks at block.type === "tool_use" (typescript/src/agents/anthropicAgent.ts). This means a single tool definition can be reused across providers as long as the per-provider adapter handles its own response block shape.

Tool Callbacks and Observability

AgentToolCallbacks defines lifecycle hooks that fire around every tool invocation: onToolStart, onToolEnd, and onToolError. Each receives the tool name, input, output (where applicable), an optional runId, tags, and arbitrary metadata (typescript/src/utils/tool.ts). The default implementations are no-ops, so subclasses can override only what they need.

These hooks are the recommended integration point for observability frameworks. Community issue #152 explicitly requests support for sending traces to Langfuse and similar systems, and the langfuse-demo example (examples/langfuse-demo/readme.md) demonstrates wiring classification decisions, agent selection, token usage, and response times into Langfuse spans by hooking into these callbacks. A trace also surfaces AgentToolResult (typescript/src/utils/tool.ts), which pairs the toolUseId from the model with the tool's returned content.

Inline Agents and Dynamic Tooling

BedrockInlineAgent (TypeScript and Python) takes tooling one step further by letting the agent itself invoke a special inline_agent_creation tool that spins up a *new* sub-agent on the fly with its own action groups and knowledge bases:

# Source: python/src/agent_squad/agents/bedrock_inline_agent.py
if tool_use_name == "inline_agent_creation":
    action_group_names = tool_use_block["input"].get('action_group_names', [])
    kb_names = tool_use_block["input"].get('knowledge_bases', '')
    description = tool_use_block["input"].get('description', '')
    user_request = tool_use_block["input"].get('user_request', '')

The Python implementation also exposes a default_max_recursions of 20 to bound the inline-agent creation loop (python/src/agent_squad/agents/bedrock_inline_agent.py), while the TypeScript port stores a parallel toolConfig.toolMaxRecursions counter (typescript/src/agents/bedrockInlineAgent.ts). Both representations protect against runaway recursive tool calls.

Customization Patterns

Agent Squad composes these primitives in three common ways:

1. Knowledge-only agents — pair a Retriever (e.g. AmazonKnowledgeBasesRetriever) with a BedrockLLMAgent so the model answers grounded on a knowledge base, as in the chat-demo-app Tech Agent.
2. Action agents — define typed tools (order lookup, shipment tracking, weather API, calculator) and let the model choose which to call, as shown in the ecommerce-support-simulator Order Management Agent.
3. Hybrid agents — combine both, optionally routing complex cases to a HumanAgent or BedrockInlineAgent when deterministic tools are insufficient.

Custom system prompts and template variables are supported uniformly: set_system_prompt(template, variables) is wired through the Python TemplateVariables type re-exported from python/src/agent_squad/types/__init__.py, and the TypeScript bedrockInlineAgent class stores customVariables alongside its systemPrompt for prompt templating (typescript/src/agents/bedrockInlineAgent.ts).

Failure Modes and Community Notes

• Tool-use field drift across providers — BedrockLLMAgent uses toolUseId, while AnthropicAgent uses id. Authors of custom agents must follow the per-provider conventions documented in typescript/src/agents/anthropicAgent.ts.
• Unbounded recursion — without setting default_max_recursions (Python) or toolMaxRecursions (TypeScript), inline-agent tool calls can loop indefinitely (python/src/agent_squad/agents/bedrock_inline_agent.py).
• Observability gaps — issue #152 notes that production users want richer traces than the default text output; until first-class support lands, the langfuse-demo shows how to bridge AgentToolCallbacks to an external tracing backend.
• MCP support — issue #299 requests MCP-server-backed tools; today, the Retriever and Tool abstract classes are the integration seam where an MCP adapter would plug in.
• Anthropic "think" tool — issue #339 proposes adding Anthropic's structured thinking tool; it would slot into the same formatTools pipeline used by BedrockLLMAgent once implemented.

Related Pages

Related topics: Classifiers, Agents & the Orchestrator Runtime, Storage, Retrievers, Tools & Customization

Observability, Deployment, Examples & Community-Tracked Integrations

1. Purpose and Scope

Agent Squad is a flexible framework for orchestrating multiple AI agents while maintaining conversation context across interactions. The framework is implemented in both Python and TypeScript and ships with pre-built agents, classifiers, and retrievers intended to cover a wide range of production scenarios. Source: README.md.

Beyond its core orchestration logic, the project exposes hooks that support observability, supports universal deployment from local machines to AWS Lambda or any other cloud, and is accompanied by a set of worked examples that illustrate real-world integrations. This page documents those peripheral capabilities, the official example applications, and several community-tracked integration requests that the maintainers are considering but have not yet shipped in a stable release.

2. Observability

2.1 Built-in Tracing Flags

Tracing support is opt-in at the agent layer. Both BedrockLLMAgent and BedrockInlineAgent accept an enableTrace option in their configuration objects; when set to true, the underlying Bedrock runtime returns trace metadata alongside the model response. Source: typescript/src/agents/bedrockInlineAgent.ts and python/src/agent_squad/agents/bedrock_inline_agent.py.

2.2 Langfuse Integration Example

The repository ships a dedicated langfuse-demo example that demonstrates end-to-end observability with Langfuse. The example traces the full user conversation, creates spans for each agent interaction, and records metrics such as classification decisions, agent selection confidence, token usage, and response times. Source: examples/langfuse-demo/readme.md.

2.3 Tool Lifecycle Callbacks

The TypeScript toolkit exposes AgentToolCallbacks with onToolStart and onToolEnd hooks. Each callback receives the tool name, input, output, an optional runId, tags, and arbitrary metadata, making it straightforward to wrap tool invocations with a third-party tracer. Source: typescript/src/utils/tool.ts.

2.4 Community Request: First-Class Observability

Issue #152 requests that traces be sent to observability frameworks such as Langfuse natively, with 13 comments confirming strong community interest. As of the current source tree, observability remains an example-level integration rather than a built-in feature of the orchestrator.

3. Deployment Surfaces

The framework advertises universal deployment, meaning the same code can run on AWS Lambda, on a developer's local machine, or on any other cloud provider. Source: README.md. Concrete deployments can be observed in the examples:

Sources: examples/chat-demo-app/README.md, examples/ecommerce-support-simulator/README.md, examples/text-2-structured-output/README.md.

The orchestrator itself is provider-agnostic with respect to LLM backends. Available model identifier constants such as BEDROCK_MODEL_ID_CLAUDE_3_HAIKU, BEDROCK_MODEL_ID_CLAUDE_3_5_SONNET, OPENAI_MODEL_ID_GPT_O_MINI, and ANTHROPIC_MODEL_ID_CLAUDE_3_5_SONNET indicate that agents can be pointed at multiple providers. Source: python/src/agent_squad/types/__init__.py.

4. Worked Examples

The repository contains several end-to-end examples that demonstrate how the orchestrator is composed in practice:

• Chat Demo App — Showcases a multi-agent system with Travel, Weather, Math, Tech, and Health agents handling context switching and follow-up queries. Source: examples/chat-demo-app/README.md.
• E-commerce Support Simulator — Implements Order Management, Product Information, and a custom Human Agent that bridges to AWS SQS for asynchronous human-in-the-loop handling. Source: examples/ecommerce-support-simulator/README.md.
• Text-to-Structured-Output — Converts natural-language product queries into structured JSON search parameters using Claude 3 Sonnet with streaming responses. Source: examples/text-2-structured-output/README.md.
• Langfuse Demo — Adds tracing, span collection, and metric reporting on top of the orchestrator. Source: examples/langfuse-demo/readme.md.

flowchart LR
    U[User Input] --> C[Classifier]
    C --> A1[Agent: Travel]
    C --> A2[Agent: Weather]
    C --> A3[Agent: Math]
    C --> A4[Agent: Tech]
    C --> A5[Agent: Health]
    A1 --> T[Trace/Callback Hooks]
    A2 --> T
    A3 --> T
    A4 --> T
    A5 --> T
    T --> O[Observability Sink<br/>e.g. Langfuse]

5. Community-Tracked Integrations

5.1 MCP Servers and Tools

Issue #299 requests native support for Model Context Protocol (MCP) servers and tools. While the existing BedrockInlineAgent already supports action groups, knowledge bases, and a recursive inline-agent creation tool (inline_agent_creation), MCP-specific transports have not yet been integrated. Source: python/src/agent_squad/agents/bedrock_inline_agent.py.

5.2 Anthropic "Think" Tool

Issue #339 asks for Anthropic's "think" tool capability to be exposed as a built-in tool for both Anthropic and Bedrock backends. This would provide agents with a dedicated space for structured thinking, improving policy compliance and multi-step reasoning. As of the current source tree, no think tool implementation is present.

5.3 Release Notes Insight

The python_1.0.2 release notes highlight Strands agents integration and classifier prompt fixes, indicating the project continues to expand its agent-provider ecosystem. The release notes do not mention MCP or "think" tool support, confirming these remain community-tracked requests. Source: community release notes referenced in README.md.

6. Common Failure Modes

• No built-in trace exporter — Setting enableTrace only enables Bedrock trace payloads; routing them to an external dashboard requires custom integration.
• Example-level observability — The Langfuse demo is illustrative, not a shipped integration; production users must wire their own exporter.
• MCP not yet supported — Attempting to plug in MCP servers requires custom tool wrappers rather than framework-native support.

See Also

• Issue #152 — Observability framework integration
• Issue #299 — MCP Servers and Tools
• Issue #339 — Anthropic "think" tool
• examples/langfuse-demo
• examples/chat-demo-app
• examples/ecommerce-support-simulator

Doramagic Pitfall Log

Found 7 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Configuration risk - Configuration risk requires verification.

1. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.host_targets | https://github.com/2FastLabs/agent-squad

2. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://github.com/2FastLabs/agent-squad

3. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/2FastLabs/agent-squad

4. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | https://github.com/2FastLabs/agent-squad

5. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | https://github.com/2FastLabs/agent-squad

6. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/2FastLabs/agent-squad

7. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: release_recency=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/2FastLabs/agent-squad