Claude Agent SDK vs Claude API vs Claude Code: khi nào dùng cái nào

#Ba thứ này thực ra khác nhau ở đâu (góc delivery)

Tài liệu chính thức mô tả từng thứ rất rõ, nhưng khi đứng ở vai người phải chọn và bàn giao, tôi thấy chỉ cần hai câu hỏi là đủ tách bạch:

1. Ai viết agent loop? — tức cái vòng lặp "Claude gọi tool → mình chạy tool → trả kết quả → Claude quyết bước tiếp", cộng phần quản lý context khi hội thoại dài. Gọi tắt là harness.
2. Ai lo hạ tầng chạy nó? — process, máy, sandbox, nơi lưu trạng thái phiên. Gọi tắt là deployment.

Chiếu theo hai trục đó:

• Claude API (Messages API, kèm Tool Runner) — bạn định nghĩa tool, SDK (hoặc chính bạn) lo vòng lặp, và bạn tự host. Không có sẵn built-in tools, không có sandbox. Đây là mức "ít phép thuật nhất": bạn kiểm soát từng bước, đổi lại tự lắp mọi thứ.
• Claude Agent SDK — Claude Code được đóng gói thành thư viện (claude_agent_sdk cho Python, @anthropic-ai/claude-agent-sdk cho TypeScript). Nó mang theo nguyên harness của Claude Code: agent loop, context management, và bộ built-in tools (Read, Write, Edit, Bash, Glob, Grep, WebSearch, WebFetch…), cộng hooks, subagents, permissions, sessions. Bạn chỉ đưa prompt + cấu hình, nhưng vẫn tự host (chạy trong process của bạn).
• Claude Code — cùng harness đó, nhưng là CLI tương tác để gõ trong terminal. Cùng năng lực Agent SDK, khác ở giao diện.
• Managed Agents — Anthropic lo cả harness lẫn deployment: chạy agent loop trên hạ tầng của Anthropic và cấp một sandbox cho mỗi phiên. Bạn gửi event, nhận kết quả qua REST.

Điểm hay dịch sai nhất: Agent SDK không phải Tool Runner của Claude API. Tool Runner (client.beta.messages.tool_runner trong SDK anthropic / @anthropic-ai/sdk) chỉ là một helper mỏng tự chạy vòng lặp cho những tool bạn tự định nghĩa — không có built-in tool, không đụng filesystem. Agent SDK (claude-agent-sdk) là cả cỗ máy Claude Code. Hai package khác nhau, hai tầng khác nhau.

Bậc thang từ bạn kiểm soát nhiều → Anthropic lo nhiều:

Càng xuống dưới, bạn càng giao nhiều phần (trước là agent loop, sau là cả hạ tầng) cho Anthropic — đổi kiểm soát lấy tiện lợi.

#Trước khi chọn: việc này có thực sự cần agent không?

Câu hỏi bị bỏ qua nhiều nhất. Agent (nhiều bước, tự gọi tool, tự quyết) tốn token gấp bội và khó đoán hơn một request thẳng. Tôi chỉ đẩy một việc lên mức "agent" khi nó thoả cả bốn:

• Nhiều bước & khó đặc tả trước — kiểu "biến cái design doc này thành PR" chứ không phải "trích tiêu đề từ PDF".
• Đáng tiền — kết quả bù được chi phí và độ trễ cao hơn.
• Claude làm được — đúng loại việc mô hình mạnh.
• Sai còn cứu được — có test, review, rollback để bắt lỗi.

Thiếu một cái là tụt xuống mức đơn giản hơn: một request Claude API (phân loại, tóm tắt, trích xuất, hỏi–đáp) hoặc một workflow do bạn cầm nhịp. Đây là điều mấy bài "X là gì" hiếm khi nói, nhưng đứng ở vai delivery thì nó tiết kiệm nhất: không dựng agent cho việc một câu SQL giải quyết xong.

#Ma trận quyết định theo tình huống delivery

Đây là phần tôi dùng thật khi chốt hướng cho một hạng mục. Trục chính là tình huống delivery, không phải tiêu chí kỹ thuật trừu tượng — vì cái quyết định cuối cùng thường là "ai vận hành nó sau khi mình rời đi", chứ không phải "cái nào nhiều tính năng hơn".

Một cách đọc ma trận cho gọn: nội bộ, chạy trên hạ tầng mình → Agent SDK; nhúng vào sản phẩm, cần control → Claude API; tương tác nhanh → Claude Code; không muốn ôm hạ tầng → Managed Agents.

#Vài chỗ dễ vấp mà chỉ thấy khi làm thật

• Agent SDK dùng một request đơn giản đến ngạc nhiên. Bản chất là query(prompt, options) trả về một luồng message. Nhưng "đơn giản để chạy" không có nghĩa "đơn giản để cho lên production" — xem checklist dưới.
• Auth: không dùng được đăng nhập claude.ai cho sản phẩm bên thứ ba. Agent SDK cho sản phẩm của bạn phải dùng API key (hoặc Bedrock/Vertex/Foundry). Nghĩa là mỗi khách/mỗi agent là một dòng chi phí token bạn phải theo dõi từ đầu, đừng để cuối dự án mới phát hiện.
• Trạng thái phiên của Agent SDK là file JSONL trên filesystem của bạn. Rất tiện để resume/fork, nhưng khi bàn giao phải trả lời được: ai backup, ai xoá, giữ bao lâu. Managed Agents thì trạng thái nằm ở event log do Anthropic host — đổi tiện lấy quyền kiểm soát.
• Ràng buộc thương hiệu. Sản phẩm build trên Agent SDK không được đặt tên/nhận diện là "Claude Code". Nghe nhỏ, nhưng là điều cần chốt với khách trước khi in lên UI.

#Checklist đưa agent lên production

Chọn đúng công cụ mới là một nửa. Nửa còn lại — cũng là chỗ farm content không chạm tới — là đưa nó lên production mà không nổ chi phí hay mất kiểm soát. Với Agent SDK / Claude Code, tôi soi sáu điểm:

1. Least-privilege cho tool. Khai báo allowed_tools (Python) / allowedTools (TS) đúng những gì cần; chặn hẳn bằng disallowed_tools. Một agent chỉ để đọc thì đừng bật Bash và Edit. Đây là ranh giới an toàn, không phải chi tiết cấu hình.
2. Chặn chi phí token. Agent loop tốn gấp bội request thường. Đặt trần số vòng, chọn đúng tầng model cho đúng việc (đừng dùng model mạnh nhất cho mọi bước), tận dụng prompt caching cho phần context cố định.
3. Human-in-the-loop cho hành động khó đảo ngược. Dùng hook PreToolUse để chặn/hỏi trước khi agent chạy lệnh xoá, push, gọi API bên ngoài. Cùng permission_mode để quyết mức tự động.
4. Observability. Hook PostToolUse ghi audit log mỗi lần sửa file/chạy lệnh. Khi có sự cố, "agent đã làm gì" phải tra được, không phải đoán.
5. Auth & billing tách theo khách. API key server-side, theo dõi chi phí per-khách ngay từ ngày đầu. Đây là dữ liệu bạn sẽ cần khi báo giá vòng sau.
6. Kịch bản bàn giao. Ai vận hành sau khi mình rời đi? Session JSONL lưu ở đâu, model đổi giá thì ai chịu, ai giữ API key. Trả lời được mấy câu này trước khi ship thì agent mới thực sự "xong".

#Kết

Agent SDK, Claude API và Claude Code không xếp hạng hơn–kém; chúng nằm trên một bậc thang: càng lên cao càng giao nhiều phần (agent loop, rồi hạ tầng) cho Anthropic, đổi kiểm soát lấy tiện lợi. Chọn đúng là chọn đúng nấc cho đúng tình huống — và luôn kèm câu hỏi "việc này có cần agent không" ở đầu, "ai vận hành nó sau bàn giao" ở cuối.

Muốn đi sâu từng mảnh: bức tranh tổng thể khi build trên nền tảng Claude nằm ở ghi chú khoá Claude Platform 101; cơ chế Messages API và tool use ở Building with the Claude API; Claude Code ở Claude Code 101; còn subagents (thứ Agent SDK tái dùng) ở Introduction to Subagents. Toàn bộ lộ trình gom ở /learn/claude.