{"product_id":"claude-agent-sdk-deep-dive-xay-dựng-agent-với-typescript-sdk","title":"Claude Agent SDK Deep Dive — Xây dựng agent với TypeScript SDK","description":"\n\u003cp\u003eClaude 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.\u003c\/p\u003e\n\n\u003ch2\u003eAgent SDK là gì và khác gì API thông thường?\u003c\/h2\u003e\n\u003cp\u003eKhi 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:\u003c\/p\u003e\n\u003cul\u003e\n  \u003cli\u003e\n\u003cstrong\u003eAgentic loop:\u003c\/strong\u003e 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\u003c\/li\u003e\n  \u003cli\u003e\n\u003cstrong\u003eTool use:\u003c\/strong\u003e Gọi các functions\/tools bạn định nghĩa để tương tác với thế giới bên ngoài\u003c\/li\u003e\n  \u003cli\u003e\n\u003cstrong\u003eMulti-turn reasoning:\u003c\/strong\u003e Duy trì context và suy luận qua nhiều lượt trao đổi\u003c\/li\u003e\n  \u003cli\u003e\n\u003cstrong\u003eGuardrails:\u003c\/strong\u003e Kiểm soát hành vi agent qua input\/output validation\u003c\/li\u003e\n  \u003cli\u003e\n\u003cstrong\u003eHandoffs:\u003c\/strong\u003e Chuyển giao nhiệm vụ giữa các agent chuyên biệt\u003c\/li\u003e\n\u003c\/ul\u003e\n\n\u003ch2\u003eCài đặt và cấu hình ban đầu\u003c\/h2\u003e\n\u003cp\u003eBắt đầu bằng cách cài đặt Agent SDK và thiết lập project:\u003c\/p\u003e\n\u003cpre\u003e\u003ccode\u003e# Tạo project mới\nmkdir my-claude-agent \u0026amp;\u0026amp; cd my-claude-agent\nnpm init -y\n\n# Cài đặt dependencies\nnpm install @anthropic-ai\/claude-agent-sdk\nnpm install -D typescript @types\/node tsx\n\n# Khởi tạo TypeScript config\nnpx tsc --init\n\n# Cấu hình environment\necho \"ANTHROPIC_API_KEY=sk-ant-...\" \u0026gt; .env\u003c\/code\u003e\u003c\/pre\u003e\n\n\u003ch2\u003eXây dựng Agent đầu tiên\u003c\/h2\u003e\n\u003cp\u003eMộ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):\u003c\/p\u003e\n\u003cpre\u003e\u003ccode\u003e\/\/ src\/basic-agent.ts\nimport { Agent, tool } from '@anthropic-ai\/claude-agent-sdk';\n\n\/\/ Định nghĩa tool cho agent\nconst searchTool = tool({\n  name: 'search_products',\n  description: 'Tìm kiếm sản phẩm trong database theo tên hoặc danh mục',\n  parameters: {\n    type: 'object',\n    properties: {\n      query: { type: 'string', description: 'Từ khóa tìm kiếm' },\n      category: { type: 'string', description: 'Danh mục sản phẩm' },\n      max_results: { type: 'number', description: 'Số kết quả tối đa' }\n    },\n    required: ['query']\n  },\n  execute: async ({ query, category, max_results = 10 }) =\u0026gt; {\n    \/\/ Thực hiện tìm kiếm trong database\n    const results = await db.products.search({\n      query, category, limit: max_results\n    });\n    return JSON.stringify(results);\n  }\n});\n\n\/\/ Tạo agent\nconst productAssistant = new Agent({\n  name: 'Product Assistant',\n  model: 'sonnet',\n  instructions: `Bạn là trợ lý tư vấn sản phẩm. Nhiệm vụ:\n  - Tìm kiếm sản phẩm phù hợp với yêu cầu khách hàng\n  - So sánh các sản phẩm và đưa ra đề xuất\n  - Trả lời bằng tiếng Việt, thân thiện và chuyên nghiệp`,\n  tools: [searchTool]\n});\n\n\/\/ Chạy agent\nconst result = await productAssistant.run(\n  'Tôi cần tìm laptop dưới 20 triệu cho sinh viên ngành IT'\n);\nconsole.log(result.output);\u003c\/code\u003e\u003c\/pre\u003e\n\n\u003ch2\u003eTool Design Patterns\u003c\/h2\u003e\n\u003cp\u003eTool 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:\u003c\/p\u003e\n\n\u003ch3\u003ePattern 1: Single-Responsibility Tool\u003c\/h3\u003e\n\u003cp\u003eMỗ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ỏ:\u003c\/p\u003e\n\u003cpre\u003e\u003ccode\u003e\/\/ Tốt: mỗi tool một chức năng\nconst getOrder = tool({\n  name: 'get_order',\n  description: 'Lấy thông tin đơn hàng theo mã đơn',\n  parameters: {\n    type: 'object',\n    properties: {\n      order_id: { type: 'string' }\n    },\n    required: ['order_id']\n  },\n  execute: async ({ order_id }) =\u0026gt; {\n    return JSON.stringify(await db.orders.findById(order_id));\n  }\n});\n\nconst updateOrderStatus = tool({\n  name: 'update_order_status',\n  description: 'Cập nhật trạng thái đơn hàng',\n  parameters: {\n    type: 'object',\n    properties: {\n      order_id: { type: 'string' },\n      status: {\n        type: 'string',\n        enum: ['pending', 'confirmed', 'shipping', 'delivered', 'cancelled']\n      }\n    },\n    required: ['order_id', 'status']\n  },\n  execute: async ({ order_id, status }) =\u0026gt; {\n    return JSON.stringify(await db.orders.updateStatus(order_id, status));\n  }\n});\u003c\/code\u003e\u003c\/pre\u003e\n\n\u003ch3\u003ePattern 2: Descriptive Tool Definitions\u003c\/h3\u003e\n\u003cp\u003eMô 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:\u003c\/p\u003e\n\u003cpre\u003e\u003ccode\u003econst analyzeSentiment = tool({\n  name: 'analyze_customer_feedback',\n  description: `Phân tích cảm xúc từ phản hồi của khách hàng.\n  Sử dụng tool này khi:\n  - Cần đánh giá mức độ hài lòng của khách\n  - Cần phân loại phản hồi (tích cực\/tiêu cực\/trung tính)\n  - Cần xác định các vấn đề cụ thể khách hàng đề cập\n\n  KHÔNG sử dụng khi:\n  - Phản hồi là câu hỏi đơn giản (dùng search thay thế)\n  - Nội dung không phải phản hồi khách hàng`,\n  parameters: {\n    type: 'object',\n    properties: {\n      feedback_text: {\n        type: 'string',\n        description: 'Nội dung phản hồi gốc của khách hàng'\n      },\n      context: {\n        type: 'string',\n        description: 'Bối cảnh: đơn hàng, sản phẩm, hoặc dịch vụ liên quan'\n      }\n    },\n    required: ['feedback_text']\n  },\n  execute: async ({ feedback_text, context }) =\u0026gt; {\n    \/\/ Implementation\n  }\n});\u003c\/code\u003e\u003c\/pre\u003e\n\n\u003ch2\u003eGuardrails — Kiểm soát hành vi Agent\u003c\/h2\u003e\n\u003cp\u003eGuardrails 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):\u003c\/p\u003e\n\n\u003ch3\u003eInput Guardrails\u003c\/h3\u003e\n\u003cp\u003eKiểm tra và validate input trước khi agent xử lý:\u003c\/p\u003e\n\u003cpre\u003e\u003ccode\u003econst inputGuardrail = {\n  name: 'content_filter',\n  execute: async (input: string) =\u0026gt; {\n    \/\/ Kiểm tra nội dung không phù hợp\n    if (containsHarmfulContent(input)) {\n      return {\n        tripwire: true,\n        message: 'Nội dung không phù hợp với chính sách sử dụng'\n      };\n    }\n    \/\/ Kiểm tra prompt injection\n    if (detectPromptInjection(input)) {\n      return {\n        tripwire: true,\n        message: 'Phát hiện nỗ lực thao túng hệ thống'\n      };\n    }\n    return { tripwire: false };\n  }\n};\u003c\/code\u003e\u003c\/pre\u003e\n\n\u003ch3\u003eOutput Guardrails\u003c\/h3\u003e\n\u003cp\u003eKiểm tra output trước khi trả về cho người dùng:\u003c\/p\u003e\n\u003cpre\u003e\u003ccode\u003econst outputGuardrail = {\n  name: 'pii_filter',\n  execute: async (output: string) =\u0026gt; {\n    \/\/ Kiểm tra thông tin cá nhân bị lộ\n    if (containsPII(output)) {\n      return {\n        tripwire: true,\n        message: 'Output chứa thông tin cá nhân cần được ẩn'\n      };\n    }\n    return { tripwire: false };\n  }\n};\u003c\/code\u003e\u003c\/pre\u003e\n\n\u003ch2\u003eMulti-Agent Orchestration\u003c\/h2\u003e\n\u003cp\u003eĐố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:\u003c\/p\u003e\n\n\u003ch3\u003eHandoff Pattern\u003c\/h3\u003e\n\u003cp\u003eAgent chính phân tích yêu cầu và chuyển giao cho agent chuyên biệt:\u003c\/p\u003e\n\u003cpre\u003e\u003ccode\u003e\/\/ Agent chuyên xử lý đơn hàng\nconst orderAgent = new Agent({\n  name: 'Order Specialist',\n  model: 'sonnet',\n  instructions: 'Bạn chuyên xử lý các vấn đề về đơn hàng...',\n  tools: [getOrder, updateOrderStatus, refundOrder]\n});\n\n\/\/ Agent chuyên tư vấn sản phẩm\nconst productAgent = new Agent({\n  name: 'Product Advisor',\n  model: 'sonnet',\n  instructions: 'Bạn chuyên tư vấn sản phẩm phù hợp...',\n  tools: [searchProducts, compareProducts, getReviews]\n});\n\n\/\/ Agent chính (triage)\nconst triageAgent = new Agent({\n  name: 'Customer Service Triage',\n  model: 'sonnet',\n  instructions: `Bạn là agent phân loại yêu cầu khách hàng.\n  - Nếu về đơn hàng: chuyển cho Order Specialist\n  - Nếu cần tư vấn sản phẩm: chuyển cho Product Advisor\n  - Nếu đơn giản: trả lời trực tiếp`,\n  handoffs: [orderAgent, productAgent]\n});\u003c\/code\u003e\u003c\/pre\u003e\n\n\u003ch2\u003eError Handling và Retry Logic\u003c\/h2\u003e\n\u003cp\u003eTrong production, agent cần xử lý lỗi gracefully:\u003c\/p\u003e\n\u003cpre\u003e\u003ccode\u003e\/\/ Cấu hình retry cho tool execution\nconst robustTool = tool({\n  name: 'fetch_external_data',\n  description: 'Lấy dữ liệu từ API bên ngoài',\n  parameters: { \/* ... *\/ },\n  execute: async (params) =\u0026gt; {\n    const maxRetries = 3;\n    let lastError;\n\n    for (let attempt = 1; attempt \u0026lt;= maxRetries; attempt++) {\n      try {\n        const data = await externalAPI.fetch(params);\n        return JSON.stringify(data);\n      } catch (error) {\n        lastError = error;\n        if (attempt \u0026lt; maxRetries) {\n          \/\/ Exponential backoff\n          await sleep(Math.pow(2, attempt) * 1000);\n        }\n      }\n    }\n\n    \/\/ Trả về lỗi thân thiện thay vì throw\n    return JSON.stringify({\n      error: true,\n      message: `Không thể lấy dữ liệu sau ${maxRetries} lần thử.\n                Vui lòng thử lại sau.`,\n      details: lastError.message\n    });\n  }\n});\u003c\/code\u003e\u003c\/pre\u003e\n\n\u003ch2\u003eStreaming và Real-time Output\u003c\/h2\u003e\n\u003cp\u003eAgent 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:\u003c\/p\u003e\n\u003cpre\u003e\u003ccode\u003e\/\/ Streaming output từ agent\nconst stream = await agent.stream(\n  'Phân tích doanh thu Q4\/2024 và tạo báo cáo chi tiết'\n);\n\nfor await (const event of stream) {\n  switch (event.type) {\n    case 'text':\n      process.stdout.write(event.content);\n      break;\n    case 'tool_call':\n      console.log(`[Đang sử dụng: ${event.tool_name}]`);\n      break;\n    case 'tool_result':\n      console.log(`[Kết quả: ${event.tool_name} hoàn thành]`);\n      break;\n    case 'error':\n      console.error(`[Lỗi: ${event.message}]`);\n      break;\n  }\n}\u003c\/code\u003e\u003c\/pre\u003e\n\n\u003ch2\u003eTesting Agent\u003c\/h2\u003e\n\u003cp\u003eAgent cần được test kỹ lưỡng trước khi deploy. Các chiến lược testing:\u003c\/p\u003e\n\n\u003ch3\u003eUnit Testing cho Tools\u003c\/h3\u003e\n\u003cpre\u003e\u003ccode\u003e\/\/ tests\/tools.test.ts\nimport { describe, it, expect } from 'vitest';\n\ndescribe('searchProducts tool', () =\u0026gt; {\n  it('should return results for valid query', async () =\u0026gt; {\n    const result = await searchTool.execute({\n      query: 'laptop', max_results: 5\n    });\n    const parsed = JSON.parse(result);\n    expect(parsed).toHaveLength(5);\n    expect(parsed[0]).toHaveProperty('name');\n    expect(parsed[0]).toHaveProperty('price');\n  });\n\n  it('should handle empty results gracefully', async () =\u0026gt; {\n    const result = await searchTool.execute({\n      query: 'nonexistent_product_xyz'\n    });\n    const parsed = JSON.parse(result);\n    expect(parsed).toHaveLength(0);\n  });\n\n  it('should respect max_results limit', async () =\u0026gt; {\n    const result = await searchTool.execute({\n      query: 'phone', max_results: 3\n    });\n    const parsed = JSON.parse(result);\n    expect(parsed.length).toBeLessThanOrEqual(3);\n  });\n});\u003c\/code\u003e\u003c\/pre\u003e\n\n\u003ch3\u003eIntegration Testing cho Agent\u003c\/h3\u003e\n\u003cp\u003eTest 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.\u003c\/p\u003e\n\n\u003ch2\u003ePerformance Optimization\u003c\/h2\u003e\n\u003cp\u003eĐể agent hoạt động nhanh và tiết kiệm chi phí:\u003c\/p\u003e\n\u003cul\u003e\n  \u003cli\u003e\n\u003cstrong\u003eChọn model phù hợp:\u003c\/strong\u003e Dùng Haiku cho triage\/routing, Sonnet cho tác vụ chính, Opus cho suy luận phức tạp\u003c\/li\u003e\n  \u003cli\u003e\n\u003cstrong\u003eGiới hạn số lượt loop:\u003c\/strong\u003e Đặt max_turns để tránh agent chạy vô hạn\u003c\/li\u003e\n  \u003cli\u003e\n\u003cstrong\u003eCache tool results:\u003c\/strong\u003e Cache kết quả của tools không thay đổi thường xuyên\u003c\/li\u003e\n  \u003cli\u003e\n\u003cstrong\u003eParallel tool calls:\u003c\/strong\u003e Khi có nhiều tool calls độc lập, chạy song song thay vì tuần tự\u003c\/li\u003e\n  \u003cli\u003e\n\u003cstrong\u003eTối ưu instructions:\u003c\/strong\u003e Instructions ngắn gọn và rõ ràng giúp agent quyết định nhanh hơn\u003c\/li\u003e\n\u003c\/ul\u003e\n\n\u003ch2\u003eDeploy Agent lên Production\u003c\/h2\u003e\n\u003cp\u003eKhi agent đã test xong, triển khai lên production với các best practices:\u003c\/p\u003e\n\u003cul\u003e\n  \u003cli\u003eSử dụng environment variables cho API keys và cấu hình\u003c\/li\u003e\n  \u003cli\u003eThiết lập rate limiting để kiểm soát chi phí API\u003c\/li\u003e\n  \u003cli\u003eLogging đầy đủ: ghi lại mọi tool calls, decisions và errors\u003c\/li\u003e\n  \u003cli\u003eMonitoring: theo dõi latency, success rate, và cost per interaction\u003c\/li\u003e\n  \u003cli\u003eGradual rollout: bắt đầu với nhóm user nhỏ trước khi mở rộng\u003c\/li\u003e\n\u003c\/ul\u003e\n\n\u003ch2\u003eBước tiếp theo\u003c\/h2\u003e\n\u003cp\u003eBạ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 \u003ca href=\"\/collections\/nang-cao\"\u003eThư viện Nâng cao\u003c\/a\u003e.\u003c\/p\u003e\n","brand":"Minh Tuấn","offers":[{"title":"Default Title","offer_id":47730150703316,"sku":null,"price":0.0,"currency_code":"VND","in_stock":true}],"thumbnail_url":"\/\/cdn.shopify.com\/s\/files\/1\/0821\/0264\/9044\/files\/claude-agent-sdk-deep-dive-xay-d_ng-agent-v_i-typescript-sdk.jpg?v=1774715529","url":"https:\/\/claude.vn\/products\/claude-agent-sdk-deep-dive-xay-d%e1%bb%b1ng-agent-v%e1%bb%9bi-typescript-sdk","provider":"CLAUDE.VN","version":"1.0","type":"link"}