Claude Agent SDK — Xây Dựng AI Agent Tự Động Với Claude

Claude Agent SDK (trước đây gọi là Claude Code SDK) cho phép bạn xây dựng các AI Agent sản xuất với Claude Code như một thư viện lập trình. Agent của bạn có thể tự động đọc file, chạy lệnh, tìm kiếm web, chỉnh sửa code — tất cả những gì Claude Code có thể làm, giờ đây lập trình được bằng Python và TypeScript.

SDK cung cấp sẵn các công cụ (tool) tích hợp để đọc file, chạy lệnh và chỉnh sửa code — agent của bạn hoạt động ngay mà không cần tự xây dựng logic thực thi tool.

Ví dụ nhanh

# Python
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="Tìm và sửa bug trong auth.py",
        options=ClaudeAgentOptions(allowed_tools=["Read", "Edit", "Bash"]),
    ):
        print(message)

asyncio.run(main())

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

for await (const message of query({
  prompt: "Tìm và sửa bug trong auth.py",
  options: { allowedTools: ["Read", "Edit", "Bash"] }
})) {
  console.log(message);
}

Bắt Đầu Nhanh — Cài Đặt và Chạy Agent Đầu Tiên

Bước 1: Cài đặt SDK

Chọn ngôn ngữ phù hợp với dự án của bạn:

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

# Python
pip install claude-agent-sdk

Bước 2: Thiết lập API key

Lấy API key từ Console và thiết lập biến môi trường:

export ANTHROPIC_API_KEY=your-api-key

SDK cũng hỗ trợ xác thực qua các nhà cung cấp bên thứ ba:

• Amazon Bedrock: đặt CLAUDE_CODE_USE_BEDROCK=1 và cấu hình AWS credentials
• Google Vertex AI: đặt CLAUDE_CODE_USE_VERTEX=1 và cấu hình Google Cloud credentials
• Microsoft Azure: đặt CLAUDE_CODE_USE_FOUNDRY=1 và cấu hình Azure credentials

Bước 3: Chạy Agent đầu tiên

Ví dụ tạo agent liệt kê file trong thư mục hiện tại:

# Python
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="Có những file gì trong thư mục này?",
        options=ClaudeAgentOptions(allowed_tools=["Bash", "Glob"]),
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())

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

for await (const message of query({
  prompt: "Có những file gì trong thư mục này?",
  options: { allowedTools: ["Bash", "Glob"] }
})) {
  if ("result" in message) console.log(message.result);
}

Công Cụ Tích Hợp Sẵn (Built-in Tools)

Agent của bạn có thể đọc file, chạy lệnh và tìm kiếm codebase ngay lập tức. Các công cụ chính bao gồm:

Công cụ	Chức năng
Read	Đọc bất kỳ file nào trong thư mục làm việc
Write	Tạo file mới
Edit	Chỉnh sửa chính xác file hiện có
Bash	Chạy lệnh terminal, script, thao tác git
Glob	Tìm file theo pattern (**/*.ts, src/**/*.py)
Grep	Tìm kiếm nội dung file bằng regex
WebSearch	Tìm kiếm web để lấy thông tin mới nhất
WebFetch	Lấy và phân tích nội dung trang web
AskUserQuestion	Hỏi người dùng câu hỏi làm rõ

Ví dụ: Tạo agent tìm kiếm tất cả comment TODO trong codebase:

async for message in query(
    prompt="Tìm tất cả comment TODO và tạo bản tóm tắt",
    options=ClaudeAgentOptions(allowed_tools=["Read", "Glob", "Grep"]),
):
    if hasattr(message, "result"):
        print(message.result)

Hooks — Chạy Code Tùy Chỉnh Trong Vòng Đời Agent

Hooks cho phép bạn chạy code tùy chỉnh tại các thời điểm quan trọng trong vòng đời của agent. Sử dụng hooks để xác thực, ghi log, chặn hoặc biến đổi hành vi agent.

Các hook có sẵn: PreToolUse, PostToolUse, Stop, SessionStart, SessionEnd, UserPromptSubmit và nhiều hơn nữa.

Ví dụ: Ghi log tất cả thay đổi file vào file audit:

from claude_agent_sdk import query, ClaudeAgentOptions, HookMatcher
from datetime import datetime

async def log_file_change(input_data, tool_use_id, context):
    file_path = input_data.get("tool_input", {}).get("file_path", "unknown")
    with open("./audit.log", "a") as f:
        f.write(f"{datetime.now()}: modified {file_path}\n")
    return {}

async for message in query(
    prompt="Refactor utils.py để cải thiện khả năng đọc",
    options=ClaudeAgentOptions(
        permission_mode="acceptEdits",
        hooks={
            "PostToolUse": [
                HookMatcher(matcher="Edit|Write", hooks=[log_file_change])
            ]
        },
    ),
):
    if hasattr(message, "result"):
        print(message.result)

Subagents — Agent Chuyên Biệt Cho Từng Nhiệm Vụ

Tạo các agent chuyên biệt để xử lý các nhiệm vụ con cụ thể. Agent chính ủy thác công việc, và subagent báo cáo kết quả.

async for message in query(
    prompt="Dùng agent code-reviewer để review codebase này",
    options=ClaudeAgentOptions(
        allowed_tools=["Read", "Glob", "Grep", "Agent"],
        agents={
            "code-reviewer": AgentDefinition(
                description="Chuyên gia review code về chất lượng và bảo mật.",
                prompt="Phân tích chất lượng code và đề xuất cải thiện.",
                tools=["Read", "Glob", "Grep"],
            )
        },
    ),
):
    if hasattr(message, "result"):
        print(message.result)

Các message từ trong context của subagent bao gồm trường parent_tool_use_id, giúp bạn theo dõi message nào thuộc về lần thực thi subagent nào.

Kết Nối Hệ Thống Bên Ngoài Qua MCP

Kết nối với các hệ thống bên ngoài thông qua Model Context Protocol (MCP): database, trình duyệt, API và hàng trăm service khác.

Ví dụ: Kết nối Playwright MCP server để agent tự động hóa trình duyệt:

async for message in query(
    prompt="Mở example.com và mô tả những gì bạn thấy",
    options=ClaudeAgentOptions(
        mcp_servers={
            "playwright": {"command": "npx", "args": ["@playwright/mcp@latest"]}
        }
    ),
):
    if hasattr(message, "result"):
        print(message.result)

Quản Lý Quyền Hạn Agent

Kiểm soát chính xác những công cụ agent được phép sử dụng. Cho phép thao tác an toàn, chặn thao tác nguy hiểm, hoặc yêu cầu phê duyệt cho hành động nhạy cảm.

Ví dụ: Tạo agent chỉ đọc (read-only) chỉ phân tích mà không sửa code:

async for message in query(
    prompt="Review code này theo best practices",
    options=ClaudeAgentOptions(
        allowed_tools=["Read", "Glob", "Grep"],  # Chỉ đọc, không sửa
    ),
):
    if hasattr(message, "result"):
        print(message.result)

Quản Lý Phiên Làm Việc (Sessions)

Duy trì context qua nhiều lần trao đổi. Claude nhớ các file đã đọc, phân tích đã thực hiện và lịch sử hội thoại. Có thể tiếp tục phiên sau hoặc fork để thử hướng khác.

session_id = None

# Truy vấn đầu tiên: lưu session ID
async for message in query(
    prompt="Đọc module authentication",
    options=ClaudeAgentOptions(allowed_tools=["Read", "Glob"]),
):
    if hasattr(message, "subtype") and message.subtype == "init":
        session_id = message.session_id

# Tiếp tục với đầy đủ context từ truy vấn đầu
async for message in query(
    prompt="Bây giờ tìm tất cả nơi gọi module đó",
    options=ClaudeAgentOptions(resume=session_id),
):
    if hasattr(message, "result"):
        print(message.result)

Tính Năng Từ Claude Code

SDK hỗ trợ cấu hình dựa trên hệ thống file của Claude Code. Để sử dụng, đặt setting_sources=["project"] (Python) hoặc settingSources: ['project'] (TypeScript).

Tính năng	Mô tả	Vị trí
Skills	Khả năng chuyên biệt định nghĩa bằng Markdown	.claude/skills/*/SKILL.md
Slash commands	Lệnh tùy chỉnh cho tác vụ phổ biến	.claude/commands/*.md
Memory	Context và hướng dẫn dự án	CLAUDE.md
Plugins	Mở rộng với commands, agents và MCP servers tùy chỉnh	Lập trình qua option plugins

So Sánh Agent SDK Với Các Công Cụ Khác

Agent SDK vs Client SDK (Anthropic SDK)

Anthropic Client SDK cho bạn truy cập API trực tiếp — bạn gửi prompt và tự xây dựng logic thực thi tool. Agent SDK cung cấp Claude với khả năng thực thi tool tích hợp sẵn.

# Client SDK: Bạn tự xây vòng lặp tool
response = client.messages.create(...)
while response.stop_reason == "tool_use":
    result = your_tool_executor(response.tool_use)
    response = client.messages.create(tool_result=result, **params)

# Agent SDK: Claude tự động xử lý tool
async for message in query(prompt="Sửa bug trong auth.py"):
    print(message)

Agent SDK vs Claude Code CLI

Cùng khả năng, khác giao diện:

Use case	Lựa chọn tốt nhất
Phát triển tương tác	CLI
CI/CD pipeline	SDK
Ứng dụng tùy chỉnh	SDK
Tác vụ một lần	CLI
Tự động hóa production	SDK

Nhiều team dùng cả hai: CLI cho phát triển hàng ngày, SDK cho production.

Bước Tiếp Theo

Tham khảo các tài nguyên sau để bắt đầu xây dựng AI Agent:

• Quickstart — Xây agent sửa bug trong vài phút
• Agent mẫu — Email assistant, research agent và nhiều hơn
• TypeScript SDK — Tài liệu API đầy đủ cho TypeScript
• Python SDK — Tài liệu API đầy đủ cho Python

Xem thêm các bài viết liên quan trên Agentwork.vn:

• Claude Code — Công Cụ AI Lập Trình Agentic Toàn Diện
• Claude Code Workflows — Hướng Dẫn Quy Trình Làm Việc
• MCP Connector — Kết Nối Công Cụ Qua API