Agent Squad for TypeScript

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.