Claude Agent SDK Deep Dive — Xây dựng agent với TypeScript SDK

Claude Agent SDK là bộ công cụ chính thức từ Anthropic giúp bạn xây dựng các AI agent tự chủ — những hệ thống có khả năng lập kế hoạch, sử dụng tools, và hoàn thành tác vụ phức tạp qua nhiều bước. Bài viết này đi sâu vào kiến trúc, patterns và best practices khi xây dựng agent bằng TypeScript SDK.

Agent SDK là gì và khác gì API thông thường?

Khi sử dụng Claude API thông thường, bạn gửi một prompt và nhận một response — đó là mô hình request-response đơn giản. Agent SDK mở rộng khả năng này bằng cách cho phép Claude:

• Agentic loop: Tự động lặp lại quy trình suy nghĩ - hành động - quan sát cho đến khi hoàn thành mục tiêu
• Tool use: Gọi các functions/tools bạn định nghĩa để tương tác với thế giới bên ngoài
• Multi-turn reasoning: Duy trì context và suy luận qua nhiều lượt trao đổi
• Guardrails: Kiểm soát hành vi agent qua input/output validation
• Handoffs: Chuyển giao nhiệm vụ giữa các agent chuyên biệt

Cài đặt và cấu hình ban đầu

Bắt đầu bằng cách cài đặt Agent SDK và thiết lập project:

# Tạo project mới
mkdir my-claude-agent && cd my-claude-agent
npm init -y

# Cài đặt dependencies
npm install @anthropic-ai/claude-agent-sdk
npm install -D typescript @types/node tsx

# Khởi tạo TypeScript config
npx tsc --init

# Cấu hình environment
echo "ANTHROPIC_API_KEY=sk-ant-..." > .env

Xây dựng Agent đầu tiên

Một agent cơ bản gồm 3 thành phần: instructions (hướng dẫn), tools (công cụ), và execution logic (logic chạy):

// src/basic-agent.ts
import { Agent, tool } from '@anthropic-ai/claude-agent-sdk';

// Định nghĩa tool cho agent
const searchTool = tool({
  name: 'search_products',
  description: 'Tìm kiếm sản phẩm trong database theo tên hoặc danh mục',
  parameters: {
    type: 'object',
    properties: {
      query: { type: 'string', description: 'Từ khóa tìm kiếm' },
      category: { type: 'string', description: 'Danh mục sản phẩm' },
      max_results: { type: 'number', description: 'Số kết quả tối đa' }
    },
    required: ['query']
  },
  execute: async ({ query, category, max_results = 10 }) => {
    // Thực hiện tìm kiếm trong database
    const results = await db.products.search({
      query, category, limit: max_results
    });
    return JSON.stringify(results);
  }
});

// Tạo agent
const productAssistant = new Agent({
  name: 'Product Assistant',
  model: 'sonnet',
  instructions: `Bạn là trợ lý tư vấn sản phẩm. Nhiệm vụ:
  - Tìm kiếm sản phẩm phù hợp với yêu cầu khách hàng
  - So sánh các sản phẩm và đưa ra đề xuất
  - Trả lời bằng tiếng Việt, thân thiện và chuyên nghiệp`,
  tools: [searchTool]
});

// Chạy agent
const result = await productAssistant.run(
  'Tôi cần tìm laptop dưới 20 triệu cho sinh viên ngành IT'
);
console.log(result.output);

Tool Design Patterns

Tool là cầu nối giữa agent và thế giới bên ngoài. Thiết kế tool tốt quyết định hiệu quả của agent:

Pattern 1: Single-Responsibility Tool

Mỗi tool chỉ nên làm một việc duy nhất. Thay vì tạo một tool "quản lý đơn hàng" làm tất cả, hãy tách thành nhiều tool nhỏ:

// Tốt: mỗi tool một chức năng
const getOrder = tool({
  name: 'get_order',
  description: 'Lấy thông tin đơn hàng theo mã đơn',
  parameters: {
    type: 'object',
    properties: {
      order_id: { type: 'string' }
    },
    required: ['order_id']
  },
  execute: async ({ order_id }) => {
    return JSON.stringify(await db.orders.findById(order_id));
  }
});

const updateOrderStatus = tool({
  name: 'update_order_status',
  description: 'Cập nhật trạng thái đơn hàng',
  parameters: {
    type: 'object',
    properties: {
      order_id: { type: 'string' },
      status: {
        type: 'string',
        enum: ['pending', 'confirmed', 'shipping', 'delivered', 'cancelled']
      }
    },
    required: ['order_id', 'status']
  },
  execute: async ({ order_id, status }) => {
    return JSON.stringify(await db.orders.updateStatus(order_id, status));
  }
});

Pattern 2: Descriptive Tool Definitions

Mô tả tool càng chi tiết, Claude càng biết khi nào nên dùng và cách dùng đúng:

const analyzeSentiment = tool({
  name: 'analyze_customer_feedback',
  description: `Phân tích cảm xúc từ phản hồi của khách hàng.
  Sử dụng tool này khi:
  - Cần đánh giá mức độ hài lòng của khách
  - Cần phân loại phản hồi (tích cực/tiêu cực/trung tính)
  - Cần xác định các vấn đề cụ thể khách hàng đề cập

  KHÔNG sử dụng khi:
  - Phản hồi là câu hỏi đơn giản (dùng search thay thế)
  - Nội dung không phải phản hồi khách hàng`,
  parameters: {
    type: 'object',
    properties: {
      feedback_text: {
        type: 'string',
        description: 'Nội dung phản hồi gốc của khách hàng'
      },
      context: {
        type: 'string',
        description: 'Bối cảnh: đơn hàng, sản phẩm, hoặc dịch vụ liên quan'
      }
    },
    required: ['feedback_text']
  },
  execute: async ({ feedback_text, context }) => {
    // Implementation
  }
});

Guardrails — Kiểm soát hành vi Agent

Guardrails là cơ chế an toàn quan trọng, đặc biệt khi agent có quyền thực hiện các hành động có tác động thực (gửi email, thay đổi database, tạo đơn hàng):

Input Guardrails

Kiểm tra và validate input trước khi agent xử lý:

const inputGuardrail = {
  name: 'content_filter',
  execute: async (input: string) => {
    // Kiểm tra nội dung không phù hợp
    if (containsHarmfulContent(input)) {
      return {
        tripwire: true,
        message: 'Nội dung không phù hợp với chính sách sử dụng'
      };
    }
    // Kiểm tra prompt injection
    if (detectPromptInjection(input)) {
      return {
        tripwire: true,
        message: 'Phát hiện nỗ lực thao túng hệ thống'
      };
    }
    return { tripwire: false };
  }
};

Output Guardrails

Kiểm tra output trước khi trả về cho người dùng:

const outputGuardrail = {
  name: 'pii_filter',
  execute: async (output: string) => {
    // Kiểm tra thông tin cá nhân bị lộ
    if (containsPII(output)) {
      return {
        tripwire: true,
        message: 'Output chứa thông tin cá nhân cần được ẩn'
      };
    }
    return { tripwire: false };
  }
};

Multi-Agent Orchestration

Đối với hệ thống phức tạp, một agent đơn lẻ có thể không đủ. Agent SDK hỗ trợ orchestration nhiều agent chuyên biệt:

Handoff Pattern

Agent chính phân tích yêu cầu và chuyển giao cho agent chuyên biệt:

// Agent chuyên xử lý đơn hàng
const orderAgent = new Agent({
  name: 'Order Specialist',
  model: 'sonnet',
  instructions: 'Bạn chuyên xử lý các vấn đề về đơn hàng...',
  tools: [getOrder, updateOrderStatus, refundOrder]
});

// Agent chuyên tư vấn sản phẩm
const productAgent = new Agent({
  name: 'Product Advisor',
  model: 'sonnet',
  instructions: 'Bạn chuyên tư vấn sản phẩm phù hợp...',
  tools: [searchProducts, compareProducts, getReviews]
});

// Agent chính (triage)
const triageAgent = new Agent({
  name: 'Customer Service Triage',
  model: 'sonnet',
  instructions: `Bạn là agent phân loại yêu cầu khách hàng.
  - Nếu về đơn hàng: chuyển cho Order Specialist
  - Nếu cần tư vấn sản phẩm: chuyển cho Product Advisor
  - Nếu đơn giản: trả lời trực tiếp`,
  handoffs: [orderAgent, productAgent]
});

Error Handling và Retry Logic

Trong production, agent cần xử lý lỗi gracefully:

// Cấu hình retry cho tool execution
const robustTool = tool({
  name: 'fetch_external_data',
  description: 'Lấy dữ liệu từ API bên ngoài',
  parameters: { /* ... */ },
  execute: async (params) => {
    const maxRetries = 3;
    let lastError;

    for (let attempt = 1; attempt <= maxRetries; attempt++) {
      try {
        const data = await externalAPI.fetch(params);
        return JSON.stringify(data);
      } catch (error) {
        lastError = error;
        if (attempt < maxRetries) {
          // Exponential backoff
          await sleep(Math.pow(2, attempt) * 1000);
        }
      }
    }

    // Trả về lỗi thân thiện thay vì throw
    return JSON.stringify({
      error: true,
      message: `Không thể lấy dữ liệu sau ${maxRetries} lần thử.
                Vui lòng thử lại sau.`,
      details: lastError.message
    });
  }
});

Streaming và Real-time Output

Agent SDK hỗ trợ streaming để hiển thị output theo thời gian thực, đặc biệt quan trọng cho UX khi agent thực hiện tác vụ dài:

// Streaming output từ agent
const stream = await agent.stream(
  'Phân tích doanh thu Q4/2024 và tạo báo cáo chi tiết'
);

for await (const event of stream) {
  switch (event.type) {
    case 'text':
      process.stdout.write(event.content);
      break;
    case 'tool_call':
      console.log(`[Đang sử dụng: ${event.tool_name}]`);
      break;
    case 'tool_result':
      console.log(`[Kết quả: ${event.tool_name} hoàn thành]`);
      break;
    case 'error':
      console.error(`[Lỗi: ${event.message}]`);
      break;
  }
}

Testing Agent

Agent cần được test kỹ lưỡng trước khi deploy. Các chiến lược testing:

Unit Testing cho Tools

// tests/tools.test.ts
import { describe, it, expect } from 'vitest';

describe('searchProducts tool', () => {
  it('should return results for valid query', async () => {
    const result = await searchTool.execute({
      query: 'laptop', max_results: 5
    });
    const parsed = JSON.parse(result);
    expect(parsed).toHaveLength(5);
    expect(parsed[0]).toHaveProperty('name');
    expect(parsed[0]).toHaveProperty('price');
  });

  it('should handle empty results gracefully', async () => {
    const result = await searchTool.execute({
      query: 'nonexistent_product_xyz'
    });
    const parsed = JSON.parse(result);
    expect(parsed).toHaveLength(0);
  });

  it('should respect max_results limit', async () => {
    const result = await searchTool.execute({
      query: 'phone', max_results: 3
    });
    const parsed = JSON.parse(result);
    expect(parsed.length).toBeLessThanOrEqual(3);
  });
});

Integration Testing cho Agent

Test agent với các scenarios thực tế, kiểm tra chuỗi hành động chứ không chỉ từng tool riêng lẻ. Đảm bảo agent chọn đúng tool cho đúng tình huống, xử lý edge cases tốt, và output đúng format mong muốn.

Performance Optimization

Để agent hoạt động nhanh và tiết kiệm chi phí:

• Chọn model phù hợp: Dùng Haiku cho triage/routing, Sonnet cho tác vụ chính, Opus cho suy luận phức tạp
• Giới hạn số lượt loop: Đặt max_turns để tránh agent chạy vô hạn
• Cache tool results: Cache kết quả của tools không thay đổi thường xuyên
• Parallel tool calls: Khi có nhiều tool calls độc lập, chạy song song thay vì tuần tự
• Tối ưu instructions: Instructions ngắn gọn và rõ ràng giúp agent quyết định nhanh hơn

Deploy Agent lên Production

Khi agent đã test xong, triển khai lên production với các best practices:

• Sử dụng environment variables cho API keys và cấu hình
• Thiết lập rate limiting để kiểm soát chi phí API
• Logging đầy đủ: ghi lại mọi tool calls, decisions và errors
• Monitoring: theo dõi latency, success rate, và cost per interaction
• Gradual rollout: bắt đầu với nhóm user nhỏ trước khi mở rộng

Bước tiếp theo

Bạn đã nắm được cách xây dựng agent với Claude Agent SDK. Bắt đầu từ agent đơn giản với 2-3 tools, test kỹ, rồi dần mở rộng. Khám phá thêm các hướng dẫn API nâng cao tại Thư viện Nâng cao.