# https://github.com/2FastLabs/agent-squad Project Manual
Generated at: 2026-06-21 13:12:32 UTC
## Table of Contents
- [Overview & High-Level Architecture](#page-overview)
- [Classifiers, Agents & the Orchestrator Runtime](#page-core-components)
- [Storage, Retrievers, Tools & Customization](#page-storage-retrievers)
- [Observability, Deployment, Examples & Community-Tracked Integrations](#page-observability-deployment)
## Overview & High-Level Architecture
### Related Pages
Related topics: [Classifiers, Agents & the Orchestrator Runtime](#page-core-components), [Storage, Retrievers, Tools & Customization](#page-storage-retrievers)
Related Source Files
The following source files were used to generate this page:
- [README.md](https://github.com/2FastLabs/agent-squad/blob/main/README.md)
- [examples/text-2-structured-output/README.md](https://github.com/2FastLabs/agent-squad/blob/main/examples/text-2-structured-output/README.md)
- [examples/ecommerce-support-simulator/README.md](https://github.com/2FastLabs/agent-squad/blob/main/examples/ecommerce-support-simulator/README.md)
- [examples/chat-demo-app/README.md](https://github.com/2FastLabs/agent-squad/blob/main/examples/chat-demo-app/README.md)
- [examples/langfuse-demo/readme.md](https://github.com/2FastLabs/agent-squad/blob/main/examples/langfuse-demo/readme.md)
- [python/src/agent_squad/types/__init__.py](https://github.com/2FastLabs/agent-squad/blob/main/python/src/agent_squad/types/__init__.py)
- [python/src/agent_squad/agents/bedrock_inline_agent.py](https://github.com/2FastLabs/agent-squad/blob/main/python/src/agent_squad/agents/bedrock_inline_agent.py)
- [python/src/agent_squad/agents/supervisor_agent.py](https://github.com/2FastLabs/agent-squad/blob/main/python/src/agent_squad/agents/supervisor_agent.py)
- [python/src/agent_squad/retrievers/retriever.py](https://github.com/2FastLabs/agent-squad/blob/main/python/src/agent_squad/retrievers/retriever.py)
- [typescript/src/agents/bedrockLLMAgent.ts](https://github.com/2FastLabs/agent-squad/blob/main/typescript/src/agents/bedrockLLMAgent.ts)
- [typescript/src/retrievers/retriever.ts](https://github.com/2FastLabs/agent-squad/blob/main/typescript/src/retrievers/retriever.ts)
# 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]()
```mermaid
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` 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:
| Example | Demonstrates |
|---------|-------------|
| Chat Demo App | Multi-domain chat with Travel (Lex), Weather (Bedrock + Open-Meteo), Math (Bedrock + tools), Tech (Bedrock + Knowledge Base), and Health agents | Source: [examples/chat-demo-app/README.md:1-30]() |
| E-commerce Support Simulator | Order Management, Product Information, and Human handoff via SQS, plus full AWS infra (AppSync, Lambda, DynamoDB, Cognito) | Source: [examples/ecommerce-support-simulator/README.md:1-40]() |
| Text-to-Structured-Output | Converts free-text queries into JSON search parameters using specialized agents | Source: [examples/text-2-structured-output/README.md:1-20]() |
| Langfuse Demo | Observability traces, spans, classification decisions, token usage, and response-time metrics | Source: [examples/langfuse-demo/readme.md:1-25]() |
## 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](getting-started.md)
- [Classifier Implementations](classifiers.md)
- [Agents Overview](agents.md)
- [Storage Backends](storage.md)
---
## Classifiers, Agents & the Orchestrator Runtime
### Related Pages
Related topics: [Overview & High-Level Architecture](#page-overview), [Storage, Retrievers, Tools & Customization](#page-storage-retrievers)
Related Source Files
The following source files were used to generate this page:
- [python/src/agent_squad/orchestrator.py](https://github.com/2FastLabs/agent-squad/blob/main/python/src/agent_squad/orchestrator.py)
- [typescript/src/orchestrator.ts](https://github.com/2FastLabs/agent-squad/blob/main/typescript/src/orchestrator.ts)
- [python/src/agent_squad/classifiers/classifier.py](https://github.com/2FastLabs/agent-squad/blob/main/python/src/agent_squad/classifiers/classifier.py)
- [python/src/agent_squad/classifiers/anthropic_classifier.py](https://github.com/2FastLabs/agent-squad/blob/main/python/src/agent_squad/classifiers/anthropic_classifier.py)
- [python/src/agent_squad/classifiers/bedrock_classifier.py](https://github.com/2FastLabs/agent-squad/blob/main/python/src/agent_squad/classifiers/bedrock_classifier.py)
- [python/src/agent_squad/classifiers/openai_classifier.py](https://github.com/2FastLabs/agent-squad/blob/main/python/src/agent_squad/classifiers/openai_classifier.py)
- [python/src/agent_squad/types/__init__.py](https://github.com/2FastLabs/agent-squad/blob/main/python/src/agent_squad/types/__init__.py)
- [python/src/agent_squad/agents/strands_agent.py](https://github.com/2FastLabs/agent-squad/blob/main/python/src/agent_squad/agents/strands_agent.py)
- [typescript/src/agents/bedrockLLMAgent.ts](https://github.com/2FastLabs/agent-squad/blob/main/typescript/src/agents/bedrockLLMAgent.ts)
- [typescript/src/agents/bedrockInlineAgent.ts](https://github.com/2FastLabs/agent-squad/blob/main/typescript/src/agents/bedrockInlineAgent.ts)
- [typescript/src/retrievers/retriever.ts](https://github.com/2FastLabs/agent-squad/blob/main/typescript/src/retrievers/retriever.ts)
- [typescript/src/utils/tool.ts](https://github.com/2FastLabs/agent-squad/blob/main/typescript/src/utils/tool.ts)
- [README.md](https://github.com/2FastLabs/agent-squad/blob/main/README.md)
- [examples/chat-demo-app/README.md](https://github.com/2FastLabs/agent-squad/blob/main/examples/chat-demo-app/README.md)
- [examples/langfuse-demo/readme.md](https://github.com/2FastLabs/agent-squad/blob/main/examples/langfuse-demo/readme.md)
# 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](https://github.com/2FastLabs/agent-squad/blob/main/README.md)).
```mermaid
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](https://github.com/2FastLabs/agent-squad/blob/main/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](https://github.com/2FastLabs/agent-squad/blob/main/README.md)).
The TypeScript orchestrator in [typescript/src/orchestrator.ts](https://github.com/2FastLabs/agent-squad/blob/main/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](https://github.com/2FastLabs/agent-squad/blob/main/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](https://github.com/2FastLabs/agent-squad/blob/main/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](https://github.com/2FastLabs/agent-squad/blob/main/python/src/agent_squad/types/__init__.py)).
- **AnthropicClassifier** ([python/src/agent_squad/classifiers/anthropic_classifier.py](https://github.com/2FastLabs/agent-squad/blob/main/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](https://github.com/2FastLabs/agent-squad/blob/main/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](https://github.com/2FastLabs/agent-squad/blob/main/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](https://github.com/2FastLabs/agent-squad/blob/main/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](https://github.com/2FastLabs/agent-squad/blob/main/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](https://github.com/2FastLabs/agent-squad/blob/main/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](https://github.com/2FastLabs/agent-squad/blob/main/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](https://github.com/2FastLabs/agent-squad/blob/main/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](https://github.com/2FastLabs/agent-squad/blob/main/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](https://github.com/2FastLabs/agent-squad/blob/main/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](https://github.com/2FastLabs/agent-squad/blob/main/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)](#)
---
## Storage, Retrievers, Tools & Customization
### Related Pages
Related topics: [Classifiers, Agents & the Orchestrator Runtime](#page-core-components), [Observability, Deployment, Examples & Community-Tracked Integrations](#page-observability-deployment)
Related Source Files
The following source files were used to generate this page:
- [typescript/src/retrievers/retriever.ts](https://github.com/2FastLabs/agent-squad/blob/main/typescript/src/retrievers/retriever.ts)
- [python/src/agent_squad/retrievers/retriever.py](https://github.com/2FastLabs/agent-squad/blob/main/python/src/agent_squad/retrievers/retriever.py)
- [typescript/src/agents/bedrockLLMAgent.ts](https://github.com/2FastLabs/agent-squad/blob/main/typescript/src/agents/bedrockLLMAgent.ts)
- [typescript/src/agents/anthropicAgent.ts](https://github.com/2FastLabs/agent-squad/blob/main/typescript/src/agents/anthropicAgent.ts)
- [typescript/src/agents/bedrockInlineAgent.ts](https://github.com/2FastLabs/agent-squad/blob/main/typescript/src/agents/bedrockInlineAgent.ts)
- [python/src/agent_squad/agents/bedrock_inline_agent.py](https://github.com/2FastLabs/agent-squad/blob/main/python/src/agent_squad/agents/bedrock_inline_agent.py)
- [typescript/src/utils/tool.ts](https://github.com/2FastLabs/agent-squad/blob/main/typescript/src/utils/tool.ts)
- [python/src/agent_squad/types/__init__.py](https://github.com/2FastLabs/agent-squad/blob/main/python/src/agent_squad/types/__init__.py)
- [examples/chat-demo-app/README.md](https://github.com/2FastLabs/agent-squad/blob/main/examples/chat-demo-app/README.md)
- [examples/langfuse-demo/readme.md](https://github.com/2FastLabs/agent-squad/blob/main/examples/langfuse-demo/readme.md)
# 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.
```ts
// Source: typescript/src/retrievers/retriever.ts:24-71
abstract class Retriever {
protected options: any;
abstract retrieve(text: any): Promise;
abstract retrieveAndCombineResults(text: any): Promise;
abstract retrieveAndGenerate(text: any): Promise;
}
```
The Python port mirrors this contract one-for-one ([python/src/agent_squad/retrievers/retriever.py](https://github.com/2FastLabs/agent-squad/blob/main/python/src/agent_squad/retrievers/retriever.py)). The three methods cover progressively richer behaviors:
| Method | Purpose | Typical Implementation |
|--------|---------|------------------------|
| `retrieve` | Return raw matching documents/chunks | Vector store lookup |
| `retrieveAndCombineResults` | Return a merged context block | Concatenate chunks with formatting |
| `retrieveAndGenerate` | Return a model-generated answer grounded in retrieved context | Bedrock Knowledge Bases `RetrieveAndGenerate` |
In practice, agents such as `BedrockLLMAgent` and `AmazonKnowledgeBasesRetriever` (shown in the [ecommerce-support-simulator example](https://github.com/2FastLabs/agent-squad/blob/main/examples/ecommerce-support-simulator/README.md)) 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:
```ts
// 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](https://github.com/2FastLabs/agent-squad/blob/main/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](https://github.com/2FastLabs/agent-squad/blob/main/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](https://github.com/2FastLabs/agent-squad/blob/main/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](https://github.com/2FastLabs/agent-squad/issues/152) explicitly requests support for sending traces to Langfuse and similar systems, and the `langfuse-demo` example ([examples/langfuse-demo/readme.md](https://github.com/2FastLabs/agent-squad/blob/main/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](https://github.com/2FastLabs/agent-squad/blob/main/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:
```python
# 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](https://github.com/2FastLabs/agent-squad/blob/main/python/src/agent_squad/agents/bedrock_inline_agent.py)), while the TypeScript port stores a parallel `toolConfig.toolMaxRecursions` counter ([typescript/src/agents/bedrockInlineAgent.ts](https://github.com/2FastLabs/agent-squad/blob/main/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](https://github.com/2FastLabs/agent-squad/blob/main/examples/chat-demo-app/README.md).
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](https://github.com/2FastLabs/agent-squad/blob/main/examples/ecommerce-support-simulator/README.md) 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](https://github.com/2FastLabs/agent-squad/blob/main/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](https://github.com/2FastLabs/agent-squad/blob/main/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](https://github.com/2FastLabs/agent-squad/blob/main/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](https://github.com/2FastLabs/agent-squad/blob/main/python/src/agent_squad/agents/bedrock_inline_agent.py)).
- **Observability gaps** — issue [#152](https://github.com/2FastLabs/agent-squad/issues/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](https://github.com/2FastLabs/agent-squad/issues/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](https://github.com/2FastLabs/agent-squad/issues/339) proposes adding Anthropic's structured thinking tool; it would slot into the same `formatTools` pipeline used by `BedrockLLMAgent` once implemented.
---
## Observability, Deployment, Examples & Community-Tracked Integrations
### Related Pages
Related topics: [Classifiers, Agents & the Orchestrator Runtime](#page-core-components), [Storage, Retrievers, Tools & Customization](#page-storage-retrievers)
Related Source Files
The following source files were used to generate this page:
- [README.md](https://github.com/2FastLabs/agent-squad/blob/main/README.md)
- [examples/langfuse-demo/readme.md](https://github.com/2FastLabs/agent-squad/blob/main/examples/langfuse-demo/readme.md)
- [examples/chat-demo-app/README.md](https://github.com/2FastLabs/agent-squad/blob/main/examples/chat-demo-app/README.md)
- [examples/ecommerce-support-simulator/README.md](https://github.com/2FastLabs/agent-squad/blob/main/examples/ecommerce-support-simulator/README.md)
- [examples/text-2-structured-output/README.md](https://github.com/2FastLabs/agent-squad/blob/main/examples/text-2-structured-output/README.md)
- [typescript/src/agents/bedrockLLMAgent.ts](https://github.com/2FastLabs/agent-squad/blob/main/typescript/src/agents/bedrockLLMAgent.ts)
- [typescript/src/agents/bedrockInlineAgent.ts](https://github.com/2FastLabs/agent-squad/blob/main/typescript/src/agents/bedrockInlineAgent.ts)
- [typescript/src/retrievers/retriever.ts](https://github.com/2FastLabs/agent-squad/blob/main/typescript/src/retrievers/retriever.ts)
- [typescript/src/utils/tool.ts](https://github.com/2FastLabs/agent-squad/blob/main/typescript/src/utils/tool.ts)
- [typescript/src/classifiers/classifier.ts](https://github.com/2FastLabs/agent-squad/blob/main/typescript/src/classifiers/classifier.ts)
- [python/src/agent_squad/agents/bedrock_inline_agent.py](https://github.com/2FastLabs/agent-squad/blob/main/python/src/agent_squad/agents/bedrock_inline_agent.py)
- [python/src/agent_squad/types/__init__.py](https://github.com/2FastLabs/agent-squad/blob/main/python/src/agent_squad/types/__init__.py)
# 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](https://github.com/2FastLabs/agent-squad/blob/main/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](https://github.com/2FastLabs/agent-squad/blob/main/typescript/src/agents/bedrockInlineAgent.ts) and [python/src/agent_squad/agents/bedrock_inline_agent.py](https://github.com/2FastLabs/agent-squad/blob/main/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](https://github.com/2FastLabs/agent-squad/blob/main/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](https://github.com/2FastLabs/agent-squad/blob/main/typescript/src/utils/tool.ts).
### 2.4 Community Request: First-Class Observability
Issue [#152](https://github.com/2FastLabs/agent-squad/issues/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](https://github.com/2FastLabs/agent-squad/blob/main/README.md). Concrete deployments can be observed in the examples:
| Example | Deployment Pattern |
|---------|-------------------|
| `chat-demo-app` | Local React/Node development with AWS backend services |
| `ecommerce-support-simulator` | Full AWS stack: CloudFront, AppSync GraphQL, SQS, Lambda, DynamoDB, Cognito |
| `text-2-structured-output` | Local script execution against Bedrock |
Sources: [examples/chat-demo-app/README.md](https://github.com/2FastLabs/agent-squad/blob/main/examples/chat-demo-app/README.md), [examples/ecommerce-support-simulator/README.md](https://github.com/2FastLabs/agent-squad/blob/main/examples/ecommerce-support-simulator/README.md), [examples/text-2-structured-output/README.md](https://github.com/2FastLabs/agent-squad/blob/main/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](https://github.com/2FastLabs/agent-squad/blob/main/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](https://github.com/2FastLabs/agent-squad/blob/main/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](https://github.com/2FastLabs/agent-squad/blob/main/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](https://github.com/2FastLabs/agent-squad/blob/main/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](https://github.com/2FastLabs/agent-squad/blob/main/examples/langfuse-demo/readme.md).
```mermaid
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
e.g. Langfuse]
```
## 5. Community-Tracked Integrations
### 5.1 MCP Servers and Tools
Issue [#299](https://github.com/2FastLabs/agent-squad/issues/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](https://github.com/2FastLabs/agent-squad/blob/main/python/src/agent_squad/agents/bedrock_inline_agent.py).
### 5.2 Anthropic "Think" Tool
Issue [#339](https://github.com/2FastLabs/agent-squad/issues/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](https://github.com/2FastLabs/agent-squad/blob/main/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](https://github.com/2FastLabs/agent-squad/issues/152)
- [Issue #299 — MCP Servers and Tools](https://github.com/2FastLabs/agent-squad/issues/299)
- [Issue #339 — Anthropic "think" tool](https://github.com/2FastLabs/agent-squad/issues/339)
- [examples/langfuse-demo](https://github.com/2FastLabs/agent-squad/tree/main/examples/langfuse-demo)
- [examples/chat-demo-app](https://github.com/2FastLabs/agent-squad/tree/main/examples/chat-demo-app)
- [examples/ecommerce-support-simulator](https://github.com/2FastLabs/agent-squad/tree/main/examples/ecommerce-support-simulator)
---
---
## Pitfall Log
Project: 2FastLabs/agent-squad
Summary: 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
- Evidence strength: source_linked
- 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.
- Evidence: capability.host_targets | https://github.com/2FastLabs/agent-squad
## 2. Capability evidence risk - Capability evidence risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.assumptions | https://github.com/2FastLabs/agent-squad
## 3. Maintenance risk - Maintenance risk requires verification
- Severity: medium
- Evidence strength: source_linked
- 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.
- Evidence: evidence.maintainer_signals | https://github.com/2FastLabs/agent-squad
## 4. Security or permission risk - Security or permission risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: downstream_validation.risk_items | https://github.com/2FastLabs/agent-squad
## 5. Security or permission risk - Security or permission risk requires verification
- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: risks.scoring_risks | https://github.com/2FastLabs/agent-squad
## 6. Maintenance risk - Maintenance risk requires verification
- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/2FastLabs/agent-squad
## 7. Maintenance risk - Maintenance risk requires verification
- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/2FastLabs/agent-squad