agent-squad TypeScript — assistant guide

Node.js / TypeScript multi-agent orchestration framework (npm package agent-squad). All public symbols are exported from a single barrel typescript/src/index.ts. This file is guidance and a map — not an API reference. Read exact signatures from typescript/src/ and worked recipes from 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 + AgentSquad with no routing. Or skip the orchestrator entirely and call agent.processRequest(...) directly.
• Several specialists → multiple agents registered with orchestrator.addAgent(agent), a classifier routes each turn.
• Answers must not drift from data (prices, balances, live lookups) → GroundedAgent: a gatherer LLM calls tools, an isolated presenter LLM speaks only from the curated results.
• Fixed pipeline → ChainAgent: each agent's output is the next agent's input.
• One lead LLM coordinating a team → SupervisorAgent: the lead calls sub-agents as tools.
• External tools via MCP → MCPToolProvider (async factory pattern, optional peer dep).
• RAG context → attach a Retriever to any agent that supports retriever? in its options.

How to install

npm install agent-squad

Optional peer dependencies — install only what you use:

@modelcontextprotocol/sdk and @dakera-ai/dakera are the only two true optional peer deps; everything else ships as a hard dependency at the moment.

How a turn works

routeRequest is the single entry point. It classifies the input, dispatches to the selected agent, saves the exchange, and returns an AgentResponse. The response is either a plain string or a Node.js Transform stream:

import { AgentSquad, BedrockLLMAgent, BedrockClassifier } from 'agent-squad';

const orchestrator = new AgentSquad({
  classifier: new BedrockClassifier(),   // default when omitted
  // storage: new DynamoDbChatStorage(...),
  // config: { LOG_AGENT_CHAT: true, MAX_MESSAGE_PAIRS_PER_AGENT: 50 },
});

orchestrator.addAgent(new BedrockLLMAgent({
  name: 'Tech Support',
  description: 'Handles technical questions about software and hardware',
  streaming: true,
}));

const response = await orchestrator.routeRequest(
  userInput,
  userId,
  sessionId,
  additionalParams   // optional Record<string, any>
);

if (response.streaming) {
  // response.output is an AccumulatorTransform (Node.js Transform)
  for await (const chunk of response.output) {
    process.stdout.write(chunk);
  }
} else {
  // response.output is a string
  console.log(response.output);
  // response.thinking? is set when the agent used extended thinking
}

// response.metadata: { agentId, agentName, userId, sessionId, userInput, additionalParams }

routeRequest never throws — it catches all errors and returns them as a non-streaming AgentResponse with the error string in output (configurable via GENERAL_ROUTING_ERROR_MSG_MESSAGE).

The pieces

Orchestrator: AgentSquad

new AgentSquad(options?: OrchestratorOptions)

Key OrchestratorOptions fields:

Useful methods: addAgent(agent), setDefaultAgent(agent), getDefaultAgent(), getAllAgents(), analyzeAgentOverlap(), classifyRequest(...), agentProcessRequest(...).

The classifier is exposed as a public field (orchestrator.classifier) so its system prompt can be overridden after construction.

Agents

All agents extend Agent and require at minimum { name, description } in their options.

agent.id is derived automatically from name: non-alphanumeric stripped, spaces → hyphens, lowercased. "Tech Support" → "tech-support". This is the key used for storage and classifier matching — it must be stable across restarts.

AgentOptions base fields: name (required), description (required), saveChat? (default true), logger?, LOG_AGENT_DEBUG_TRACE?.

BedrockLLMAgent toolConfig shape:

toolConfig: {
  tool: AgentTools | Tool[],   // AgentTools instance or raw Bedrock Tool array
  useToolHandler: (response: any, conversation: ConversationMessage[]) => any,
  toolMaxRecursions?: number,
}

When using MCPToolProvider, pass it as toolConfig.tool and omit useToolHandler — the provider overrides toolHandler internally.

GroundedAgent

Two-LLM anti-hallucination pattern. The gatherer calls tools; the presenter receives only the curated facts (never raw tool output, never chat history from the gatherer):

import {
  GroundedAgent, DataBlockCurator, PerToolCurator, PresenterPrompt,
  BedrockLLMAgent, AgentTools, AgentTool,
} from 'agent-squad';

const tools = new AgentTools([
  new AgentTool({ name: 'get_price', description: '...', func: async ({ sku }) => fetchPrice(sku) }),
]);

const gatherer = new BedrockLLMAgent({ name: 'Gatherer', description: '...', toolConfig: { tool: tools, useToolHandler: ... } });
const presenter = new BedrockLLMAgent({ name: 'Presenter', description: '...' });

const agent = new GroundedAgent({
  name: 'Price Agent',
  description: 'Answers pricing questions grounded in live data',
  gatherer,
  presenter,
  tools,
  curator: new DataBlockCurator(),          // default; or PerToolCurator for per-tool formatting
  presenterPrompt: PresenterPrompt.default(), // generic grounding prompt; or per-tool map
});

A no-tool turn (chit-chat) is answered by the gatherer directly, skipping the presenter.

Classifiers

All classifiers support setSystemPrompt(template?, variables?) to override the routing prompt. Template variables use {{VAR_NAME}} syntax; AGENT_DESCRIPTIONS and HISTORY are always injected automatically.

Storage

Storage is keyed by (userId, sessionId, agentId). fetchAllChats(userId, sessionId) is used by the classifier to get cross-agent history for context.

Retrievers

DakeraRetrieverOptions: namespace (required), apiKey? (falls back to DAKERA_API_KEY env), url? (falls back to DAKERA_URL then http://localhost:3000), topK? (default 10), filter?.

Attach to a BedrockLLMAgent via retriever: option. The agent calls retriever.retrieveAndCombineResults(inputText) to augment its system prompt.

DakeraRetriever.retrieveAndGenerate() always throws — Dakera is retrieval-only.

Tools: AgentTools and AgentTool

import { AgentTools, AgentTool } from 'agent-squad';

const myTools = new AgentTools([
  new AgentTool({
    name: 'search_web',
    description: 'Search the web for current information',
    properties: {
      query: { type: 'string', description: 'The search query' },
    },
    required: ['query'],
    func: async ({ query }) => webSearch(query),
  }),
]);

AgentTool constructor will auto-extract parameter names from func if properties is omitted — but this is fragile with minification. Always pass explicit properties and required.

MCPToolProvider

MCPToolProvider extends AgentTools. Always use the async factory — never new MCPToolProvider(...) directly — so that tool definitions are fetched before the agent makes its first API call:

import { MCPToolProvider } from 'agent-squad';

const provider = await MCPToolProvider.create([
  { type: 'stdio', command: 'uvx', args: ['my-mcp-server'] },
  { type: 'sse', url: 'http://localhost:3000/sse', headers: { Authorization: 'Bearer tok' } },
]);

const agent = new BedrockLLMAgent({
  name: 'MCP Agent',
  description: 'Agent with MCP tools',
  toolConfig: { tool: provider },
});

// Clean up when done (closes stdio processes and SSE connections)
await provider.disconnect();

MCPServerConfig.type is "stdio" or "sse". For stdio: command is required, args? and env? are optional. For sse: url is required, headers? is optional.

MCPToolProvider overrides toBedrockFormat(), toAnthropicFormat(), and toOpenAIFormat() to pass MCP inputSchema through unchanged rather than re-serializing it.

Requires npm install @modelcontextprotocol/sdk. The SDK is imported lazily via await import() inside ensureConnected() — installing agent-squad without the SDK is safe as long as you don't instantiate MCPToolProvider.

Custom implementations

Extend the abstract base class and pass your type where the built-in goes.

ClassifierResult shape: { selectedAgent: Agent | null, confidence: number }.

Classifier base class provides setAgents, setHistory, setSystemPrompt, and getAgentById(agentId) — use getAgentById in your processRequest to look up the selected agent from the classifier's registered map.

Gotchas

• agentId is derived from name at construction time: non-alphanumeric stripped, spaces replaced with -, lowercased. Changing an agent's name changes its id, which breaks chat history lookups in storage. Keep names stable across deployments.

• Streaming response is a Node.js Transform stream, not an async generator. Check response.streaming before iterating. The transform accumulates the full response internally; for await (const chunk of response.output) works because Transform implements AsyncIterable. Do not call response.output.read() manually.

• routeRequest never throws. Errors are returned as non-streaming AgentResponse with the error string in output. If you need to distinguish errors from real responses, check response.metadata.errorType === 'classification_failed' or inspect metadata.agentId.

• MCPToolProvider.create(...) must be awaited before the agent is used. The constructor alone does not connect; calling processRequest before create resolves means tool definitions are empty and the agent will behave as if it has no tools.

• BedrockClassifier is the default. If boto3/AWS credentials are not configured and you don't pass an explicit classifier, AgentSquad will construct a BedrockClassifier that will fail at runtime. Pass classifier: new AnthropicClassifier(...) or new OpenAIClassifier(...) if you're not on AWS.

• Optional peer deps use lazy import/require. MCPToolProvider uses await import(...) inside ensureConnected(); DakeraRetriever uses require(...) inside the constructor. Neither adds a top-level import, so a missing peer dep is only discovered at instantiation time — not at module load. Throw the missing-dep error early, before user input arrives.

• SupervisorAgent restrictions: leadAgent must be BedrockLLMAgent or AnthropicAgent; the lead agent must have no toolConfig set (SupervisorAgent wires its own tool loop). Pass additional native tools via extraTools.

• saveChat defaults to true. Every agent persists both sides of each exchange after the turn completes. Set saveChat: false on agents that should not write to storage (e.g. a presenter inside a GroundedAgent that is managed externally).

• additionalParams flows through routeRequest → dispatchToAgent → agent.processRequest. Use it to pass per-request context (tenant ID, request ID, feature flags) without touching agent options. The values end up in response.metadata.additionalParams.

• AgentTools auto-extracts parameter names from func via .toString(). This breaks with minification and TypeScript arrow functions with destructured arguments. Always supply explicit properties and required arrays to AgentTool.

• ThinkingResponse: when a BedrockLLMAgent is configured with reasoningConfig, the non-streaming path may return response.thinking (a string) alongside response.output. The streaming path does not surface thinking tokens separately.

Go deeper

• Prose & recipes — docs/src/content/docs/ (run the site from docs/ with npm run dev): orchestrator/overview, agents/built-in/bedrock-llm-agent, agents/built-in/grounded-agent, classifiers/overview, storage/overview, retrievers/overview, tools/mcp.
• Exact signatures — typescript/src/ (orchestrator.ts, agents/, classifiers/, storage/, retrievers/, tools/mcpToolProvider.ts, utils/tool.ts, types/index.ts).
• Tests — typescript/tests/ for usage patterns and mock strategies (virtual mocks for optional peer deps via jest.mock(..., { virtual: true })).
• Barrel — typescript/src/index.ts is the definitive list of every public symbol.