Building Your First AI Agent with Claude: Step by Step

npm install @anthropic-ai/sdk

import Anthropic from '@anthropic-ai/sdk'
 
const client = new Anthropic()
 
const tools: Anthropic.Tool[] = [
  {
    name: 'search_web',
    description: 'Search the web for information on a topic. Returns a list of relevant results with titles and snippets.',
    input_schema: {
      type: 'object',
      properties: {
        query: {
          type: 'string',
          description: 'The search query',
        },
        num_results: {
          type: 'number',
          description: 'Number of results to return (1-10)',
          default: 5,
        },
      },
      required: ['query'],
    },
  },
  {
    name: 'read_page',
    description: 'Read the full content of a web page given its URL.',
    input_schema: {
      type: 'object',
      properties: {
        url: {
          type: 'string',
          description: 'The URL to read',
        },
      },
      required: ['url'],
    },
  },
  {
    name: 'save_research',
    description: 'Save the final research brief to a file.',
    input_schema: {
      type: 'object',
      properties: {
        title: { type: 'string' },
        summary: { type: 'string' },
        key_points: {
          type: 'array',
          items: { type: 'string' },
        },
        sources: {
          type: 'array',
          items: { type: 'string' },
        },
      },
      required: ['title', 'summary', 'key_points', 'sources'],
    },
  },
]

import * as fs from 'fs'
 
// Mock search — in production, use Brave Search API, Tavily, or SerpAPI
function searchWeb(query: string, numResults: number = 5): string {
  const mockResults = [
    {
      title: `${query} — Complete Guide 2025`,
      url: `https://example.com/guide-${query.toLowerCase().replace(/\s+/g, '-')}`,
      snippet: `Comprehensive overview of ${query}. Learn the fundamentals, best practices, and advanced techniques...`,
    },
    {
      title: `Best practices for ${query}`,
      url: `https://docs.example.com/${query.toLowerCase()}`,
      snippet: `Official documentation covering all aspects of ${query} with code examples...`,
    },
    {
      title: `${query} in 2025: What you need to know`,
      url: `https://blog.example.com/${query.toLowerCase()}-2025`,
      snippet: `The latest developments in ${query}. Updated for 2025 with new features and patterns...`,
    },
  ]
 
  return JSON.stringify(mockResults.slice(0, numResults))
}
 
function readPage(url: string): string {
  // Mock page content — in production, use a headless browser or Firecrawl
  return `Content from ${url}:\n\nThis page contains detailed information about the topic.
  Key points include: the fundamentals, advanced usage, and real-world examples.
  The author recommends starting with the basics before moving to advanced concepts.`
}
 
function saveResearch(data: {
  title: string
  summary: string
  key_points: string[]
  sources: string[]
}): string {
  const content = `# ${data.title}\n\n## Summary\n${data.summary}\n\n## Key Points\n${data.key_points.map((p) => `- ${p}`).join('\n')}\n\n## Sources\n${data.sources.map((s) => `- ${s}`).join('\n')}`
 
  fs.writeFileSync('research-brief.md', content)
  return `Research brief saved to research-brief.md`
}
 
// Tool dispatcher
function executeTool(name: string, input: Record<string, any>): string {
  switch (name) {
    case 'search_web':
      return searchWeb(input.query, input.num_results)
    case 'read_page':
      return readPage(input.url)
    case 'save_research':
      return saveResearch(input)
    default:
      return `Unknown tool: ${name}`
  }
}

async function runResearchAgent(query: string): Promise<void> {
  console.log(`\n🔍 Starting research on: "${query}"\n`)
 
  const messages: Anthropic.MessageParam[] = [
    {
      role: 'user',
      content: `Research the following topic and create a comprehensive brief: "${query}".
      Use the search tool to find relevant sources, read the most promising ones,
      and then save a structured research brief with your findings.`,
    },
  ]
 
  let iteration = 0
  const MAX_ITERATIONS = 10
 
  while (iteration < MAX_ITERATIONS) {
    iteration++
    console.log(`\n--- Iteration ${iteration} ---`)
 
    const response = await client.messages.create({
      model: 'claude-opus-4-6',
      max_tokens: 4096,
      tools,
      messages,
    })
 
    console.log(`Stop reason: ${response.stop_reason}`)
 
    // Add assistant's response to the message history
    messages.push({ role: 'assistant', content: response.content })
 
    // If Claude is done, exit the loop
    if (response.stop_reason === 'end_turn') {
      console.log('\n✅ Agent completed task')
      // Extract and print the final text response
      const finalText = response.content
        .filter((block): block is Anthropic.TextBlock => block.type === 'text')
        .map((block) => block.text)
        .join('\n')
      if (finalText) console.log('\nFinal response:', finalText)
      break
    }
 
    // If Claude wants to use tools
    if (response.stop_reason === 'tool_use') {
      const toolResults: Anthropic.ToolResultBlockParam[] = []
 
      for (const block of response.content) {
        if (block.type === 'tool_use') {
          console.log(`\n🔧 Calling tool: ${block.name}`)
          console.log(`   Input: ${JSON.stringify(block.input)}`)
 
          const result = executeTool(block.name, block.input as Record<string, any>)
          console.log(`   Result: ${result.substring(0, 100)}...`)
 
          toolResults.push({
            type: 'tool_result',
            tool_use_id: block.id,
            content: result,
          })
        }
      }
 
      // Add tool results back to the conversation
      messages.push({ role: 'user', content: toolResults })
    }
  }
 
  if (iteration >= MAX_ITERATIONS) {
    console.log('\n⚠️ Reached maximum iterations')
  }
}
 
// Run the agent
runResearchAgent('AI agents with Claude')

npx ts-node agent.ts

const response = await client.messages.create({
  model: 'claude-opus-4-6',
  max_tokens: 4096,
  system: `You are a research assistant. Your job is to:
1. Search for information using the search_web tool
2. Read the most relevant pages using read_page
3. Synthesize the information into a structured brief
4. Always save your final brief using save_research
 
Be thorough but efficient. Read 2-3 sources before writing your summary.
Always cite your sources.`,
  tools,
  messages,
})

function executeTool(name: string, input: Record<string, any>): string {
  try {
    // ... tool execution
  } catch (error) {
    return `Error executing ${name}: ${error instanceof Error ? error.message : String(error)}`
  }
}