Claude Agent SDK Complete Tutorial: Tool System, Agent Loop, and Controllable Execution in Action

{
  name: 'read_file',
  description: 'Reads text file content',
  inputSchema: {
    type: 'object',
    properties: {
      path: { type: 'string', description: 'File path' }
    },
    required: ['path']
  },
  execute: async ({ path }) => {
    return { content: fs.readFileSync(path, 'utf-8') };
  }
}

# Using npm
npm install @anthropic-ai/sdk

# Or using bun (faster)
bun add @anthropic-ai/sdk

# Verify installation
node -e "console.log(require('@anthropic-ai/sdk').VERSION)"

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

# Or set environment variable
export ANTHROPIC_API_KEY="your_api_key_here"

# Create test documents
mkdir docs
echo "# Document 1\nThis is test content." > docs/file1.md
echo "# Document 2\nAnother test." > docs/file2.md

# Run Agent
npx ts-node agent.ts

interface ToolPolicy {
  allowedTools: string[];        // Whitelist of allowed tool names
  allowedPaths: string[];        // Whitelist of allowed paths
  allowedCommands: string[];     // Whitelist of allowed commands
  confirmRequired: string[];     // Tools requiring user confirmation
  maxFileSize: number;           // File size limit (bytes)
  timeout: number;               // Tool execution timeout (ms)
}

const productionPolicy: ToolPolicy = {
  allowedTools: ['read_file', 'list_files', 'grep'],
  allowedPaths: ['./src', './docs', './tests'],
  allowedCommands: ['git', 'npm', 'node'],
  confirmRequired: ['write_file', 'delete_file', 'exec'],
  maxFileSize: 1024 * 1024 * 5,  // 5MB
  timeout: 30000  // 30 seconds
};

function applyToolPolicy(tool: any, policy: ToolPolicy) {
  return {
    ...tool,
    execute: async (input: any) => {
      // 1. Check if tool is in whitelist
      if (!policy.allowedTools.includes(tool.name)) {
        throw new Error(`Tool ${tool.name} is not whitelisted`);
      }

      // 2. Path check
      if (input.path) {
        const isAllowed = policy.allowedPaths.some(
          allowed => input.path.startsWith(allowed)
        );
        if (!isAllowed) {
          throw new Error(`Path ${input.path} is not in allowed range`);
        }
      }

      // 3. File size check
      if (input.path && fs.existsSync(input.path)) {
        const stats = fs.statSync(input.path);
        if (stats.size > policy.maxFileSize) {
          throw new Error(`File too large: ${stats.size} bytes`);
        }
      }

      // 4. Timeout control
      const timeoutPromise = new Promise((_, reject) =>
        setTimeout(() => reject(new Error('Tool execution timeout')), policy.timeout)
      );

      return Promise.race([
        tool.execute(input),
        timeoutPromise
      ]);
    }
  };
}

// Usage
const safeTools = tools.map(t => applyToolPolicy(t, productionPolicy));

// ❌ Poor tool description
{
  name: 'file_tool',
  description: 'File operations'  // Too vague
}

// ✅ Excellent tool description
{
  name: 'read_file',
  description: 'Reads the complete content of a text file. Supports .txt, .md, .json, .yaml formats. Returns file content string and metadata (lines, size).'
}

// Explicitly request tool usage in prompt
const messages = [{
  role: 'user',
  content: `Please use the read_file tool to read ${filePath}, do not guess the content.`
}];

interface Checkpoint {
  step: number;
  processedFiles: string[];
  results: any[];
  timestamp: number;
}

async function processWithCheckpoint(files: string[]) {
  const checkpointFile = './checkpoint.json';
  
  // Restore checkpoint
  let checkpoint: Checkpoint = fs.existsSync(checkpointFile)
    ? JSON.parse(fs.readFileSync(checkpointFile, 'utf-8'))
    : { step: 0, processedFiles: [], results: [], timestamp: Date.now() };

  for (let i = checkpoint.step; i < files.length; i++) {
    try {
      const result = await processFile(files[i]);
      checkpoint.processedFiles.push(files[i]);
      checkpoint.results.push(result);
      checkpoint.step = i + 1;
      
      // Save every 5 files
      if (i % 5 === 0) {
        fs.writeFileSync(checkpointFile, JSON.stringify(checkpoint));
      }
    } catch (error) {
      console.error(`Failed to process ${files[i]}:`, error);
      fs.writeFileSync(checkpointFile, JSON.stringify(checkpoint));
      throw error;
    }
  }

  // Delete checkpoint upon completion
  fs.unlinkSync(checkpointFile);
  return checkpoint.results;
}

async function runWithVerification(task: string) {
  const messages = [
    { role: 'user' as const, content: task }
  ];

  let result;
  let verified = false;
  let attempts = 0;

  while (!verified && attempts < 3) {
    result = await runAgent(messages);
    
    // Verify output
    if (result.includes('TODO') || result.length < 100) {
      messages.push({
        role: 'user' as const,
        content: 'Output incomplete, please provide a more detailed analysis.'
      });
      attempts++;
    } else {
      verified = true;
    }
  }

  return result;
}

// 1. Limit context length
function trimContext(messages: any[], maxTokens = 8000) {
  // Keep last N turns
  return messages.slice(-10);
}

// 2. Compress tool output
function compressToolResult(result: any) {
  if (typeof result === 'string' && result.length > 2000) {
    return result.slice(0, 1000) + '\n...[omitted ' + (result.length - 1000) + ' chars]...';
  }
  return result;
}

// 3. Use smaller models for simple tasks
const model = task.complexity === 'high' 
  ? 'claude-3-5-sonnet-20241022'
  : 'claude-3-haiku-20240307';

async function interactiveAgent() {
  const readline = require('readline').createInterface({
    input: process.stdin,
    output: process.stdout
  });

  const askUser = (question: string): Promise<string> => {
    return new Promise(resolve => {
      readline.question(question, resolve);
    });
  };

  // Called within tool
  const confirmTool = {
    name: 'confirm_action',
    description: 'Requests user confirmation for sensitive operations',
    inputSchema: {
      type: 'object',
      properties: {
        action: { type: 'string' },
        details: { type: 'string' }
      }
    },
    execute: async ({ action, details }: any) => {
      const answer = await askUser(
        `\nConfirm execution: ${action}?\nDetails: ${details}\n(y/n): `
      );
      return { confirmed: answer.toLowerCase() === 'y' };
    }
  };
}

class AgentLogger {
  private logs: any[] = [];

  logToolCall(toolName: string, input: any, output: any, duration: number) {
    this.logs.push({
      type: 'tool_call',
      toolName,
      input,
      output,
      duration,
      timestamp: Date.now()
    });
  }

  logError(error: Error, context: any) {
    this.logs.push({
      type: 'error',
      message: error.message,
      stack: error.stack,
      context,
      timestamp: Date.now()
    });
  }

  exportMetrics() {
    return {
      totalToolCalls: this.logs.filter(l => l.type === 'tool_call').length,
      averageDuration: this.logs
        .filter(l => l.type === 'tool_call')
        .reduce((sum, l) => sum + l.duration, 0) / this.logs.length,
      errors: this.logs.filter(l => l.type === 'error').length
    };
  }
}

async function parallelProcessing(tasks: string[]) {
  const subAgents = tasks.map(task => 
    createSubAgent({ 
      task, 
      maxTokens: 2000,
      isolatedContext: true 
    })
  );

  const results = await Promise.all(
    subAgents.map(agent => agent.run())
  );

  return aggregateResults(results);
}