Bạn đã quen gõ lệnh cho Claude Code trong terminal. Giờ bạn muốn cái “engine” đó chạy bên trong app của mình, trong một pipeline CI, hay một con bot xử lý ticket lúc 3 giờ sáng mà không ai ngồi gõ. Đó là lúc cần Claude Agent SDK.
Nói gọn: Agent SDK đưa đúng bộ tools, vòng lặp agent, và cách quản lý context của Claude Code ra thành một thư viện Python và TypeScript. Bài này giải thích nó là gì, khác gì với Claude Code và API thường, rồi hướng dẫn viết con agent đầu tiên chạy được.
TL;DR: Claude Agent SDK (trước tên là Claude Code SDK) cho phép chạy engine của Claude Code như một thư viện trong code Python/TypeScript, qua hàm
query(). Claude tự đọc file, chạy lệnh, sửa code trong vòng lặp agent. Dùng để nhúng agent vào script, server, CI/CD. Cài bằng pip/npm, auth bằng API key.
Dùng nếu: bạn cần nhúng năng lực Claude Code vào sản phẩm hoặc tự động hóa. Bỏ qua nếu: bạn chỉ code tương tác hằng ngày (dùng thẳng Claude Code CLI là đủ).
Bài này dành cho: người viết được Python hoặc TypeScript. Phần khái niệm và bảng so sánh thì ai cũng đọc được, nhưng phần build agent có code thật.
Claude Agent SDK là gì, và vì sao đổi tên?
Trả lời nhanh: một thư viện cho phép bạn điều khiển engine của Claude Code bằng code, thay vì gõ lệnh trong terminal. Anthropic gọi nó là “build production AI agents with Claude Code as a library”. Trong tài liệu, nó tên là Claude Agent SDK.
Hình dung thế này. Claude Code mà bạn dùng trong terminal là một sản phẩm hoàn chỉnh: nó có vòng lặp agent (đọc file, chạy lệnh, sửa code, lặp lại tới khi xong), bộ tools built-in, và cách quản lý context. Agent SDK lấy đúng cái lõi đó và phơi ra dưới dạng một hàm bạn gọi từ Python hoặc TypeScript. Cùng động cơ, khác cách lái. (Định nghĩa “build production AI agents with Claude Code as a library” theo tài liệu chính thức, truy cập 30/06/2026.)
Một điểm hay gây nhầm: SDK này trước đây tên là “Claude Code SDK”, sau Anthropic đổi thành “Claude Agent SDK”. Nên nếu bạn thấy hai cái tên trong các bài viết cũ và mới, đừng hoang mang, chúng là một. Việc đổi tên phản ánh ý đồ: đây là bộ công cụ để xây agent nói chung, không bó hẹp ở việc code. (Việc đổi tên được ghi nhận qua các nguồn cộng đồng như ksred.com và mục “People also ask” của Google, không nêu trực tiếp trên trang overview.)
Agent SDK khác gì Claude Code, API, và Managed Agents?
Đây là chỗ nhiều người rối nhất, vì Anthropic có vài cách khác nhau để build với Claude. Câu hỏi đúng không phải “cái nào tốt nhất” mà “cái nào cho việc của mình”. Bảng dưới là bốn lựa chọn hay bị nhầm với nhau.
| Công cụ | Bản chất | Bạn tự lo gì | Hợp khi |
|---|---|---|---|
| Messages / Client API | Gọi model trực tiếp, stateless | Tự viết vòng lặp tool (execute rồi gửi lại) | Cần kiểm soát từng bước, tự quản tool |
| Claude Agent SDK | Engine Claude Code dạng thư viện | Chỉ gọi query(), Claude tự lo tool loop |
Nhúng agent vào script/CI/app, chạy trên hạ tầng của bạn |
| Claude Code CLI | Sản phẩm tương tác trong terminal | Không gì cả, dùng luôn | Code tương tác hằng ngày, việc một lần |
| Managed Agents | REST API Anthropic host + sandbox | Không lo hạ tầng/session | Production không muốn tự vận hành sandbox |
Vài cặp đáng phân biệt rõ:
- API thường vs Agent SDK. Với Messages API, bạn nhận về
tool_userồi tự thực thi và gửi kết quả lại trong một vòngwhile. Với Agent SDK, Claude tự chạy vòng đó: bạn đưa một câu lệnh, nó tự đọc file, chạy bash, sửa code tới khi xong.
- Agent SDK vs Claude Code CLI. Cùng năng lực, khác giao diện. CLI cho dev tương tác và việc một lần; SDK cho CI/CD, app riêng, automation production. Nhiều team dùng cả hai: CLI để code, SDK để chạy production.
- Agent SDK vs Managed Agents. SDK chạy vòng lặp agent ngay trong process của bạn, đụng file trên hạ tầng của bạn, lưu session JSONL trên đĩa của bạn. Managed Agents là dịch vụ Anthropic host: agent chạy trong sandbox của họ, bạn gọi qua REST. Đường phổ biến: prototype bằng SDK, lên production thì cân nhắc Managed Agents.
Trước khi bắt đầu cần gì?
Cần ba thứ: một runtime (Python 3.10 trở lên, hoặc Node), một API key, và biết sơ về thư mục .claude/. Bạn không cần cài Claude Code riêng, vì gói SDK đã bundle sẵn binary của Claude Code.
- Runtime: Python 3.10+ (gói báo lỗi
No matching distributionnghĩa là Python cũ hơn 3.10), hoặc Node cho bản TypeScript. - API key: lấy ở Console. Quan trọng: SDK không cho dùng tài khoản đăng nhập claude.ai để chạy sản phẩm, phải dùng API key (xem phần auth bên dưới).
.claude/: SDK tự đọc skills, commands,CLAUDE.md, plugins từ.claude/trong thư mục dự án và~/.claude/. Nếu chưa quen, đọc trước bài cấu hình Claude Code.
Bước 1: Cài SDK và set API key
Cài gói rồi khai báo API key qua biến môi trường. Hai dòng lệnh là xong, nhưng phần auth có một bẫy đáng nhớ với ai định bán sản phẩm.
Cài đặt:
# Python (cần 3.10+)
pip install claude-agent-sdk
# TypeScript / Node
npm install @anthropic-ai/claude-agent-sdk
Set API key (lấy từ Console):
export ANTHROPIC_API_KEY=your-api-key
Nếu bạn chạy trên cloud provider, SDK hỗ trợ sẵn bằng biến môi trường:
- Amazon Bedrock:
CLAUDE_CODE_USE_BEDROCK=1+ cấu hình AWS credentials. - Google Vertex AI:
CLAUDE_CODE_USE_VERTEX=1+ Google Cloud credentials. - Microsoft Azure:
CLAUDE_CODE_USE_FOUNDRY=1+ Azure credentials.
Bẫy auth quan trọng: Anthropic không cho phép sản phẩm build trên Agent SDK dùng đăng nhập claude.ai hay rate limit của gói Pro/Max. Bạn phải dùng API key. Đây là điểm hay làm hỏng kế hoạch của người mới định “lấy gói Max chạy bot cho rẻ”. Cũng nhớ đừng để lộ key, xem bài bẫy API key trong Claude Code.
Bước 2: Viết agent đầu tiên (Python và TypeScript)
Con agent tối thiểu chỉ cần gọi hàm query() với một câu lệnh và danh sách tool được phép. Claude lo phần còn lại: đọc file, chạy lệnh, sửa code, lặp tới khi xong. Đây là khác biệt lớn nhất so với API thường, nơi bạn phải tự viết vòng lặp đó.
Python:
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions
async def main():
async for message in query(
prompt="Find and fix the bug in auth.py",
options=ClaudeAgentOptions(allowed_tools=["Read", "Edit", "Bash"]),
):
print(message) # Claude đọc file, tìm bug, sửa
asyncio.run(main())
TypeScript:
import { query } from "@anthropic-ai/claude-agent-sdk";
for await (const message of query({
prompt: "Find and fix the bug in auth.ts",
options: { allowedTools: ["Read", "Edit", "Bash"] }
})) {
console.log(message);
}
query() trả về một luồng message (async iterator) mà bạn duyệt bằng async for (Python) hoặc for await (TS). allowed_tools (Python) / allowedTools (TS) là danh sách tool bạn pre-approve, để Claude khỏi hỏi xin phép từng bước. Tool built-in gồm: Read, Write, Edit, Bash, Monitor, Glob, Grep, WebSearch, WebFetch, AskUserQuestion, và vài cái nữa, dùng được ngay mà không phải tự implement.
Bước 3: Nâng cấp agent với tools, hooks, subagents, MCP, sessions
Một con agent thật cần nhiều hơn một câu lệnh. SDK cho bạn đúng những thành phần làm nên Claude Code, mỗi cái bật qua một field trong options. Dưới đây là bản đồ nhanh để biết cái gì làm gì.
- Permissions / tools.
allowed_toolsquyết định Claude được làm gì. Một agent chỉ-đọc (Read, Glob, Grep) sẽ phân tích mà không sửa được file, an toàn cho việc review. - Hooks. Chạy code của bạn tại các mốc trong vòng đời agent:
PreToolUse,PostToolUse,Stop,SessionStart,SessionEnd,UserPromptSubmit. Dùng để log, chặn, hay biến đổi hành vi. Ví dụ: ghi mọi lần sửa file ra một file audit. - Subagents. Khai báo
AgentDefinition(mô tả + prompt + tools riêng) để giao việc con cho một agent chuyên biệt. Nhớ thêm"Agent"vàoallowed_toolsđể tự duyệt. Khái niệm này giống sub-agent trong Claude Code. - MCP. Field
mcp_serversnối agent tới hệ thống ngoài qua Model Context Protocol: database, browser, API. Ví dụ cắm Playwright MCP để agent điều khiển trình duyệt. Xem thêm MCP server cho Claude Code. - Sessions. Bắt
session_idtừ message init, rồi truyềnresume=session_idở lần gọi sau để giữ nguyên context (file đã đọc, phân tích đã làm).
Một điểm tiện: với options mặc định, SDK tự load cấu hình từ .claude/ của bạn, gồm skills, slash command, CLAUDE.md, plugin. Muốn giới hạn nguồn nào được load thì set setting_sources (Python) hoặc settingSources (TS).
Khi nào dùng SDK, khi nào dùng CLI hay claude -p?
Câu trả lời ngắn: việc tương tác hằng ngày thì dùng CLI; việc lập trình, lặp lại, hoặc chạy không người ngồi thì dùng SDK. Giữa hai cái có một lựa chọn nhẹ là chế độ headless của CLI.
- Claude Code CLI cho code tương tác và việc một lần. Bạn ngồi đó, gõ, xem Claude làm.
claude -plà chế độ in (print) không tương tác của CLI: đưa một prompt, nhận kết quả, không mở phiên chat. Hợp cho script một-lần hay một bước nhỏ trong CI mà bạn không cần điều khiển sâu.- Agent SDK cho khi bạn cần điều khiển bằng code thật: bật tắt tool theo logic, gắn hooks, chạy subagent, giữ session, xử lý lỗi, nhúng vào server hay pipeline. Đây là đường cho agent production.
Quy tắc của mình: nếu bạn thấy mình đang viết một vòng while quanh claude -p để parse output và quyết định bước tiếp, đó là tín hiệu nên chuyển sang SDK. SDK sinh ra để lo đúng cái vòng đó.
Sai lầm và lưu ý khi build production
Phần lớn rắc rối không nằm ở code mẫu, mà ở những điều kiện vận hành quanh nó: auth, license, và ranh giới giữa prototype và production.
- Định dùng gói Pro/Max cho bot. Không được. SDK yêu cầu API key; đăng nhập claude.ai không dùng được cho sản phẩm. Tính chi phí theo API trước khi cam kết.
- Tưởng SDK là sandbox an toàn. Không. SDK chạy trong process của bạn, đụng file thật trên hạ tầng của bạn. Giới hạn
allowed_tools, cân nhắc agent chỉ-đọc cho phần phân tích, và bọc hooks để chặn hành vi nguy hiểm. - Đặt tên sản phẩm là “Claude Code”. Branding guideline không cho đối tác gọi sản phẩm mình là “Claude Code”. Giữ thương hiệu riêng, ghi “powered by Claude” nếu cần.
- Nhảy thẳng lên production bằng SDK trên hạ tầng tự dựng. Nếu bạn không muốn tự vận hành sandbox và session, cân nhắc đường prototype-bằng-SDK rồi chuyển Managed Agents cho production.
FAQ
Agent SDK khác Messages API chỗ nào?
Với Messages API, bạn tự viết vòng lặp tool: nhận tool_use, thực thi, gửi kết quả lại, lặp. Với Agent SDK, Claude tự chạy vòng đó qua query(). SDK là API thường cộng sẵn vòng lặp agent và bộ tool built-in, nên bạn viết ít hơn nhiều cho cùng một việc.
Agent SDK có miễn phí không?
Bản thân thư viện là mã nguồn để cài, nhưng nó gọi model qua API nên bạn trả tiền theo lượng token API như mọi lần gọi Claude. Không dùng được gói đăng nhập claude.ai cho sản phẩm; phải dùng API key và chịu chi phí API.
Có cần cài Claude Code riêng không?
Không. Gói TypeScript bundle sẵn binary Claude Code cho nền tảng của bạn; gói Python cũng đi kèm Claude Code CLI. Cài SDK là đủ để chạy.
Có bản Go hay Java không?
Tài liệu chính thức hỗ trợ Python và TypeScript. Một số người tìm bản Go/Java (theo related search), nhưng đường chính thức hiện là hai ngôn ngữ trên. Với ngôn ngữ khác, bạn gọi qua process hoặc dùng Messages API trực tiếp.
claude -p là gì?
Là chế độ in không tương tác của Claude Code CLI: đưa một prompt qua dòng lệnh, nhận kết quả, không mở phiên chat. Tiện cho script một-lần. Nhưng để build agent lập trình thực sự, hãy dùng SDK thay vì bọc vòng lặp quanh claude -p.
Kết luận
Claude Agent SDK là cách lấy đúng engine của Claude Code, vòng lặp agent, tools, quản lý context, và đặt nó vào code của bạn. Cài bằng pip hoặc npm, auth bằng API key, gọi query(), và bạn có một con agent tự đọc file, chạy lệnh, sửa code.
Chọn đúng công cụ là nửa thành công: API thường khi bạn muốn tự lo mọi thứ, SDK khi muốn Claude lo vòng lặp agent giúp, CLI cho việc tương tác, Managed Agents khi không muốn tự vận hành hạ tầng. Nhớ bẫy auth (phải dùng API key) và đừng đặt tên sản phẩm là “Claude Code”.
Muốn đi tiếp, đọc nguyên tắc xây agent hiệu quả cho phần tư duy thiết kế, và bẫy API key trước khi đưa key vào production.
