Claude Agent SDK là gì? Thư viện đứng sau Claude Code

Thay vì gọi Messages API rồi tự xoay xở với từng lượt, bạn nhận sẵn một harness (khung điều khiển) hoàn chỉnh: nó quản lý vòng lặp agent, các công cụ hệ thống và ngữ cảnh làm việc.

Với thư viện này, bạn dựng được những AI agent tự chủ: đọc tệp, chạy lệnh terminal, tự sửa lỗi ngay trong tiến trình của bạn. Đây không phải một wrapper API, mà là cách sản phẩm hóa những agent phức tạp vốn trước đây chỉ chạy được qua dòng lệnh của Claude Code.

Claude Agent SDK là gì?

Claude Agent SDK là "động cơ" cốt lõi của Claude Code, được Anthropic đóng gói lại thành thư viện lập trình. Claude Code là ứng dụng dòng lệnh (CLI) để kỹ sư ngồi tương tác trực tiếp; SDK này là bộ phận bên trong nó, thứ bạn tích hợp vào bất kỳ sản phẩm phần mềm, công cụ nội bộ hay pipeline tự động nào.

Triết lý thiết kế của SDK gói gọn trong một câu: trao cho Claude một chiếc máy tính. Bằng cách cấp quyền vào terminal và hệ thống tệp qua một thư mục làm việc (cwd), agent làm việc giống một kỹ sư thật — tìm tệp, đọc nội dung, chỉnh sửa, rồi kiểm tra kết quả bằng lệnh shell.

Khác với Client SDK của Messages API, nơi bạn phải tự quản lý từng lượt gọi, Claude Agent SDK là khung điều khiển tự vận hành. Nó tự gọi mô hình, tự quyết định dùng công cụ nào, tự xử lý phản hồi từ môi trường. Bạn đưa yêu cầu; SDK lo các bước trung gian cho đến khi xong việc.

SDK hỗ trợ hai ngôn ngữ: Python 3.10+ và TypeScript trên Node.js 18+. Cả hai bản đều đóng gói sẵn binary Claude Code, nên phần lớn trường hợp bạn không cần cài Claude Code riêng. Có vài ngoại lệ đáng nhớ: nếu pip cài bản source thay vì platform wheel (chẳng hạn trên Windows ARM64), hoặc nếu bạn chạy npm ci --omit=optional khiến npm bỏ qua optional dependency, thì binary không đi kèm và bạn phải cài Claude Code thủ công.

Vòng lặp agent hoạt động như thế nào?

Agent trong SDK chạy theo một chu kỳ khép kín: thu thập ngữ cảnh (gather context) → hành động (take action) → xác minh kết quả (verify work) → lặp lại. Quy trình này giúp agent luôn tự điều chỉnh theo kết quả thực tế thay vì hành động mù quáng. Mỗi vòng đầy đủ là một lượt (turn), và vòng lặp dừng khi Claude trả lời mà không gọi thêm công cụ nào.

Việc thu thập ngữ cảnh dựa nhiều vào "agentic search". Thay vì chỉ dùng tìm kiếm ngữ nghĩa (semantic search) — vốn hay thiếu chính xác với cấu trúc mã nguồn — agent dùng thẳng các công cụ như grep, glob hay tail để quét hệ thống. Hệ quả: cấu trúc thư mục và tệp tin của bạn chính là một dạng kỹ nghệ ngữ cảnh (context engineering). Tổ chức thư mục tốt là bạn đang gián tiếp lập trình khả năng suy luận cho agent.

Ở bước hành động, điểm mạnh nhất của SDK là khả năng tự sửa lỗi. Một lệnh Bash thất bại hay đoạn mã hỏng sau khi chỉnh sửa sẽ quay lại agent dưới dạng phản hồi lỗi, và nó tự tìm cách khắc phục ở lượt kế tiếp thay vì dừng lại chờ bạn.

Bước cuối là xác minh. SDK cho phép bạn đặt ra các luật nghiêm ngặt, dùng phản hồi bằng hình ảnh (chụp ảnh màn hình qua MCP Playwright chẳng hạn), hoặc để một mô hình khác đóng vai giám khảo. Đây là chỗ quyết định agent có gây ra thay đổi ngoài ý muốn trong môi trường production hay không.

SDK mang sẵn những công cụ và cơ chế nào?

Bộ công cụ tích hợp gồm Read, Write, Edit, Bash, Glob, Grep, WebSearch và WebFetch. Chúng đủ để agent làm việc từ lập trình đến thu thập dữ liệu web ngay khi khởi tạo, không cần bạn viết thêm gì.

Một cơ chế không thể thiếu là Model Context Protocol (MCP). MCP nối agent với các dịch vụ bên ngoài như Slack, GitHub hay database mà bạn không phải viết mã tích hợp riêng cho từng API. SDK đóng vai trò MCP client, gọi được công cụ từ bất kỳ MCP server nào bạn cấu hình.

Để quản lý phiên làm việc dài, SDK dùng cơ chế compaction (tóm tắt tự động). Khi cửa sổ ngữ cảnh sắp tràn, nó tóm tắt các lượt hội thoại cũ để giải phóng chỗ cho thông tin mới. Cách này khác hẳn việc cắt bỏ tin nhắn (truncation): các ý chính của cả quá trình vẫn được giữ lại.

Đáng giá nhất về mặt kỹ thuật là subagent. Bạn có thể yêu cầu agent chính sinh ra các subagent chuyên biệt để song song hóa công việc, mỗi subagent giữ một cửa sổ ngữ cảnh cô lập. Subagent chỉ trả kết quả quan trọng nhất về cho agent điều phối, nhờ vậy tiết kiệm token đáng kể và không làm nhiễu ngữ cảnh phiên chính bằng dữ liệu rác.

Agent SDK khác gì Claude Code CLI, Client SDK và các framework khác?

So với Client SDK của Messages API, khác biệt nằm ở quyền sở hữu vòng lặp. Với Client SDK, bạn tự viết vòng lặp while và toàn bộ logic xử lý tool_use. Với Agent SDK, thư viện làm sẵn việc đó ngay trong tiến trình của bạn.

So với Claude Code CLI, Agent SDK dành cho việc sản phẩm hóa. CLI để tương tác trực tiếp qua terminal; SDK để nhúng vào backend service, IDE plugin hay pipeline CI/CD.

Nếu bạn đang cân nhắc Managed Agents, điểm phân biệt là hạ tầng. Agent SDK chạy trên hạ tầng của bạn, trong tiến trình của bạn; Managed Agents chạy trên hạ tầng Anthropic với sandbox riêng. SDK hợp hơn khi agent cần truy cập trực tiếp hệ thống tệp cục bộ hoặc dịch vụ nội bộ mà bạn không muốn mở cổng ra ngoài.

So với các framework như LangGraph, Claude Agent SDK là giải pháp "batteries-included" (có sẵn mọi thứ cần thiết) tối ưu riêng cho mô hình Claude. LangGraph cho bạn sự linh hoạt tuyệt đối và khả năng đa mô hình; Agent SDK đổi phần linh hoạt đó lấy tốc độ triển khai và những tính năng đặc thù của Claude, chẳng hạn cơ chế chỉnh sửa tệp chính xác từng dòng.

Vì sao Claude Code SDK đổi tên, và điều đó thay đổi những gì?

Tháng 9/2025, Anthropic đổi tên "Claude Code SDK" thành "Claude Agent SDK". Cái tên mới phản ánh tầm nhìn rộng hơn: SDK không chỉ dành cho lập trình mà còn để dựng agent trong tài chính, nghiên cứu hay trợ lý vận hành.

Về mặt kỹ thuật, đây là một thay đổi phá vỡ tương thích. Tên package trên npm và PyPI, đường dẫn import, và các đối tượng cấu hình đều đổi: @anthropic-ai/claude-code thành @anthropic-ai/claude-agent-sdk, claude-code-sdk thành claude-agent-sdk, và trong Python thì ClaudeCodeOptions thành ClaudeAgentOptions. Mã nguồn dùng định danh cũ sẽ hỏng.

Có hai thay đổi hành vi dễ làm bạn mất thời gian hơn cả việc đổi tên. Thứ nhất, SDK không còn mặc định dùng system prompt của Claude Code nữa; muốn giữ hành vi cũ, bạn phải yêu cầu rõ preset claude_code, hoặc truyền system prompt của riêng mình. Thứ hai là cách nạp cấu hình từ ổ đĩa, phần được siết lại rồi hoàn nguyên — chi tiết nằm ở phần chạy thật bên dưới.

Lõi công nghệ vẫn là Claude Code, nhưng phạm vi sử dụng mở rộng sang cả những tác vụ phi kỹ thuật như xử lý tệp CSV hay quản lý pipeline. Nói cách khác, agent giờ hiểu được quan hệ không gian giữa các tệp tin để hành động trong một phạm vi công việc rộng hơn nhiều so với chỉ sửa lỗi code.

Viết agent đầu tiên bằng Python hoặc TypeScript

Bạn cài thư viện qua trình quản lý gói quen thuộc:

• TypeScript: npm install @anthropic-ai/claude-agent-sdk
• Python: pip install claude-agent-sdk

Điểm khởi đầu là hàm query(), dùng cho các truy vấn một lượt. Khi cần hội thoại nhiều lượt có trạng thái, bạn chuyển sang ClaudeSDKClient. Một tham số đáng chú ý là cwd (thư mục làm việc hiện tại) — chính là "chiếc máy tính" bạn trao cho Claude.

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions
 
async def run_agent():
    options = ClaudeAgentOptions(
        model="claude-sonnet-5",
        allowed_tools=["Bash", "Read", "Glob"],
        system_prompt="Bạn là chuyên gia phân tích log hệ thống.",
        cwd="./data_logs",  # trao "máy tính" cho Claude tại thư mục này
        max_turns=20,       # chặn vòng lặp chạy vô hạn
    )
 
    async for message in query("Tìm các file log lỗi và tóm tắt nguyên nhân", options=options):
        if hasattr(message, "text"):
            print(message.text, end="", flush=True)
 
asyncio.run(run_agent())

Việc lặp qua async iterator cho bạn kết quả theo thời gian thực, đủ để dựng trải nghiệm streaming cho người dùng cuối. Công cụ tùy chỉnh được nối vào qua MCP; nhớ rằng chúng mang tên đầy đủ dạng mcp__<server>__<tool> khi bạn liệt kê trong danh sách cho phép.

Chạy thật: quyền hạn, chi phí và điều kiện xác thực

Xác thực. Bạn hoàn toàn có thể dùng gói đăng ký Claude (Pro, Max, Team, Enterprise) để chạy agent của chính mình qua SDK. Ranh giới nằm ở chỗ khác: nếu bạn phát hành sản phẩm cho người dùng khác, Anthropic không cho phép bên thứ ba mời người dùng đăng nhập bằng claude.ai hay dùng hạn mức của tài khoản claude.ai, trừ khi được duyệt trước. Trường hợp đó bạn dùng API key từ Claude Console, hoặc chạy qua Amazon Bedrock, Google Cloud Vertex AI hay Microsoft Foundry.

Chi phí. Tháng 5/2026 Anthropic từng thông báo sẽ tách hạn mức Agent SDK ra khỏi gói đăng ký kể từ 15/6/2026, thay bằng một khoản tín dụng riêng theo tháng. Kế hoạch đó đã bị tạm dừng trước khi có hiệu lực. Tính đến 15/6/2026, Claude Agent SDK, lệnh claude -p và các ứng dụng bên thứ ba vẫn dùng chung hạn mức của gói đăng ký như trước, và khoản tín dụng riêng không được cấp. Nếu bạn dùng API key thì không có gì thay đổi: vẫn tính phí theo token như mọi lời gọi API khác.

Quyền hạn. Có sáu chế độ permission_mode: default (hỏi qua callback canUseTool), acceptEdits (tự duyệt sửa file và vài lệnh hệ thống thông dụng), plan (khám phá và lập kế hoạch, không tự sửa mã nguồn), dontAsk (không bao giờ hỏi — chỉ chạy công cụ đã cấp phép sẵn, còn lại từ chối), auto (dùng một bộ phân loại để tự duyệt) và bypassPermissions (bỏ qua hỏi, chỉ dành cho môi trường cách ly như CI hay container). Với agent chạy không người trông, dontAsk là lựa chọn an toàn vì nó thất bại theo hướng đóng thay vì treo chờ. Dù chọn chế độ nào, hãy đặt max_turns hoặc max_budget_usd để agent không chạy vô hạn và đốt tiền.

Cấu hình từ ổ đĩa. Mặc định, SDK nạp cấu hình từ ổ đĩa của máy đang chạy: ~/.claude/settings.json, .claude/settings.json, các tệp CLAUDE.md và lệnh tùy chỉnh. Trong CI/CD hoặc production, hãy đặt setting_sources=[] để agent không hành xử khác nhau vì một tệp cấu hình ẩn nào đó trên máy lập trình viên.

Khi nào nên và không nên chọn Claude Agent SDK?

Chọn Claude Agent SDK khi bạn muốn dựng nhanh một agent mạnh dựa trên Claude, tận dụng khả năng điều khiển máy tính của nó mà không phải tự xây sandbox hay vòng lặp công cụ. Đổi lại, bạn chấp nhận một vòng lặp có sẵn và ít quyền can thiệp vào từng bước.

Đừng chọn nó nếu kiến trúc của bạn cần định tuyến giữa nhiều nhà cung cấp mô hình, hoặc cần kiểm soát từng node trong đồ thị thực thi. Khi đó LangGraph hay Client SDK cho bạn đúng thứ mà vòng lặp đóng gói sẵn của Agent SDK đã đánh đổi đi.

Tài liệu tham khảo

• Agent SDK overview — Claude Code Docs
• How the agent loop works — Claude Code Docs
• Building agents with the Claude Agent SDK — Anthropic
• Migrate to Claude Agent SDK — Claude Code Docs
• anthropics/claude-agent-sdk-python — GitHub
• Claude Agent SDK Tutorial: Create Agents Using Claude Sonnet 4.5 — DataCamp
• Claude Agent SDK Complete Guide: Building Custom Agents Beyond the CLI — Hidekazu Konishi
• Claude Agent SDK vs LangGraph: Choosing Your Agent Stack in 2026 — Developers Digest
• Anthropic officially bans using subscription authentication for third-party Claude use — AlternativeTo