Claude Agent SDK là gì: xây AI agent riêng từ nền Claude Code

Thử hình dung sáng thứ Hai nào cũng vậy: chị kế toán mở năm file CSV xuất từ phần mềm bán hàng, dò từng cột, tìm chỗ bất thường, gõ lại thành bản tóm tắt gửi sếp. Mất cả buổi. Nhờ Claude Code làm hộ thì được, nhưng lần nào cũng phải ngồi gõ lệnh, canh chừng. Giá mà biến được nó thành một công cụ chạy riêng, đúng việc, đúng quyền. Claude Agent SDK là bộ công cụ lập trình của Anthropic, dùng để xây AI agent riêng dựa trên đúng bộ máy đang chạy Claude Code: đọc file, chạy lệnh, gọi công cụ, tự kiểm tra kết quả.

Đọc nhanh trong 30 giây

Ngày 29/09/2025, Anthropic đổi tên Claude Code SDK thành Claude Agent SDK, phát hành gói Python claude-agent-sdk và gói TypeScript @anthropic-ai/claude-agent-sdk bản 0.1.0.

SDK cho phép đưa vòng lặp "thu thập ngữ cảnh, hành động, kiểm tra" của Claude Code vào phần mềm của chính anh chị.

Cài: npm install -g @anthropic-ai/claude-code rồi pip install claude-agent-sdk, cần Python 3.10 trở lên và Node.js.

Hợp với doanh nghiệp có người viết được Python, muốn tự động hóa quy trình dựa trên file và hệ thống nội bộ.

Claude Agent SDK là gì, sao lại đổi tên?

Claude Agent SDK là thư viện để đưa "bộ não và đôi tay" của Claude Code vào phần mềm riêng. Trong bài công bố, Anthropic giải thích lý do đổi tên: bên trong hãng, Claude Code đã được dùng cho nghiên cứu, làm video, ghi chép và nhiều việc ngoài lập trình, nên bộ máy phía sau xứng đáng là nền tảng cho mọi loại agent.

Ví von kiểu xưởng ô tô: tự làm agent từ đầu giống tự đúc động cơ, tự lắp hộp số. Claude Agent SDK trao cho anh chị nguyên phần khung gầm và động cơ đang chạy hằng ngày bên trong Claude Code. Việc của anh chị là đóng thùng xe: xe chở hàng, xe khách hay xe cứu thương tùy nghiệp vụ.

Nguyên tắc thiết kế Anthropic nêu là cho agent một chiếc máy tính: được tìm file, đọc, ghi, chạy lệnh như một nhân viên ngồi trước máy. Hãng nêu bốn loại agent làm ví dụ: agent tài chính, trợ lý cá nhân quản lý lịch, agent chăm sóc khách hàng biết chuyển cho người khi cần, và agent nghiên cứu đối chiếu nhiều nguồn để viết báo cáo.

Sơ đồ khối: ứng dụng của doanh nghiệp gọi Claude Agent SDK, SDK chạy Claude Code bên dưới, nối tới công cụ, MCP và hook

Anh chị viết phần nghiệp vụ, SDK lo phần động cơ.

Agent làm việc theo vòng lặp nào?

Claude Agent SDK chạy agent theo vòng lặp bốn bước Anthropic mô tả: thu thập ngữ cảnh, hành động, kiểm tra kết quả, rồi lặp lại. Giống người đầu bếp: đi chợ lấy đồ, nấu, nếm thử, thiếu muối thì nêm thêm rồi nếm lại, tới khi vừa miệng mới bưng ra.

Thu thập ngữ cảnh: agent tự tìm thông tin trong thư mục bằng các lệnh như grep, tail. Anthropic khuyên bắt đầu bằng cách tìm này trước, chỉ thêm tìm kiếm theo nghĩa bằng vector khi cần nhanh hơn. SDK có sẵn subagent để chia việc song song, mỗi subagent dùng vùng ngữ cảnh riêng. Tính năng compact tự tóm tắt tin nhắn cũ khi ngữ cảnh sắp đầy.
Hành động: qua công cụ tự định nghĩa, lệnh bash, viết code, và MCP để nối với Slack, GitHub, Google Drive, Asana.
Kiểm tra kết quả: đặt luật rõ ràng (ví dụ kiểm tra lint), dùng phản hồi bằng hình chụp màn hình, hoặc nhờ một mô hình khác chấm.
Lặp lại tới khi đạt.

Vòng lặp bốn bước của Claude Agent SDK: thu thập ngữ cảnh, hành động, kiểm tra, lặp lại

Nấu, nếm, nêm, nếm lại: agent chỉ dừng khi kết quả đạt.

Mẹo

Bước "kiểm tra" là chỗ anh chị nên đầu tư nhiều nhất. Một luật kiểm tra rõ ràng, ví dụ "file tóm tắt phải có đủ ba mục và mỗi số phải khớp file gốc", đáng giá hơn mọi câu dặn "làm cẩn thận nhé".

Cài Claude Agent SDK cho Python

Yêu cầu theo README ngày 29/09/2025: Python 3.10 trở lên, Node.js, và Claude Code cài qua npm.

Cài Claude Code:

npm install -g @anthropic-ai/claude-code

Cài SDK:

pip install claude-agent-sdk

Chạy thử đoạn mã ngắn nhất trong README:

import anyio
from claude_agent_sdk import query

async def main():
    async for message in query(prompt="What is 2 + 2?"):
        print(message)

anyio.run(main)

Cửa sổ terminal với hai lệnh cài Claude Code, Claude Agent SDK và đoạn mã chạy thử

Hai lệnh cài, năm dòng code là có agent đầu tiên trả lời.

Ai đang dùng Claude Code SDK bản cũ cần đổi ClaudeCodeOptions thành ClaudeAgentOptions. README dẫn tới changelog bản 0.1.0 với các thay đổi khác: gộp cấu hình system prompt, tách riêng phần cài đặt, thêm subagent khai báo bằng code và tách nhánh phiên làm việc.

Thử với việc thật: agent đọc báo cáo tuần

Giới hạn agent trong một thư mục. Quay lại chị kế toán ở đầu bài. README cho phép giới hạn công cụ, chế độ duyệt và thư mục làm việc. Giống phát thẻ từ cho nhân viên mới: thẻ chỉ mở đúng tầng, đúng phòng cần làm.

from claude_agent_sdk import query, ClaudeAgentOptions

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Write"],
    permission_mode="acceptEdits",
    cwd="/du-lieu/bao-cao-tuan"
)

async for message in query(
    prompt="Đọc các file CSV trong thư mục, viết file tom-tat.md nêu ba điểm bất thường",
    options=options
):
    print(message)

Thêm công cụ riêng và chặn lệnh nguy hiểm. Với ClaudeSDKClient, anh chị viết công cụ bằng hàm Python và gắn vào agent như một máy chủ MCP chạy ngay trong chương trình, không cần tiến trình riêng. Ví dụ trong README:

from claude_agent_sdk import tool, create_sdk_mcp_server, ClaudeAgentOptions

@tool("greet", "Greet a user", {"name": str})
async def greet_user(args):
    return {"content": [{"type": "text", "text": f"Hello, {args['name']}!"}]}

server = create_sdk_mcp_server(name="my-tools", version="1.0.0", tools=[greet_user])

options = ClaudeAgentOptions(
    mcp_servers={"tools": server},
    allowed_tools=["mcp__tools__greet"]
)

Thay hàm chào hỏi bằng hàm tra đơn hàng hay đọc phiếu sửa chữa trong hệ thống của công ty là anh chị có công cụ nghiệp vụ. README còn có ví dụ hook PreToolUse: một hàm Python chạy trước mỗi lần agent dùng Bash, gặp lệnh trong danh sách cấm thì từ chối. Đây là luật an toàn viết bằng code, không phụ thuộc AI có nghe lời hay không.

Nếu anh chị đang so sánh các bộ công cụ xây agent, có thể đọc thêm bài OpenAI Agents SDK và bài về bộ subagent wshobson/agents.

Trước khi giao chìa khóa cho agent

Lưu ý

Phụ thuộc Claude Code: SDK Python gọi Claude Code bên dưới, nên máy chạy phải có Node.js và Claude Code. README có lỗi riêng CLINotFoundError cho trường hợp chưa cài.

Chi phí: mỗi vòng lặp đọc file, gọi công cụ đều tính token. README không nêu giá, anh chị xem bảng giá API của Anthropic.

Quyền rộng: agent chạy được lệnh trên máy. Luôn khai báo allowed_tools tối thiểu, đặt cwd vào thư mục riêng, thêm hook chặn lệnh nguy hiểm.

Dữ liệu: nội dung file agent đọc sẽ được gửi tới mô hình của Anthropic để xử lý. Dữ liệu khách hàng, lương, hợp đồng cần cân nhắc trước.

Giấy phép: MIT cho phần SDK Python.

Nhận xét của chuyên gia

Đổi tên nghe như chuyện nhỏ, nhưng tôi thấy đây là tín hiệu rõ: Anthropic coi Claude Code là nền tảng làm agent chung, không riêng cho lập trình viên. Việc văn phòng lặp lại như đọc báo cáo, đối chiếu file có thể dựng thành agent mà không phải tự viết phần khó nhất là vòng lặp.

Hợp với ai: doanh nghiệp có ít nhất một người viết được Python, có quy trình rõ ràng dựa trên file và hệ thống nội bộ, muốn agent chạy tự động theo lịch hoặc theo sự kiện thay vì ngồi chat.

Chưa hợp với ai: đội chưa có ai lập trình, hoặc chỉ cần hỏi đáp tài liệu, khi đó dùng thẳng Claude Code hay ứng dụng Claude nhanh hơn; doanh nghiệp có quy định dữ liệu không được rời hạ tầng nội bộ, vì mô hình chạy trên máy chủ của Anthropic.

Cách bắt đầu của tôi: chọn một việc nhỏ, chạy được trên một thư mục, có kết quả đo được, ví dụ tóm tắt báo cáo tuần từ file xuất sẵn. Dựng đủ ba lớp an toàn ngay từ đầu: giới hạn công cụ, giới hạn thư mục, hook chặn lệnh. Chạy tay vài lần, so với người làm, rồi mới đặt lịch tự động.

Một câu để nhớ: động cơ Anthropic đã làm sẵn, phần anh chị cần làm kỹ là chìa khóa và phanh.

Xem thêm các mốc trong chuỗi ở dòng thời gian AI.

Câu hỏi thường gặp

Claude Agent SDK khác gì Claude Code SDK?

Claude Agent SDK là tên mới của Claude Code SDK, đổi ngày 29/09/2025. Bản 0.1.0 đổi ClaudeCodeOptions thành ClaudeAgentOptions, thêm subagent khai báo bằng code và tùy chọn tách nhánh phiên.

Claude Agent SDK có miễn phí không?

Thư viện miễn phí theo giấy phép MIT. Anh chị trả tiền cho lượt dùng mô hình Claude mà agent tiêu tốn khi chạy.

Không biết lập trình có dùng được Claude Agent SDK không?

Khó. SDK là thư viện Python và TypeScript, cần viết code để khai báo công cụ, quyền và luồng chạy. Người không lập trình nên bắt đầu với Claude Code hoặc ứng dụng Claude.

Claude Agent SDK có hỗ trợ MCP không?

Có. README cho phép gắn máy chủ MCP bên ngoài và máy chủ MCP chạy ngay trong chương trình Python, dùng chung trong một cấu hình.

Nguồn: Anthropic, Building agents with the Claude Agent SDK, 29/09/2025.