Why Build Multi-Tool AI Agents with Claude API?

In today's fast-paced development world, single-purpose AI tools fall short. Developers need autonomous agents that intelligently chain multiple capabilities—like searching the web for data, executing code for computations, and managing files—all in one seamless workflow.

Claude's Messages API, powered by models like Claude 3.5 Sonnet, excels at this with native multi-tool support. It allows parallel tool calls, precise JSON-structured outputs, and reliable reasoning. This tutorial walks you through building such an agent in TypeScript using the official Anthropic SDK.

Real-world use cases:

• Automate research reports: Search web → Analyze data → Generate CSV.
• CI/CD bots: Check code → Run tests → Update files.
• Data pipelines: Fetch external data → Compute stats → Save results.

By the end, you'll have a production-ready agent template. Let's dive in.

Prerequisites

• Node.js 18+ and npm/yarn.
• TypeScript knowledge.
• Anthropic API key (get one at console.anthropic.com).
• Optional: SerpAPI key for real web search (free tier available).

Step 1: Project Setup

Create a new directory and initialize:

mkdir claude-multi-agent
cd claude-multi-agent
npm init -y
npm install @anthropic-ai/sdk typescript ts-node @types/node
npm install -D @types/node
npx tsc --init

Update tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  }
}

Create src/agent.ts for our code.

Step 2: Initialize the Anthropic Client

import { Anthropic } from '@anthropic-ai/sdk';

const client = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY!,
});

const MODEL = 'claude-3-5-sonnet-20241022'; // Latest with top tool use

Set your API key: export ANTHROPIC_API_KEY=sk-....

Step 3: Define Your Tools

Claude tools are JSON Schema-defined functions. We'll create three:

1. web_search: Fetches results (uses SerpAPI mockable).
2. calculator: Safe math execution.
3. file_ops: Read/write files.

import * as fs from 'fs/promises';
import * as path from 'path';

type ToolResult = { tool_use_id: string; content: string };

type SerpAPIResult = { organic_results: Array<{title: string; snippet: string; link: string}> };

const tools = [
  {
    name: 'web_search',
    description: 'Search the web for current information. Use for facts, news, or research.',
    inputSchema: {
      type: 'object',
      properties: { query: { type: 'string', description: 'Search query' } },
      required: ['query'],
    },
  },
  {
    name: 'calculator',
    description: 'Execute safe mathematical expressions. Supports +, -, *, /, **, sin, cos, etc.',
    inputSchema: {
      type: 'object',
      properties: { expression: { type: 'string', description: 'Math expression e.g. "2+3*4"' } },
      required: ['expression'],
    },
  },
  {
    name: 'read_file',
    description: 'Read content from a local file.',
    inputSchema: {
      type: 'object',
      properties: { filepath: { type: 'string', description: 'Absolute or relative path' } },
      required: ['filepath'],
    },
  },
  {
    name: 'write_file',
    description: 'Write content to a local file. Overwrites if exists.',
    inputSchema: {
      type: 'object',
      properties: {
        filepath: { type: 'string', description: 'Path to write' },
        content: { type: 'string', description: 'Content to write' },
      },
      required: ['filepath', 'content'],
    },
  },
] as const;

Step 4: Implement Tool Executors

Each tool needs a handler. Parallel execution is key for efficiency.

async function executeTool(toolName: string, toolUseId: string, args: any): Promise<ToolResult> {
  try {
    switch (toolName) {
      case 'web_search':
        // Mock for tutorial; replace with real SerpAPI
        const query = args.query;
        // Real: const res = await fetch(`https://serpapi.com/search?api_key=${process.env.SERPAPI_KEY}&q=${encodeURIComponent(query)}`, { method: 'GET' });
        // const data: SerpAPIResult = await res.json();
        const mockResults = [
          { title: 'Mock Result 1', snippet: `Info on ${query}`, link: 'https://example.com' },
        ];
        return {
          tool_use_id: toolUseId,
          content: JSON.stringify(mockResults),
        };

      case 'calculator':
        // Safe eval alternative (use mathjs in prod)
        const result = Function('expr', `return ${args.expression}`)('0'); // Simplified; use vm2 for safety
        return {
          tool_use_id: toolUseId,
          content: `Result: ${result}`,
        };

      case 'read_file':
        const fileContent = await fs.readFile(args.filepath, 'utf-8');
        return {
          tool_use_id: toolUseId,
          content: fileContent,
        };

      case 'write_file':
        await fs.writeFile(args.filepath, args.content, 'utf-8');
        return {
          tool_use_id: toolUseId,
          content: `Wrote to ${args.filepath}`,
        };

      default:
        throw new Error(`Unknown tool: ${toolName}`);
    }
  } catch (error) {
    return {
      tool_use_id: toolUseId,
      content: `Error: ${(error as Error).message}`,
    };
  }
}

Pro tip: In production, sandbox code exec (e.g., isolated Docker) and rate-limit tools.

Step 5: The Agent Loop

Core logic: Send user message → Check for tools → Execute → Append results → Repeat until final answer.

interface Message {
  role: 'user' | 'assistant';
  content: string | Array<{type: 'text'; text: string} | {type: 'tool_use'; id: string; name: string; input: object}>;
}

type AgentResponse = { finalAnswer: string; toolCalls?: Array<any> };

export async function runAgent(prompt: string): Promise<AgentResponse> {
  let messages: Message[] = [{ role: 'user', content: prompt }];

  const systemPrompt = `You are a helpful agent. Use tools to gather info and solve tasks. 
  Think step-by-step. When done, give a clear final answer without tools.`;

  while (true) {
    const res = await client.messages.create({
      model: MODEL,
      max_tokens: 1024,
      system: systemPrompt,
      messages,
      tools,
    });

    if (!res.content || res.stop_reason === 'end_turn') {
      break;
    }

    const assistantMsg: Message = { role: 'assistant', content: [] };
    let hasTools = false;

    for (const block of res.content) {
      if (block.type === 'text') {
        (assistantMsg.content as any[]).push({ type: 'text', text: block.text });
      } else if (block.type === 'tool_use') {
        hasTools = true;
        (assistantMsg.content as any[]).push({
          type: 'tool_use',
          id: block.id,
          name: block.name,
          input: block.input,
        });
      }
    }

    messages.push(assistantMsg);

    if (!hasTools || res.stop_reason !== 'tool_use') {
      break;
    }

    // Execute all tool calls in parallel
    const toolResults: ToolResult[] = [];
    for (const block of res.content) {
      if (block.type === 'tool_use') {
        const result = await executeTool(block.name, block.id, block.input);
        toolResults.push(result);
      }
    }

    // Append tool results
    const toolMsg: Message = {
      role: 'user',
      content: toolResults.map(r => ({
        type: 'tool_result',
        tool_use_id: r.tool_use_id,
        content: r.content,
      })),
    };
    messages.push(toolMsg);
  }

  const finalMsg = messages[messages.length - 1];
  const finalAnswer = Array.isArray(finalMsg.content)
    ? (finalMsg.content as any[]).find((b: any) => b.type === 'text')?.text || 'No response'
    : finalMsg.content as string;

  return { finalAnswer };
}

Step 6: Test Your Agent

Add a run script to src/index.ts:

(async () => {
  const prompt = 'Research latest Node.js version, calculate 1.21 * its minor, save to data.txt as "vX.Y: result=Z"';
  const result = await runAgent(prompt);
  console.log('Final Answer:', result.finalAnswer);
})();

Run: npx ts-node src/index.ts

Expected flow:

• Claude calls web_search("latest Node.js version")
• Gets mock/real results (e.g., v22.5)
• Calls calculator("1.21 * 22.5") → ~27.225
• Calls write_file("data.txt", "v22.5: result=27.225")
• Outputs summary.

Advanced Tips & Best Practices

Prompt Engineering

• Chain-of-Thought: "Plan steps, then act."
• Tool Selection: Describe tools clearly; Claude picks best.
• Max Loops: Add counter to prevent infinite loops (e.g., 10 max).

Error Handling

• Always return tool results, even errors.
• Use stop_sequences for custom stops.

Scaling

• Parallelism: Claude handles 10+ tools natively.
• State Management: Persist messages array to DB for long sessions.
• Integrations: Hook into n8n/Zapier via webhooks.

Performance

• Claude 3.5 Sonnet: 2k tokens/sec, 200k context.
• Cache tool results.
• Use Haiku for cheap pre-processing.

Security

• Validate/sanitize tool inputs.
• API keys in env vars.
• Sandbox file ops to dirs.

Common Pitfalls

• JSON Parsing: Claude outputs valid JSON; use inputSchema.
• Token Limits: Monitor usage; truncate history if needed.
• Mock vs Real: Swap mocks for prod APIs.

Conclusion

You've now built a robust multi-tool agent with Claude API! This TypeScript blueprint solves real dev problems, from automation to analysis. Extend it with MCP servers for more tools or deploy as a CLI with Claude Code.

Next steps:

• Add RAG with vector DB tools.
• Build teams of agents.
• Check Anthropic docs for updates.

Fork on GitHub, experiment, and share your agents in Claude Directory comments!

Word count: ~1450