Claude Agent Builder - TypeScript

Build production-ready Claude Agent SDK agents with TypeScript for business automation, workflow orchestration, and AI-powered operations.

Quick Start

Installation

npm install @anthropic-ai/claude-agent-sdk zod npm install --save-dev typescript @types/node

Basic Agent

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

for await (const message of query({ prompt: "Your task description", options: { allowedTools: ["Read", "Edit"], permissionMode: "acceptEdits" } })) { if (message.type === "result") { console.log("Done:", message.result); } }

With Custom Tools

import { tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk"; import { z } from "zod";

const server = createSdkMcpServer({ name: "my-tools", version: "1.0.0", tools: [ tool( "process_data", "Process business data", { input: z.string() }, async (args) => ({ content: [{ type: "text", text: Processed: ${args.input} }] }) ) ] });

async function* messages() { yield { type: "user" as const, message: { role: "user" as const, content: "Use the tool" } }; }

for await (const msg of query({ prompt: messages(), options: { mcpServers: { "tools": server }, allowedTools: ["mcp__tools__process_data"] } })) { // Handle messages }

Core Documentation

1. SDK API Reference

Complete TypeScript SDK API documentation.

Read: sdk-api.md

Key topics:

• Installation & setup

• query() and V2 API functions

• tool() and createSdkMcpServer()

• Configuration options

• Message types

• Error handling

• Advanced features (context management, cloud providers)

2. Custom Tool Development

Advanced patterns for creating production-ready custom tools.

Read: custom-tools.md

Key topics:

• Tool design principles (single responsibility, clear contracts)

• Common patterns (data retrieval, API gateway, file processing, state management)

• Error handling (recoverable vs fatal errors)

• Type safety with Zod

• Performance optimization (caching, batching)

• Security best practices

• Tool testing strategies

3. Testing & Evaluation

Production-grade testing and evaluation strategies.

Read: testing-evaluation.md

Key topics:

• Three-layer testing strategy (unit, integration, evaluation sets)

• Evaluation metrics (success rate, semantic similarity, latency, token usage)

• Test infrastructure (harnesses, snapshot testing)

• Regression testing with golden datasets

• Continuous evaluation in CI/CD

• Production monitoring

4. Production Monitoring

Observability and monitoring for deployed agents.

Read: monitoring.md

Key topics:

• Key metrics (performance, token usage, quality)

• Observability wrappers

• Structured logging

• Distributed tracing

• Alerting thresholds

• Dashboard metrics

5. Multi-Agent Orchestration

Patterns for coordinating multiple specialized agents.

Read: orchestration.md

Key topics:

• Orchestration strategies (sequential, manager-worker, parallel, hierarchical, reflective)

• State management across agents

• Real-world patterns

• Dynamic orchestration

6. Real-World Examples

Production-ready agent implementations.

Read: examples.md

Examples included:

• Business intake agent

• Code review agent

• Data analysis agent

• API integration agent

• Aging-in-place design agent

• Multi-agent system

Agent Template

Production-ready starter template with monitoring, error handling, and testing.

Location: assets/agent-template/

Files:

• agent.ts

• Main agent implementation

• package.json

• Dependencies and scripts

• tsconfig.json

• TypeScript configuration

• agent.test.ts

• Test file template

Usage:

Copy template to your project

cp -r assets/agent-template/ /path/to/your/agent

Install dependencies

cd /path/to/your/agent npm install

Customize configuration in agent.ts

Implement your custom tools

Add your business logic

Run

npm start

Test

npm test

Development Workflow

1. Define Agent Purpose

Clearly articulate what the agent does:

• Domain/specialty

• Responsibilities

• Expected inputs/outputs

• Success criteria

2. Design Custom Tools

Identify what tools the agent needs:

• What external systems to integrate?

• What data processing is required?

• What validations are needed?

Use patterns from custom-tools.md.

3. Implement Agent

Start with the template in assets/agent-template/ :

• Configure system prompt

• Implement custom tools

• Add error handling

• Set up monitoring

4. Test Thoroughly

Follow testing strategy from testing-evaluation.md:

• Unit test custom tools

• Integration test agent behavior

• Create evaluation set

• Run regression tests

5. Deploy & Monitor

Set up production monitoring from monitoring.md:

• Structured logging

• Metrics tracking

• Alerting

• Dashboard

6. Iterate

Continuously improve based on:

• Production metrics

• User feedback

• Edge cases discovered

• Performance bottlenecks

Best Practices

Tool Development

• Single responsibility - One tool, one job

• Type everything - Use Zod for runtime + compile-time validation

• Handle errors gracefully - Distinguish recoverable from fatal

• Test independently - Validate tools before agent integration

Agent Architecture

• Clear system prompt - Define role, responsibilities, guidelines

• Appropriate permissions - Use bypassPermissions only in production

• Token management - Use 1M context model for long-running tasks

• State management - Pass context between multi-turn conversations

Testing

• Multiple levels - Unit, integration, evaluation sets

• Golden dataset - Known-good examples for regression

• Semantic similarity - Not exact string matching

• Automate in CI/CD - Run eval set on every change

Production

• Structured logging - JSON format with context

• Track metrics - Latency, success rate, cost, token usage

• Set up alerts - Error rate, latency, cost thresholds

• Monitor continuously - Real-time observability

Multi-Agent Systems

• Clear responsibilities - Each agent has specific role

• Fail gracefully - Handle agent failures

• Parallel when possible - Speed up with concurrency

• Version agents - Track which version produced results

Common Patterns

Pattern 1: Business Workflow Agent

Orchestrates business processes (intake, validation, routing).

Example: Customer intake agent that validates form data, checks for completeness, and routes to appropriate team.

See: examples.md - Example 1

Pattern 2: Domain Specialist Agent

Deep expertise in specific domain (design, finance, legal, technical).

Example: Interior design agent that analyzes floor plans, suggests modifications, and estimates costs.

See: examples.md - Example 5

Pattern 3: Integration Agent

Connects to and orchestrates external services and APIs.

Example: Onboarding agent that creates Stripe customer, sends welcome email, and posts to Slack.

See: examples.md - Example 4

Pattern 4: Analysis Agent

Processes data and generates insights.

Example: Data analysis agent that loads CSVs, calculates statistics, and identifies patterns.

See: examples.md - Example 3

Pattern 5: Multi-Agent Orchestrator

Coordinates multiple specialized agents for complex workflows.

Example: Project orchestrator that runs intake, architecture, compliance, and budget agents in sequence.

See: orchestration.md and examples.md - Example 6

Troubleshooting

Issue: Custom tools not being called

Solution: Ensure you're using async generator for prompt when using MCP:

async function* messages() { yield { type: "user", message: { role: "user", content: "Task" } }; }

query({ prompt: messages(), options: { mcpServers: { ... } } });

Issue: High token costs

Solutions:

• Use more specific system prompts

• Limit context with targeted tool outputs

• Cache expensive operations

• Use 1M context model for long conversations

Issue: Slow agent execution

Solutions:

• Profile tool execution times

• Optimize slow tools (caching, batching)

• Run independent operations in parallel

• Consider simpler prompts

Issue: Agent produces inconsistent results

Solutions:

• More specific system prompt

• Better tool descriptions

• Add validation tools

• Use evaluation sets to measure consistency

Issue: Tools return errors

Solutions:

• Add comprehensive error handling in tools

• Validate inputs before processing

• Return isError: false for recoverable errors

• Log errors for debugging

Resources

• TypeScript SDK Docs: https://platform.claude.com/docs/en/agent-sdk/typescript

• GitHub: https://github.com/anthropics/claude-agent-sdk-typescript

• Custom Tools Guide: https://platform.claude.com/docs/en/agent-sdk/custom-tools

• MCP Documentation: https://platform.claude.com/docs/en/agent-sdk/mcp

Version

Skill Version: 1.0.0 SDK Compatibility: @anthropic-ai/claude-agent-sdk latest Last Updated: 2026-01-12

Support

For agent development assistance:

• Review relevant reference documentation above

• Check examples for similar use cases

• Use the agent template as starting point

• Test thoroughly before production deployment