Claude Agent SDK Tutorial: Build an Agent in TypeScript

The Claude Agent SDK gives your own code the same agent loop and tools that power Claude Code. Install @anthropic-ai/claude-agent-sdk, set ANTHROPIC_API_KEY, call query() with a prompt and the tools you allow, and loop over the messages it streams back. A useful first agent reads files and reports.

This tutorial builds a small agent an agency could run for a client: it reads a folder of support tickets and reports the recurring issues. The code follows Anthropic's Agent SDK quickstart, checked October 2026, and was compiled against the SDK's own types.

When to use the SDK

Use the SDK when an agent has to live inside your own software: a scheduled job for a client, a step in a backend, a tool behind your own interface. For one-off scripts and CI, claude -p (the same SDK as a command-line tool) is often enough (headless mode).

Step 1: Set up the project

You need Node.js 18 or newer.

mkdir ticket-agent
cd ticket-agent
npm init -y
npm pkg set type=module
npm install @anthropic-ai/claude-agent-sdk
npm install --save-dev tsx

Setting "type": "module" lets the script use top-level await, and tsx runs TypeScript directly. The SDK bundles a Claude Code binary, so you don't need a separate install in most cases.

Step 2: Authenticate with an API key

Create a key in the Claude Console and set it in the shell that runs the agent:

export ANTHROPIC_API_KEY=your-api-key

The SDK doesn't load .env files on its own. Anthropic also says third-party products, including agents built on the SDK, may not offer claude.ai login or its rate limits unless approved, so agents you build for clients use API key billing. Price that usage into the retainer (how Claude Code is billed).

Step 3: Some data to read

Make a tickets folder with a few text files, one ticket each, for example tickets/1042.txt:

Customer can't find the booking link in the confirmation email.

In a real build these might be exports from the client's help desk.

Step 4: Write the agent

Create agent.ts:

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt:
    "Read every file in ./tickets. Group the tickets by the underlying problem and list the top 5 recurring issues, with a count and one example ticket number each. Do not change any files.",
  options: {
    allowedTools: ["Read", "Glob", "Grep"],
    systemPrompt:
      "You analyse customer support tickets for a small business. Be concise and specific. Never invent tickets that are not in the folder.",
  },
})) {
  if (message.type === "assistant" && message.message?.content) {
    for (const block of message.message.content) {
      if ("name" in block) console.log(`Tool: ${block.name}`);
    }
  } else if (message.type === "result") {
    if (message.subtype === "success") {
      console.log(message.result);
    } else {
      console.error(`Run ended: ${message.subtype}`);
    }
  }
}

Run it:

npx tsx agent.ts

What's happening:

• query() starts the agent loop and returns an async stream of messages.
• allowedTools pre-approves read-only tools, so the agent can look but not change anything.
• systemPrompt sets the agent's role and rules.
• The loop prints each tool call as it happens, then the final report from the result message.

Step 5: Give it more to do, carefully

The SDK's options control what the agent can do:

• Add Edit if it should change files, and permissionMode: "acceptEdits" to auto-approve edits. Only for files you're happy to let it change.
• Add Bash to run commands, such as tests. Use with care on client systems.
• Add WebSearch for research tasks.
• Connect MCP servers with the mcpServers option to reach a CRM, a database or a help desk API.

Keep the same rule as any client automation: start read-only, add write access only for the specific job, and keep a person reviewing anything that reaches the client's customers.

Step 6: Add a subagent

A subagent is a specialist your main agent can hand a task to. Add Agent to allowedTools and define it under agents:

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Review the authentication module for security issues",
  options: {
    allowedTools: ["Read", "Grep", "Glob", "Agent"],
    agents: {
      "code-reviewer": {
        description: "Expert code review specialist. Use for quality, security, and maintainability reviews.",
        prompt: "You are a code review specialist. Be thorough but concise.",
        tools: ["Read", "Grep", "Glob"],
        model: "sonnet",
      },
    },
  },
})) {
  console.log(message);
}

The description tells Claude when to use the subagent, and tools keeps it read-only. That's how you build agentic workflows with limits.

Step 7: Run it for a client

From Anthropic's docs, the SDK supports hosting in Docker, the cloud and CI. A typical agency setup:

1. The agent runs on a schedule, such as every Monday morning.
2. It reads the week's exports from the client's tools.
3. It writes a short report your team reviews before it goes in the client's monthly update (client retention).
4. Usage is billed to an API key per client, so costs are easy to track and pass through.

Mistakes to avoid

• Allowing every tool on day one. Grant tools per job.
• Putting the API key in code. Use environment variables or a secrets manager.
• Skipping the result check. A run can end without success. Handle the non-success subtype in your code.
• No logs. Save each run's output and the tools it used, so you can audit what the agent did.

Learn to build agents

The Stride AI Coding course teaches Claude Code and Codex for building tools and apps for clients, written for non-programmers, with weekly live calls. Many of the free guides cover agent setups.

FAQ

What is the Claude Agent SDK?

It's Anthropic's library for building agents with the same tools, agent loop and context management that power Claude Code. It's available for TypeScript and Python, and as the claude -p command line for scripts and CI.

Do I need Claude Code installed to use the SDK?

Usually not. The TypeScript and Python SDKs bundle a native Claude Code binary. Some installs skip it, for example when optional npm dependencies are omitted, and then you install Claude Code separately.

Can I use my Claude subscription with the Agent SDK?

For your own scripts, set an API key from the Claude Console. Anthropic says third-party products built on the SDK may not offer claude.ai login or its rate limits unless approved, so agents you build for clients should use API key billing.

Does the Claude Agent SDK work with Python?

Yes. The Python SDK uses the same ideas: you write an async def main(), call query() and pass allowed_tools in ClaudeAgentOptions.

How do I stop an SDK agent from changing files?

Only allow read-only tools such as Read, Glob and Grep in allowedTools, and don't set a permission mode that auto-approves edits. Add Edit or Bash only for jobs that need them.