← 17.217.4 →
947 words Slides

17.3 TypeScript SDK Setup

Course: Claude Code - Enterprise Development

Section: Claude Agent SDK

Video Length: 2-3 minutes

Presenter: Daniel Treasure

Opening Hook

"If you're a TypeScript/Node.js shop, you'll appreciate the SDK's strong typing and native async/await. Let's set up the TypeScript SDK, create your first agent, and run it in Node.js."

Key Talking Points

What to say:

  • "TypeScript SDK follows Node.js patterns—async/await, typed interfaces, npm packages."
  • "Strong typing catches errors early and provides IDE autocomplete."
  • "Setup mirrors Python version: install, set env vars, define agent, run."
  • "Use TypeScript for production applications where type safety matters."

What to show on screen:

  • Terminal showing npm install
  • .env file configuration
  • TypeScript agent definition with type hints
  • Agent execution and output
  • Compiled JavaScript running

Demo Plan

[00:00 - 00:30] Installation & Project Setup 1. Show: npm init -y to create package.json 2. Install: npm install @anthropic-ai/sdk 3. Install TypeScript dev dependencies: npm install -D typescript @types/node ts-node 4. Create tsconfig.json with basic config 5. Create .env file with API key

[00:30 - 01:30] First Agent (TypeScript) 1. Create first-agent.ts 2. Import: import Anthropic from "@anthropic-ai/sdk" 3. Initialize client with type safety 4. Define agent configuration 5. Call: agent.run(task) 6. Show promise handling with async/await 7. Run: npx ts-node first-agent.ts

[01:30 - 02:15] Type Safety & Interfaces 1. Show IDE autocomplete for agent options 2. Demonstrate: TypeScript catching type errors 3. Show: Result type definition with IntelliSense 4. Contrast with Python (runtime errors) vs. TypeScript (compile time)

[02:15 - 03:00] (Optional) Build & Execution 1. Show: npm run build to compile TypeScript to JavaScript 2. Show: node dist/first-agent.js running compiled code 3. Explain: Development (ts-node) vs. Production (compiled JS)

Code Examples & Commands

Installation & Setup:

# Initialize project
npm init -y

# Install SDK and dependencies
npm install @anthropic-ai/sdk
npm install -D typescript @types/node ts-node dotenv

# Create tsconfig.json
npx tsc --init

# Create .env file
echo "ANTHROPIC_API_KEY=your_key_here" > .env

First agent script (first-agent.ts):

import Anthropic from "@anthropic-ai/sdk";
import dotenv from "dotenv";

dotenv.config();

async function main(): Promise<void> {
  // Initialize client
  const client = new Anthropic({
    apiKey: process.env.ANTHROPIC_API_KEY,
  });

  // Define task
  const task = "Explain what a closure is in JavaScript with a simple example";

  console.log(`Running task: ${task}\n`);

  // Create message (note: Agent SDK may have different interface)
  // This example uses the Messages API; check current Agent SDK docs
  const message = await client.messages.create({
    model: "claude-sonnet-4-5-20250929",
    max_tokens: 1024,
    system: "You are a helpful JavaScript expert. Provide clear, concise answers.",
    messages: [
      {
        role: "user",
        content: task,
      },
    ],
  });

  // Display result
  console.log("Result:");
  console.log(message.content[0].type === "text" ? message.content[0].text : "");
}

main().catch(console.error);

With error handling:

import Anthropic from "@anthropic-ai/sdk";
import dotenv from "dotenv";

dotenv.config();

async function runAgent(task: string): Promise<string> {
  try {
    const client = new Anthropic();

    const message = await client.messages.create({
      model: "claude-sonnet-4-5-20250929",
      max_tokens: 2048,
      system: "You are a code expert.",
      messages: [{ role: "user", content: task }],
    });

    if (message.content[0].type === "text") {
      return message.content[0].text;
    }
    throw new Error("Unexpected response format");
  } catch (error) {
    console.error("Agent failed:", error);
    throw error;
  }
}

runAgent("What is TypeScript?").then(console.log);

With async/await patterns:

import Anthropic from "@anthropic-ai/sdk";

async function reviewCode(code: string): Promise<void> {
  const client = new Anthropic();

  console.log("Analyzing code...");

  const message = await client.messages.create({
    model: "claude-sonnet-4-5-20250929",
    max_tokens: 1024,
    messages: [
      {
        role: "user",
        content: `Review this code for issues:\n${code}`,
      },
    ],
  });

  if (message.content[0].type === "text") {
    console.log("Review:\n", message.content[0].text);
  }
}

// Usage
const exampleCode = `function add(a, b) { return a + b; }`;
reviewCode(exampleCode).catch(console.error);

package.json scripts:

{
  "name": "claude-agent-example",
  "version": "1.0.0",
  "scripts": {
    "dev": "ts-node src/first-agent.ts",
    "build": "tsc",
    "start": "node dist/first-agent.js"
  },
  "dependencies": {
    "@anthropic-ai/sdk": "latest"
  },
  "devDependencies": {
    "@types/node": "latest",
    "typescript": "latest",
    "ts-node": "latest",
    "dotenv": "latest"
  }
}

Gotchas & Tips

Gotcha 1: async/await vs. Promises - SDK is promise-based; await syntax is cleaner - Gotcha: Forgetting await on async calls leads to unresolved promises

Gotcha 2: TypeScript Configuration - Need proper tsconfig.json for ts-node to work - Common issues: ES target too old, module system mismatch

Gotcha 3: Node.js Version - Use Node.js 18+ for best compatibility - Older versions may have fetch/crypto issues

Gotcha 4: Environment Variables - Must load dotenv early: import dotenv from "dotenv"; dotenv.config(); - Order matters: load before creating client

Tip 1: IDE Support - TypeScript + VS Code gives excellent autocomplete for SDK - Hover over types to see documentation

Tip 2: Development Workflow - Use ts-node for development (no build step) - Use tsc && node for production

Tip 3: Error Types - SDK throws specific error types (APIError, AuthenticationError, etc.) - Catch and handle appropriately

Tip 4: Source Maps - Enable source maps in tsconfig.json for better debugging - Makes compiled JavaScript easier to debug

Lead-out

"You've got TypeScript setup working. Both Python and TypeScript SDKs share the same concepts. Next, we'll dive into advanced features—streaming responses, handling permissions, and managing agent state. These apply to both languages."

Reference URLs

  • Anthropic TypeScript SDK: https://github.com/anthropics/anthropic-sdk-typescript
  • TypeScript Handbook: https://www.typescriptlang.org/docs/
  • Node.js Best Practices: https://nodejs.org/en/docs/
  • ts-node Documentation: https://typestrong.org/ts-node/

Prep Reading

  • Install Node.js 18+ (if not already done)
  • Review TypeScript basics (5 min)
  • Read SDK installation guide (5 min)

Notes for Daniel

  • Comparison to Python: Briefly mention how TypeScript setup mirrors Python—same concepts, different syntax.
  • Type safety selling point: Emphasize that strong typing catches bugs before runtime.
  • Production angle: Mention that TypeScript is preferred for production services (financial, healthcare, critical systems).
  • IDE magic: Show how IDE autocomplete saves time and prevents errors.