Claude Agent SDK 完整教程：工具系统、代理循环与可控执行实战

{
  name: 'read_file',
  description: '读取文本文件内容',
  inputSchema: {
    type: 'object',
    properties: {
      path: { type: 'string', description: '文件路径' }
    },
    required: ['path']
  },
  execute: async ({ path }) => {
    return { content: fs.readFileSync(path, 'utf-8') };
  }
}

// tools.ts
import fs from 'fs';
import path from 'path';

export const readFileTool = {
  name: 'read_file',
  description: '读取文本文件内容。只能读取 .md, .txt, .json 格式的文件。',
  inputSchema: {
    type: 'object',
    properties: {
      path: { 
        type: 'string', 
        description: '相对于项目根目录的文件路径' 
      }
    },
    required: ['path']
  },
  execute: async ({ path: filePath }: { path: string }) => {
    const allowedExtensions = ['.md', '.txt', '.json'];
    const ext = path.extname(filePath);
    
    if (!allowedExtensions.includes(ext)) {
      throw new Error(`不支持的文件类型: ${ext}`);
    }
    
    const fullPath = path.resolve(process.cwd(), filePath);
    const content = fs.readFileSync(fullPath, 'utf-8');
    
    return { 
      content, 
      size: content.length,
      lines: content.split('\n').length
    };
  }
};

export const listFilesTool = {
  name: 'list_files',
  description: '列出指定目录下的所有文件',
  inputSchema: {
    type: 'object',
    properties: {
      directory: { 
        type: 'string', 
        description: '目录路径' 
      },
      extension: {
        type: 'string',
        description: '文件扩展名筛选（如 .md）'
      }
    },
    required: ['directory']
  },
  execute: async ({ directory, extension }: { directory: string; extension?: string }) => {
    const dirPath = path.resolve(process.cwd(), directory);
    const files = fs.readdirSync(dirPath);
    
    const filtered = extension
      ? files.filter(f => f.endsWith(extension))
      : files;
    
    return { files: filtered, count: filtered.length };
  }
};

// agent.ts
import { Anthropic } from '@anthropic-ai/sdk';
import { readFileTool, listFilesTool } from './tools';

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

async function summarizeMarkdownFiles(directory: string) {
  const messages = [
    {
      role: 'user' as const,
      content: `请帮我分析 ${directory} 目录下的所有 Markdown 文件，并生成一份摘要报告。报告应包含：
      1. 文件列表
      2. 每个文件的核心内容（1-2 句话）
      3. 整体主题分析`
    }
  ];

  let continueLoop = true;
  const tools = [readFileTool, listFilesTool];
  
  while (continueLoop) {
    const response = await client.messages.create({
      model: 'claude-3-5-sonnet-20241022',
      max_tokens: 4096,
      tools,
      messages
    });

    console.log('Claude 回复:', response.content);

    // 检查是否有工具调用
    const toolUseBlock = response.content.find(
      block => block.type === 'tool_use'
    );

    if (toolUseBlock && toolUseBlock.type === 'tool_use') {
      // 执行工具
      const tool = tools.find(t => t.name === toolUseBlock.name);
      if (!tool) {
        throw new Error(`未找到工具: ${toolUseBlock.name}`);
      }

      console.log(`\n执行工具: ${tool.name}`, toolUseBlock.input);
      
      const result = await tool.execute(toolUseBlock.input as any);
      
      console.log('工具输出:', JSON.stringify(result, null, 2));

      // 将工具结果添加到对话
      messages.push({
        role: 'assistant',
        content: response.content
      });
      
      messages.push({
        role: 'user' as const,
        content: [
          {
            type: 'tool_result',
            tool_use_id: toolUseBlock.id,
            content: JSON.stringify(result)
          }
        ]
      });
    } else {
      // 没有工具调用，任务完成
      continueLoop = false;
      
      const textBlock = response.content.find(block => block.type === 'text');
      if (textBlock && textBlock.type === 'text') {
        console.log('\n\n=== 最终摘要 ===\n');
        console.log(textBlock.text);
      }
    }
  }
}

// 运行
summarizeMarkdownFiles('./docs')
  .then(() => console.log('\n任务完成'))
  .catch(err => console.error('错误:', err));

// code-review-agent.ts
import { Anthropic } from '@anthropic-ai/sdk';
import fs from 'fs';
import { exec } from 'child_process';
import { promisify } from 'util';

const execAsync = promisify(exec);

const tools = [
  {
    name: 'read_python_file',
    description: '读取 Python 文件内容进行分析',
    inputSchema: {
      type: 'object',
      properties: {
        path: { type: 'string' }
      },
      required: ['path']
    },
    execute: async ({ path }: { path: string }) => {
      const content = fs.readFileSync(path, 'utf-8');
      const lines = content.split('\n').length;
      return { content, lines };
    }
  },
  {
    name: 'run_pylint',
    description: '运行 pylint 静态代码检查工具',
    inputSchema: {
      type: 'object',
      properties: {
        path: { type: 'string' }
      },
      required: ['path']
    },
    execute: async ({ path }: { path: string }) => {
      try {
        const { stdout } = await execAsync(`pylint ${path} --output-format=json`);
        return { result: JSON.parse(stdout) };
      } catch (error: any) {
        // Pylint 返回非零退出码时
        return { result: JSON.parse(error.stdout || '[]') };
      }
    }
  }
];

async function reviewPythonCode(filePath: string) {
  const client = new Anthropic({
    apiKey: process.env.ANTHROPIC_API_KEY!
  });

  const messages = [
    {
      role: 'user' as const,
      content: `请审查 Python 文件 ${filePath}，重点关注：
      1. 代码风格和可读性
      2. 潜在的 bug 和逻辑错误
      3. 性能优化建议
      4. 安全漏洞（SQL 注入、XSS 等）
      
      请先运行 pylint 工具，然后结合工具输出和代码内容进行人工审查。
      最后生成一份结构化的审查报告。`
    }
  ];

  let continueLoop = true;

  while (continueLoop) {
    const response = await client.messages.create({
      model: 'claude-3-5-sonnet-20241022',
      max_tokens: 8192,
      tools,
      messages
    });

    const toolUseBlocks = response.content.filter(block => block.type === 'tool_use');

    if (toolUseBlocks.length > 0) {
      messages.push({ role: 'assistant', content: response.content });

      const toolResults = [];
      for (const toolUse of toolUseBlocks) {
        if (toolUse.type !== 'tool_use') continue;

        const tool = tools.find(t => t.name === toolUse.name);
        const result = await tool!.execute(toolUse.input as any);
        
        toolResults.push({
          type: 'tool_result' as const,
          tool_use_id: toolUse.id,
          content: JSON.stringify(result)
        });
      }

      messages.push({ role: 'user' as const, content: toolResults });
    } else {
      continueLoop = false;
      const textBlock = response.content.find(block => block.type === 'text');
      if (textBlock && textBlock.type === 'text') {
        console.log(textBlock.text);
      }
    }
  }
}

// 使用示例
reviewPythonCode('./example.py');