Xây dựng AI Agent với Claude Agent SDK - Hướng dẫn thực hành

Claude Agent SDK cung cấp cho bạn quyền truy cập lập trình vào cùng Agent Loop đang vận hành Claude Code. Agent của bạn có thể đọc file, chạy lệnh Shell, tìm kiếm web, chỉnh sửa code, gọi API bên ngoài thông qua MCP Server và điều phối Sub-Agent - tất cả chỉ với vài dòng TypeScript hoặc Python.

Khác với Anthropic Client SDK tiêu chuẩn nơi bạn phải tự xây dựng Tool Loop, Agent SDK xử lý việc thực thi công cụ, quản lý Context, thử lại và điều phối bên trong. Bạn mô tả những gì bạn muốn, cung cấp các công cụ, và Agent sẽ tự xử lý phần còn lại.

Kiến trúc

SDK theo một vòng lặp đơn giản: thu thập Context, thực hiện hành động, xác minh, lặp lại.

Điểm vào chính là query(), trả về một Async Iterator phát các thông điệp khi Agent làm việc. Mỗi thông điệp cho bạn biết Agent đang làm gì: suy luận, gọi công cụ, nhận kết quả, hoặc trả về kết quả cuối cùng.

Bắt đầu

Cài đặt

# TypeScript
npm install @anthropic-ai/claude-agent-sdk

# Python
pip install claude-agent-sdk

Bạn cần đặt Anthropic API Key là ANTHROPIC_API_KEY trong biến môi trường.

Agent đầu tiên của bạn

import { query } from "@anthropic-ai/claude-agent-sdk";

const conversation = query({
  prompt: "Find all TODO comments in the codebase and create a summary",
  options: {
    allowedTools: ["Read", "Glob", "Grep"],
  },
});

for await (const message of conversation) {
  if (message.type === "assistant") {
    process.stdout.write(message.content);
  }
  if (message.type === "result" && message.subtype === "success") {
    console.log("\nDone:", message.result);
  }
}

Chỉ có vậy thôi. Agent sẽ sử dụng Glob để tìm file, Grep để tìm kiếm pattern TODO, Read để kiểm tra kết quả khớp, và trả về bản tóm tắt có cấu trúc. Bạn không cần viết logic điều phối - SDK xử lý tất cả.

Phiên bản Python

from claude_agent_sdk import query

async for message in query(
    prompt="Find all TODO comments in the codebase and create a summary",
    options={"allowed_tools": ["Read", "Glob", "Grep"]},
):
    if message.type == "assistant":
        print(message.content, end="")
    if message.type == "result" and message.subtype == "success":
        print(f"\nDone: {message.result}")

Công cụ tích hợp sẵn

SDK đi kèm với các công cụ tương tự như trong Claude Code:

Bạn kiểm soát công cụ nào Agent có thể sử dụng thông qua allowedTools. Nếu một công cụ không có trong danh sách, Agent không thể gọi nó.

Chế độ quyền

Vì Agent thực thi lệnh thật trên hệ thống thật, quyền hạn rất quan trọng.

const conversation = query({
  prompt: "Refactor the auth module to use JWT",
  options: {
    allowedTools: ["Read", "Edit", "Glob", "Grep", "Bash"],
    permissionMode: "acceptEdits",
  },
});

Trong môi trường Production, luôn chạy Agent trong môi trường Sandbox (Container, VM) và sử dụng chế độ quyền hạn chế nhất mà vẫn cho phép Agent hoàn thành công việc.

Xây dựng công cụ tùy chỉnh với MCP

Sức mạnh thực sự của SDK đến từ việc mở rộng Agent bằng công cụ của riêng bạn. Công cụ tùy chỉnh được định nghĩa là MCP Server trong tiến trình (In-process) - không cần quản lý Subprocess, không có Network Overhead.

Ví dụ: Công cụ thời tiết

import { tool, createSdkMcpServer, query } from "@anthropic-ai/claude-agent-sdk";
import { z } from "zod";

const getTemperature = tool(
  "get_temperature",
  "Get the current temperature at a location",
  {
    latitude: z.number().describe("Latitude"),
    longitude: z.number().describe("Longitude"),
  },
  async ({ latitude, longitude }) => {
    const res = await fetch(
      `https://api.open-meteo.com/v1/forecast?latitude=${latitude}&longitude=${longitude}&current=temperature_2m&temperature_unit=celsius`
    );
    const data = await res.json();
    return {
      content: [
        {
          type: "text",
          text: `Current temperature: ${data.current.temperature_2m}C`,
        },
      ],
    };
  }
);

const weatherServer = createSdkMcpServer({
  name: "weather",
  version: "1.0.0",
  tools: [getTemperature],
});

for await (const message of query({
  prompt: "What's the weather like in Rome?",
  options: {
    mcpServers: { weather: weatherServer },
    allowedTools: ["mcp__weather__get_temperature"],
  },
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

Công cụ tùy chỉnh tuân theo quy ước đặt tên mcp__{server_name}__{tool_name}. Bạn có thể dùng Wildcard trong allowedTools: "mcp__weather__*" cho phép tất cả công cụ từ Weather Server.

Ví dụ: Công cụ truy vấn cơ sở dữ liệu

const queryDb = tool(
  "query_database",
  "Run a read-only SQL query against the application database",
  {
    sql: z.string().describe("SQL SELECT query to execute"),
  },
  async ({ sql }) => {
    // Validate: only allow SELECT queries
    if (!sql.trim().toUpperCase().startsWith("SELECT")) {
      return {
        content: [{ type: "text", text: "Error: Only SELECT queries are allowed." }],
      };
    }

    const result = await pool.query(sql);
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(result.rows, null, 2),
        },
      ],
    };
  }
);

Kết nối MCP Server bên ngoài

Ngoài công cụ In-process, bạn có thể kết nối với bất kỳ MCP Server nào hiện có - cùng những Server hoạt động với Claude Desktop, Cursor và các MCP Client khác.

for await (const message of query({
  prompt: "Check the latest issues in the frontend repo and summarize them",
  options: {
    mcpServers: {
      github: {
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-github"],
        env: { GITHUB_PERSONAL_ACCESS_TOKEN: process.env.GITHUB_TOKEN },
      },
    },
    allowedTools: ["mcp__github__*"],
  },
})) {
  // ...
}

Bạn có thể kết hợp nhiều MCP Server. Agent sẽ thấy tất cả công cụ từ tất cả Server đã kết nối và sử dụng chúng khi cần thiết.

Điều phối đa Agent

Đối với các Workflow phức tạp, bạn có thể định nghĩa các Sub-Agent chuyên biệt mà Agent cha ủy quyền cho. Mỗi Sub-Agent có Prompt, công cụ và lĩnh vực tập trung riêng.

for await (const message of query({
  prompt: "Review the PR, check for security issues, and update the changelog",
  options: {
    allowedTools: ["Read", "Edit", "Bash", "Glob", "Grep", "Agent"],
    agents: [
      {
        name: "security-reviewer",
        description: "Reviews code for security vulnerabilities",
        prompt: "You are a security expert. Analyze code for OWASP Top 10 vulnerabilities.",
        allowedTools: ["Read", "Glob", "Grep"],
      },
      {
        name: "changelog-writer",
        description: "Updates the CHANGELOG.md file based on recent changes",
        prompt: "You maintain the project changelog. Follow Keep a Changelog format.",
        allowedTools: ["Read", "Edit", "Bash"],
      },
    ],
  },
})) {
  // The parent agent will:
  // 1. Read the PR diff
  // 2. Delegate security review to security-reviewer
  // 3. Delegate changelog update to changelog-writer
  // 4. Synthesize results
}

Thêm "Agent" vào allowedTools của Agent cha để bật tính năng ủy quyền. Sub-Agent chạy với công cụ riêng của chúng và không thể truy cập công cụ của Agent cha trừ khi được cấp quyền rõ ràng.

Session và tính liên tục

Agent có thể duy trì Context qua nhiều Query bằng cách sử dụng Session. Lấy session_id từ lần tương tác đầu tiên và truyền vào resume cho các Query tiếp theo.

let sessionId: string | undefined;

// First query
for await (const message of query({
  prompt: "Read the project structure and understand the architecture",
  options: { allowedTools: ["Read", "Glob", "Grep"] },
})) {
  if (message.type === "init") {
    sessionId = message.session_id;
  }
}

// Follow-up query (same session, full context preserved)
for await (const message of query({
  prompt: "Now refactor the auth module based on what you learned",
  resume: sessionId,
  options: { allowedTools: ["Read", "Edit", "Bash"] },
})) {
  // Agent remembers the full project context from the first query
}

Claude Managed Agents

Nếu bạn không muốn tự host hạ tầng Agent, Claude Managed Agents (ra mắt tháng 4 năm 2026) cung cấp dịch vụ đám mây được quản lý hoàn toàn. Anthropic chạy Container, xử lý Scaling và cung cấp Streaming API.

Khác biệt chính: với Agent SDK, bạn chạy Agent Loop trong hạ tầng của riêng bạn. Với Managed Agents, Anthropic host và chạy Agent cho bạn. Bạn tương tác thông qua API dựa trên Session và nhận Event qua Server-Sent Events.

Giá:

• Agent SDK: chỉ tính theo giá Token của Claude API tiêu chuẩn. Bạn tự xử lý hosting.
• Managed Agents: giá Token cộng thêm $0.08 mỗi giờ Session (tính theo mili giây).

Các phương pháp tốt nhất cho Production

1. Luôn sử dụng Sandbox

Không bao giờ chạy Agent với quyền không giới hạn trên máy Production. Sử dụng Container (Docker, Fly.io, Modal) hoặc môi trường Sandbox (E2B, Vercel Sandbox).

2. Giới hạn quyền truy cập công cụ

Tuân theo nguyên tắc đặc quyền tối thiểu. Agent tạo báo cáo không cần Bash hay Write.

// Too permissive
allowedTools: ["Read", "Write", "Edit", "Bash", "Glob", "Grep"]

// Better: only what's needed
allowedTools: ["Read", "Glob", "Grep"]

3. Sử dụng Hook làm lan can bảo vệ

Hook cho phép bạn chặn các lời gọi công cụ trước và sau khi thực thi. Sử dụng cho việc ghi Log, xác thực và giới hạn tốc độ.

const conversation = query({
  prompt: "Analyze the codebase",
  options: {
    allowedTools: ["Read", "Glob", "Grep"],
    hooks: {
      PreToolUse: async (toolName, input) => {
        console.log(`Tool call: ${toolName}`, input);
        // Return false to block the call
        if (toolName === "Bash" && input.command.includes("rm")) {
          return false;
        }
        return true;
      },
    },
  },
});

4. Xử lý lỗi một cách tinh tế

Agent Loop có thể tạo ra lỗi - công cụ thất bại, API Rate Limit, Context Window tràn. Luôn kiểm tra loại thông điệp.

for await (const message of conversation) {
  switch (message.type) {
    case "assistant":
      // Agent reasoning
      break;
    case "tool_use":
      // Agent is calling a tool
      break;
    case "result":
      if (message.subtype === "error") {
        console.error("Agent failed:", message.error);
      }
      break;
  }
}

5. Giám sát lượng Token sử dụng

Agent Loop có thể tiêu thụ lượng Token đáng kể, đặc biệt với Codebase lớn. SDK bao gồm tính năng tự động nén Context, nhưng bạn vẫn nên giám sát lượng sử dụng.

Kết luận

Claude Agent SDK biến LLM từ một máy trả lời câu hỏi thành thứ gì đó gần với một lập trình viên mới vào nghề. Agent của bạn có thể đọc, viết, thực thi, xác minh và lặp lại - cùng Workflow mà con người thực hiện.

Bắt đầu từ nhỏ: xây dựng một Agent với vài công cụ tích hợp sẵn. Sau đó thêm công cụ MCP tùy chỉnh cho lĩnh vực cụ thể của bạn. Mở rộng lên điều phối đa Agent khi Workflow của bạn cần sự chuyên môn hóa.

Agent Loop là cùng một vòng lặp đang vận hành Claude Code. Nếu nó có thể xây dựng phần mềm, Agent của bạn cũng làm được.

Danh sách kiểm tra để bắt đầu:

• Cài đặt SDK (npm install @anthropic-ai/claude-agent-sdk)
• Đặt ANTHROPIC_API_KEY trong biến môi trường
• Xây dựng Agent đơn giản với công cụ tích hợp sẵn (Read, Glob, Grep)
• Thêm công cụ tùy chỉnh qua In-process MCP Server
• Kết nối MCP Server bên ngoài (GitHub, PostgreSQL, v.v.)
• Triển khai điều phối đa Agent với Sub-Agent
• Thiết lập môi trường Sandbox cho Production
• Thêm Hook cho việc ghi Log và lan can bảo vệ