Building an AI Coding Agent from Scratch with Claude Agent SDK

You've been using Claude as a chatbot — paste code, get a reply, paste again. That works. But there's a different mode entirely: give Claude a set of tools and a goal, and let it figure out the steps itself.

That's what an agent is. Not a smarter autocomplete — a loop that reads files, runs checks, makes decisions, and calls your code until the job is done.

In this article, I'll walk through building a TypeScript code review agent using Anthropic's SDK. It will autonomously scan your project, find issues, and output a structured report — without you prompting it at each step.

What Makes Something an "Agent"

A regular API call is stateless: you send a prompt, you get a response. An agent is different in three ways:

Tools — it can call functions you define (read a file, run a command, query an API)
A loop — after using a tool, it sees the result and decides what to do next
A goal — it keeps going until it reaches a terminal state, not until the context window fills up

The Anthropic SDK exposes this through tool_use content blocks. Claude returns a tool call, you execute it, you append the result, and Claude continues. You own the loop.

What We're Building

A CLI agent that takes a TypeScript project path and produces a code review report:

$ npx ts-node agent.ts ./src

🔍 Reading project structure...
📂 Found 12 TypeScript files
🔎 Checking src/services/UserService.ts...
⚠️  Found 3 issues in src/services/UserService.ts
✅ No issues in src/repositories/UserRepo.ts
...
📋 Report saved to review-report.md

The agent decides which files to read, in what order, and how deep to go — we just give it the tools and the goal.

Project Setup

mkdir ts-review-agent && cd ts-review-agent
npm init -y
npm install @anthropic-ai/sdk
npm install -D typescript ts-node @types/node
npx tsc --init --strict --module commonjs --target es2020

Create agent.ts:

import Anthropic from '@anthropic-ai/sdk';
import * as fs from 'fs';
import * as path from 'path';

const client = new Anthropic(); // reads ANTHROPIC_API_KEY from env

Defining the Tools

The agent needs three capabilities: list files, read a file, and write the final report.

const tools: Anthropic.Tool[] = [
  {
    name: 'list_files',
    description: 'List all TypeScript files in a directory recursively',
    input_schema: {
      type: 'object',
      properties: {
        directory: { type: 'string', description: 'Absolute or relative path to directory' }
      },
      required: ['directory']
    }
  },
  {
    name: 'read_file',
    description: 'Read the contents of a TypeScript file',
    input_schema: {
      type: 'object',
      properties: {
        file_path: { type: 'string', description: 'Path to the file to read' }
      },
      required: ['file_path']
    }
  },
  {
    name: 'write_report',
    description: 'Write the final code review report to a markdown file',
    input_schema: {
      type: 'object',
      properties: {
        content: { type: 'string', description: 'Markdown content of the report' },
        output_path: { type: 'string', description: 'Where to save the report' }
      },
      required: ['content', 'output_path']
    }
  }
];

Tool definitions are just JSON Schema — Claude reads the description to understand when and how to use each one. The descriptions matter more than you'd think.

Implementing the Tool Executor

type ToolInput = Record<string, string>;

function executeTool(name: string, input: ToolInput): string {
  switch (name) {
    case 'list_files': {
      const dir = input.directory;
      const files: string[] = [];
      function walk(current: string) {
        for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
          const full = path.join(current, entry.name);
          if (entry.isDirectory() && !entry.name.startsWith('.') && entry.name !== 'node_modules') {
            walk(full);
          } else if (entry.isFile() && entry.name.endsWith('.ts') && !entry.name.endsWith('.d.ts')) {
            files.push(full);
          }
        }
      }
      walk(dir);
      return JSON.stringify(files);
    }

    case 'read_file': {
      try {
        return fs.readFileSync(input.file_path, 'utf-8');
      } catch {
        return `Error: could not read ${input.file_path}`;
      }
    }

    case 'write_report': {
      fs.writeFileSync(input.output_path, input.content, 'utf-8');
      return `Report written to ${input.output_path}`;
    }

    default:
      return `Unknown tool: ${name}`;
  }
}

This is intentionally simple. In production you'd add path sanitization, size limits, and timeouts — but the pattern is the same.

The Agent Loop

This is the core. Everything else is setup; this is where the agent runs.

async function runAgent(projectPath: string): Promise<void> {
  const messages: Anthropic.MessageParam[] = [
    {
      role: 'user',
      content: `You are a TypeScript code reviewer. Review the project at "${projectPath}".

Steps:
1. List all TypeScript files in the project
2. Read and review each file for: type safety issues, unused variables, any-typed params, missing error handling, and obvious logic bugs
3. Write a structured markdown report with findings, severity (error/warning/info), and suggested fixes

Be thorough but focus on real issues, not style preferences.`
    }
  ];

  console.log('🤖 Agent starting...
');

  while (true) {
    const response = await client.messages.create({
      model: 'claude-opus-4-7',
      max_tokens: 4096,
      tools,
      messages
    });

    // Add assistant response to history
    messages.push({ role: 'assistant', content: response.content });

    // Check if we're done
    if (response.stop_reason === 'end_turn') {
      console.log('
✅ Agent finished.');
      break;
    }

    // Process tool calls
    if (response.stop_reason === 'tool_use') {
      const toolResults: Anthropic.ToolResultBlockParam[] = [];

      for (const block of response.content) {
        if (block.type === 'tool_use') {
          console.log(`🔧 ${block.name}(${JSON.stringify(block.input).slice(0, 60)}...)`);
          const result = executeTool(block.name, block.input as ToolInput);
          toolResults.push({
            type: 'tool_result',
            tool_use_id: block.id,
            content: result
          });
        } else if (block.type === 'text' && block.text) {
          console.log(`💭 ${block.text.slice(0, 80)}...`);
        }
      }

      // Append tool results and continue
      messages.push({ role: 'user', content: toolResults });
    }
  }
}

// Entry point
const targetPath = process.argv[2] || '.';
runAgent(path.resolve(targetPath)).catch(console.error);

The loop is simple: send messages → get response → if tool calls, execute them and append results → repeat until end_turn.

Running It

export ANTHROPIC_API_KEY=your_key_here
npx ts-node agent.ts ./src

Output (truncated):

🤖 Agent starting...

🔧 list_files({"directory":"/Users/alex/project/src"}...)
🔧 read_file({"file_path":"/Users/alex/project/src/services/AuthService.ts"}...)
💭 Reviewing AuthService.ts — found potential issues with token expiry...
🔧 read_file({"file_path":"/Users/alex/project/src/middleware/auth.ts"}...)
🔧 write_report({"content":"# Code Review Report

## Summary...","output_p}...)

✅ Agent finished.

The agent reads files in an order it decides, cross-references related files, and writes a cohesive report — without you prompting each step.

Patterns That Matter in Production

1. Token budget awareness. Each iteration appends to messages. For large codebases, you'll hit limits fast. Either batch files (give the agent 5 files per run) or summarize intermediate results.

// Rough token estimate before each request
const estimatedTokens = JSON.stringify(messages).length / 4;
if (estimatedTokens > 150_000) {
  // Summarize or paginate
}

2. Max iterations guard. Agents can loop unexpectedly. Add a hard limit:

let iterations = 0;
while (iterations++ < 20) { ... }

3. Structured tool results. Return JSON from tools, not prose. Claude parses structured data more reliably than free text.

4. System prompt for persona. Move the role description out of the user message into a system parameter — it's more robust and doesn't count against your conversation history structure.

Key Takeaways

An agent is just a loop: model → tool calls → results → model, until stop_reason === 'end_turn'
Tool descriptions are part of your prompt — write them like documentation
You own the loop, which means you control retries, limits, and error handling
The Anthropic SDK exposes everything you need — no framework required for basic agents
Start with 2-3 well-defined tools and expand; generic "execute_code" tools cause unpredictable behavior

The full code for this agent is ~120 lines of TypeScript. The complexity in real agents comes from state management, error recovery, and tool design — not from the loop itself.

Follow me on Twitter @Alex_Rogov_js for more AI + Architecture content. If you found this useful, check out my other articles on AI-friendly TypeScript project structure and what I put in every CLAUDE.md.

Originally published on my Hashnode blog. Follow me for more AI + Architecture content.

推荐订阅源

DEV Community