Introduction to Claude Agent SDK in TypeScript

The Claude Agent SDK provides developers with a robust framework for constructing sophisticated AI agents powered by Anthropic's Claude models. Designed specifically for TypeScript environments, this SDK simplifies the process of integrating advanced agentic capabilities into your applications. Whether you're automating complex tasks, building conversational interfaces, or creating multi-step reasoning systems, the SDK handles the intricacies of model interactions, tool calling, and state management.

Key benefits include native support for asynchronous operations, type-safe tool definitions, and built-in mechanisms for human-in-the-loop interventions. By abstracting away low-level API calls, it allows you to focus on agent logic rather than boilerplate code. This guide will methodically walk you through installation, core concepts, practical implementations, and advanced configurations, ensuring you can deploy production-ready agents efficiently.

For the full source code and examples, check out the official repository at anthropic-sdk-typescript.

Step 1: Installation and Setup

Begin by setting up your development environment. Ensure you have Node.js (version 18 or higher) installed, as the SDK relies on modern JavaScript features.

Prerequisites

• Node.js ≥ 18
• npm or yarn package manager
• An Anthropic API key (obtain from the Anthropic Console)

Install the SDK via npm:

npm install @anthropic-ai/sdk

This command pulls in the core @anthropic-ai/sdk package, which includes the Agent SDK modules. No additional dependencies are typically needed for basic usage.

Environment Configuration

Create a .env file in your project root to securely store your API key:

ANTHROPIC_API_KEY=your-api-key-here

Load it using a library like dotenv:

npm install dotenv

In your TypeScript code:

import 'dotenv/config';
import { Anthropic } from '@anthropic-ai/sdk';

const client = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });

This setup ensures your credentials remain secure and are not hardcoded.

Step 2: Creating Your First Agent

Agents are the central entities in the SDK. They encapsulate a Claude model instance configured for agentic behavior, including tool access and custom instructions.

Basic Agent Initialization

Here's a simple agent that responds to messages:

import { Agent } from '@anthropic-ai/sdk/resource';

const agent = new Agent({
  name: 'MyFirstAgent',
  model: 'claude-3-5-sonnet-20240620',
  instructions: 'You are a helpful assistant.',
  client,
});

const result = await agent.run('Hello, world!');
console.log(result.finalArtifact?.text);

This creates an agent named 'MyFirstAgent' using the latest Sonnet model. The run method processes the input and returns a RunResult object, where finalArtifact holds the output.

Understanding Agent Parameters

• name: A unique identifier for logging and debugging.
• model: Specify Claude models like 'claude-3-opus-20240229', 'claude-3-sonnet-20240229', or 'claude-3-5-sonnet-20240620' for optimal performance.
• instructions: System prompt defining the agent's persona and rules.
• client: Your initialized Anthropic client.

Additional options include maxIterations to cap reasoning loops and maxTokens for output limits.

Step 3: Integrating Tools

Tools enable agents to interact with external systems, such as APIs, databases, or file operations. The SDK supports both built-in and custom tools with full TypeScript typing.

Defining Custom Tools

Tools are functions decorated with metadata:

function calculator(expression: string): number {
  return eval(expression); // Use safely in production
}

const tools = {
  calculator: {
    description: 'Evaluate a mathematical expression',
    inputSchema: {
      type: 'object',
      properties: { expression: { type: 'string' } },
    } as const,
  },
};

const agent = new Agent({
  // ... other params
  tools: [calculator],
});

The inputSchema follows JSON Schema for validation and tool calling.

Running Agents with Tools

const result = await agent.run('What is 15 * 23?');

The agent will automatically invoke the calculator tool if needed, parse the result, and incorporate it into its response. Observe the steps array in RunResult for tool call traces:

result.steps.forEach(step => {
  if (step.type === 'tool_use') {
    console.log('Tool called:', step.toolUseInput);
  }
});

Built-in Tools

The SDK includes utilities like webSearch or codeInterpreter. Extend with community tools from anthropic-sdk-typescript examples.

Step 4: Human-in-the-Loop Workflows

For safety and oversight, integrate human approval:

const agent = new Agent({
  // ...
  humanInTheLoop: async (step) => {
    console.log('Approve? ', step);
    return { approved: true, edits: [] }; // Or false to halt
  },
});

The callback triggers before tool executions or final outputs, allowing interventions. This is crucial for production agents handling sensitive data.

Step 5: Advanced Configurations

Memory and Context Management

Agents maintain conversation history via memory. Persist it for long-running sessions:

import { Memory } from '@anthropic-ai/sdk/resource';

const memory = new Memory();
agent.memory = memory;

Streaming Responses

For real-time UIs:

const stream = await agent.run('Explain quantum computing', { stream: true });
for await (const chunk of stream) {
  process.stdout.write(chunk.delta);
}

Error Handling and Retries

Wrap runs in try-catch and use exponential backoff:

try {
  const result = await agent.run(prompt);
} catch (error) {
  if (error.status === 429) {
    // Retry logic
  }
}

Step 6: Real-World Applications

Task Automation Agent

Build an agent that fetches weather and books flights:

// Define weatherTool, flightBookerTool
const travelAgent = new Agent({
  instructions: 'Plan efficient trips based on user prefs.',
  tools: [weatherTool, flightBookerTool],
});

const plan = await travelAgent.run('Plan a trip to Tokyo next week.');

This agent chains tool calls: check weather → suggest dates → book flights.

Code Generation Agent

Leverage Claude's coding prowess:

const coder = new Agent({
  model: 'claude-3-5-sonnet-20240620',
  instructions: 'Write clean TypeScript code.',
  tools: [fileWriter], // Custom tool for saving code
});

Ideal for IDE plugins or CI/CD automation.

Best Practices

• Prompt Engineering: Use structured instructions with examples.
• Monitoring: Log all RunResult for analysis.
• Cost Optimization: Set maxIterations: 10 and monitor token usage.
• Security: Validate tool inputs to prevent injection attacks.
• Testing: Unit test tools independently; integration test agent flows.

Troubleshooting Common Issues

Next Steps

Explore streaming, multiplayer agents, or deploy to Vercel/Cloudflare. Dive into the SDK source and contribute via GitHub issues.

This SDK empowers scalable AI agents—start prototyping today for transformative applications.