Agent Squad Documentation

Agent Squad is a multi-agent orchestration framework available in two primary runtime tracks:

Python / TypeScript

Designed for server and cloud environments. Features include:

• Orchestration with Bedrock, Anthropic, and OpenAI classifiers.
• Streaming responses.
• Storage backends for Lambda, DynamoDB, and SQL.
• Support for retrievers.
• Available via npm and PyPI.

Swift

Designed for Apple platforms (iOS 16+ / macOS 14+). Features include:

• On-device agent orchestration.
• MCP (Model Context Protocol) tools.
• Realtime voice support.
• Rich Tool UIs.
• SwiftData storage and built-in tracing.
• Available via GitHub.

In Agent Squad, a Retriever is a component used to fetch relevant information from a large corpus of data or a database in response to a query. They are used to enhance LLM performance by providing external knowledge that is not present in the model's training data.

Key functions include:

• Improving Context and Relevance: Providing specific context that the LLM cannot generate from internal knowledge alone.
• Memory Augmentation: Acting as an extended memory for up-to-date or highly detailed information.
• Efficiency: Allowing the system to pull only necessary information on-demand rather than requiring model retraining on large datasets.

The GroundedAgent is an anti-hallucination pattern available in Python, TypeScript, and Swift. It uses two LLMs to ensure accuracy:

1. Gatherer: Calls tools and retrieves raw data but does not communicate with the user.
2. Presenter: Receives only the curated tool output and writes the final reply. It has no access to tool transcripts or chat history, preventing it from inventing information (like prices or availability) not present in the fetched data.

The Agent Squad System uses a storage system to preserve context across interactions by saving both user messages and assistant responses.

Conversations are uniquely identified by a composite key consisting of:

• userId
• sessionId
• agentId

All storage backends must implement the ConversationStorage interface.

Agent Squad uses an OpenTelemetry-style tracing pipeline for Swift. The pipeline consists of three layers that can be swapped independently:

1. Tracer: Opens spans.
2. SpanProcessor: Assembles and batches spans.
3. TraceExporter: Ships finished TraceEvent records to a backend.

Recommended Configurations

• Local Development: Use OSLogTracer to write directly to os.Logger (viewable in Console.app or Instruments) without network configuration.
• Production: Use ProcessingTracer + BatchSpanProcessor + OTLPExporter to post OTLP/HTTP JSON to compatible collectors like Langfuse, Datadog, Grafana, or Honeycomb.

A tool-using turn follows a two-phase execution model:

1. Gather Phase: The gatherer response runs text-only (it never speaks). It calls tools and accumulates results. The session emits .state(.thinking) during this phase.
2. Present Phase: Tool results are curated by the curator and passed to an isolated presenter response. The presenter speaks from the curated block only. The session emits .state(.presenting).

Direct Response Path: If no tools are called, the gatherer's accumulated text is used for a direct response where the model speaks from conversation history without grounding. This path is governed by directInstructions and emits .state(.speaking).

The framework supports a variety of built-in agents and allows for custom implementations.

Built-in Agents:

• Bedrock LLM Agent: Uses Amazon Bedrock's API.
• Amazon Bedrock Agent: Interfaces with existing Amazon Bedrock Agents.
• Amazon Lex Bot: Implements logic to call Amazon Lex chatbots.
• Lambda Agent: Invokes AWS Lambda functions (useful for integrating Python-based agents into the system).
• OpenAI Agent: Uses OpenAI models like GPT-3.5 and GPT-4.

You can also create custom agents to meet specific requirements.

To use AWS Lambda Powertools for logging with Agent Squad, follow these steps:

1. Install the package:

   npm install @aws-lambda-powertools/logger

2. Initialize the Logger and pass it to the AgentSquad instance via the logger option.

import { Logger } from "@aws-lambda-powertools/logger";

const logger = new Logger({
  logLevel: "INFO",
  serviceName: "MyOrchestratorService"
});

const orchestrator = new AgentSquad({
  storage: storage,
  config: {
    LOG_AGENT_CHAT: true,
    LOG_CLASSIFIER_CHAT: true,
    LOG_CLASSIFIER_RAW_OUTPUT: true,
    LOG_CLASSIFIER_OUTPUT: true,
    LOG_EXECUTION_TIMES: true,
  },
  logger: logger,
});

Agent Squad uses Amazon Bedrock by default for classification and agent responses. You must have the AWS CLI installed and configured on your machine.

1. Install AWS CLI.
2. Configure credentials via aws configure.
3. Verify access by running:

   aws sts get-caller-identity

4. Ensure you have requested model access in the AWS Bedrock console for the models you intend to use (e.g., Claude 3.5 Sonnet, Claude 3 Haiku).