· 6 min read
The Claude Agent SDK is a TypeScript toolkit for building multi-agent systems on top of Anthropic's Claude models. Rather than sending one-off prompts and manually stitching outputs together, the SDK gives you primitives for defining agents, equipping them with tools, and coordinating them in structured workflows.
If you have been building agent teams by copy-pasting prompts into Claude Code or the API console, the SDK is the next step: it moves your agent coordination from ad-hoc sessions into reproducible, version-controlled code that you can test, iterate, and deploy.
Both approaches produce multi-agent output. The distinction is about repeatability and integration.
Use Claude Code prompts when:
Use the Claude Agent SDK when:
In practice, many teams start with Claude Code prompts to prototype their agent team configuration, then migrate to the SDK once the workflow is validated and needs to run at scale.
You need Node.js 20 or later and a valid Anthropic API key. The SDK is distributed as an npm package and uses ESM modules.
Install the SDK and its peer dependency in your project:
npm install @anthropic-ai/agent-sdk
Set your API key as an environment variable:
export ANTHROPIC_API_KEY=your-key-here
Your tsconfig.json needs to target ESM. The key settings are "module": "NodeNext" and "moduleResolution": "NodeNext". If you are starting a new project, the SDK ships with a recommended configuration you can extend.
An agent in the SDK is a combination of three things: a role definition (the system prompt), a set of tools it can use, and configuration for how it interacts with the model.
Here is the structure for a basic research agent:
import { Agent } from "@anthropic-ai/agent-sdk";
const researchAgent = new Agent({
name: "Market Researcher",
model: "claude-sonnet-4-20250514",
systemPrompt: `You are a Market Research Analyst. Your job is to
identify market size, growth trends, and key players for a
given industry segment. You produce structured findings with
sources. You do NOT make strategic recommendations — that is
handled by a separate agent.`,
temperature: 0.3,
});
Notice the explicit boundary in the system prompt: this agent researches but does not recommend. Clear scope prevents agents from stepping on each other when you compose them into teams later.
Tools give agents the ability to interact with external systems. The SDK provides a typed tool interface where you define the input schema, the execution function, and a description that helps the agent understand when to use the tool.
import { Tool } from "@anthropic-ai/agent-sdk";
const webSearchTool = new Tool({
name: "web_search",
description: "Search the web for current information on a topic",
inputSchema: {
type: "object",
properties: {
query: { type: "string", description: "The search query" },
maxResults: { type: "number", description: "Max results to return" },
},
required: ["query"],
},
execute: async ({ query, maxResults = 5 }) => {
// Your search implementation here
const results = await searchProvider.search(query, maxResults);
return JSON.stringify(results);
},
});
// Attach tools when defining the agent
const researchAgent = new Agent({
name: "Market Researcher",
model: "claude-sonnet-4-20250514",
systemPrompt: "...",
tools: [webSearchTool, databaseQueryTool],
});
The tool description matters more than you might expect. Agents decide which tool to call based on the description, so write it the way you would explain the tool to a colleague.
Here is where the SDK shines. Instead of running agents independently and manually passing output between them, you define a coordination pattern that handles the orchestration.
This example creates a team where a Research Agent gathers data and a Strategy Agent analyzes it:
import { Agent, Pipeline } from "@anthropic-ai/agent-sdk";
const researcher = new Agent({
name: "Research Analyst",
model: "claude-sonnet-4-20250514",
systemPrompt: `You gather market data for a given industry.
Output a structured JSON document with fields: market_size,
growth_rate, top_competitors (array), and key_trends (array).`,
tools: [webSearchTool],
});
const strategist = new Agent({
name: "Strategy Advisor",
model: "claude-sonnet-4-20250514",
systemPrompt: `You receive market research data and produce a
strategic assessment. Identify the top 3 opportunities,
the biggest risk, and a recommended positioning strategy.
Write for a startup founder audience.`,
});
const pipeline = new Pipeline({
agents: [researcher, strategist],
name: "Market Entry Analysis",
});
const result = await pipeline.run({
input: "Analyze the European B2B project management SaaS market",
});
The Pipeline handles passing the researcher's output to the strategist as context. You do not need to manually serialize or deserialize anything between stages.
For more complex tasks where the work plan might change based on intermediate results, use the Supervisor pattern:
import { Supervisor } from "@anthropic-ai/agent-sdk";
const supervisor = new Supervisor({
name: "Project Lead",
model: "claude-sonnet-4-20250514",
systemPrompt: `You coordinate a research team. Assign tasks to
available workers based on the user's request. Review each
worker's output before proceeding. Synthesize all findings
into a final report.`,
workers: [researcher, strategist, financialAnalyst],
});
const result = await supervisor.run({
input: "Should we enter the Nordic fintech market? Budget: $2M.",
});
The Supervisor agent decides which workers to engage, in what order, and can request revisions before moving to the next phase.
The SDK maps directly to the coordination patterns used in agent team design:
Pipeline -- agents run in order, each receiving the previous agent's outputSupervisor -- a coordinator dynamically assigns and reviews workParallelGroup -- multiple agents run simultaneously on independent tasks, with results merged at the endDebate -- agents argue opposing positions while a judge synthesizesIf you have already designed your team using prompt-based configurations, translating to the SDK is straightforward. Each agent's prompt becomes a systemPrompt, each agent's role becomes a named Agent, and the coordination pattern becomes the orchestration primitive.
Production agent workflows need to handle failures gracefully. The SDK provides built-in retry logic, timeout configuration, and fallback handling:
const agent = new Agent({
name: "Researcher",
model: "claude-sonnet-4-20250514",
systemPrompt: "...",
maxRetries: 3,
timeoutMs: 60000,
onError: (error) => {
logger.warn(`Agent failed: ${error.message}`);
return { fallback: "Unable to complete research. Proceeding with available data." };
},
});
This is one of the biggest advantages over prompt-based workflows. When an agent fails mid-pipeline, the SDK can retry, fall back, or surface the error programmatically rather than silently producing incomplete output.
Once you have a basic multi-agent pipeline running, the natural next steps are:
If you want to explore multi-agent team configurations before writing SDK code, you can generate complete agent team setups -- with prompts, roles, coordination patterns, and deliverables -- in seconds.