Claude Agent SDK: Lập trình agent AI tự chủ bằng TypeScript/Python

Định nghĩa

Claude Agent SDK là bộ công cụ lập trình chính thức của Anthropic (hỗ trợ TypeScript và Python) cho phép developer xây dựng agent AI tự chủ bằng cách "đóng gói" agent loop — vòng lặp suy luận → thực thi → cập nhật trạng thái — thành các component phần mềm có cấu trúc (Agent, Runner, Tool, Context), hoàn toàn độc lập với Claude Code CLI.

Giải thích chi tiết

Từ khái niệm "Agent Loop" đến code thực thi

Trước khi có SDK, developer phải tự viết hàng trăm dòng boilerplate để quản lý vòng lặp agent: gọi API Anthropic, parse JSON kết quả, xử lý lỗi khi tool fail, rồi feed kết quả trở lại context. Agent SDK đóng gói pattern này thành Runner — một event loop tự động xử lý việc gọi LLM, nhận tool_use blocks, thực thi tools song song, và đưa kết quả trở lại cho agent cho đến khi task hoàn thành.

Điểm mấu chốt là sự đảo ngược điều khiển (inversion of control): thay vì code của bạn "kéo" dữ liệu từ AI (result = call_llm()), giờ AI "đẩy" hành động ra ngoài thông qua structured tool calls. SDK capture điều này bằng cách implement vòng lặp while (!taskComplete) — không phải execution tuyến tính mà là một state machine liên tục được điều khiển bởi LLM reasoning.

Bốn thành phần kiến trúc cốt lõi

SDK xây dựng trên bốn trụ cột tách biệt rõ ràng:

Agent Class: Encapsulate system prompt, danh sách tools khả dụng, và lifecycle hooks (pre/post tool execution). Đây là "bộ não chuyên biệt" với persona riêng, ví dụ một agent chỉ được phép đọc file (read-only) để explore codebase, agent khác được quyền ghi để refactor.

Runner: Quản lý event loop và orchestration, tách biệt logic "suy luận" khỏi "thực thi". Runner đảm nhận việc gọi model (Claude 3.5 Sonnet/Opus/Haiku), parse tool_use blocks, execute tools in parallel, rồi cập nhật context cho lượt tiếp theo.

Context Isolation: Mỗi subagent được cấp context window riêng biệt (giống như subagents trong CLI nhưng ở cấp độ code). Điều này tránh "context pollution" — hiện tượng các bước suy luận trung gian (grep logs, trial-and-error) làm nhiễu context chính và đẩy quyết định quan trọng ra khỏi context window.

MCP & Computer Use: Tích hợp sẵn Model Context Protocol để kết nối với bất kỳ MCP server nào (PostgreSQL, GitHub, Slack), và hỗ trợ Computer Use (điều khiển máy tính qua screenshot) với coordinate normalization — cho phép agent thực sự "nhìn thấy" UI để test.

Progressive Disclosure — Giải pháp cho context window hạn hẹp

Khác với "mega-prompt" cồng kềnh, SDK áp dụng kiến trúc ba tầng (metadata → instructions → resources). Metadata (tên, mô tả skill ~100 tokens) luôn được load để agent biết "cái gì có sẵn"; instructions (< 5k tokens) chỉ load khi skill được trigger qua semantic matching; resources (file lớn, scripts) được stream qua bash mà không cần nạp vào context LLM. Điều này cho phép agent sở hữu hàng chục tools mà không làm đầy context window 200K tokens — giống như bộ nhớ ảo (virtual memory) của hệ điều hành.

SDK vs Claude Code CLI: Hai phương diện của cùng một đồng xu

Trong khi Claude Code CLI là "IDE tương tác" cho người dùng cuối (human-in-the-loop, cần terminal mở), Agent SDK là "runtime headless" cho developer để nhúng AI vào backend service, CI/CD pipeline, hoặc xây dựng sản phẩm AI-native. SDK cho phép bạn deploy agent như một microservice, trong khi CLI tối ưu cho quy trình phát triển cá nhân với các slash commands như /plan hay /commit.

Ví dụ thực tế

Build agent đầu tiên: Đồng bộ đơn hàng Shopee vào ERP

Giả sử bạn cần xây dựng agent tự động pull dữ liệu từ Shopee API, chuẩn hóa theo schema nội bộ, và insert vào PostgreSQL cho hệ thống ERP của công ty thương mại điện tử. Với Agent SDK (Python):

from anthropic_agent_sdk import Agent, Runner

# Định nghĩa agent với persona và tools cụ thể
pipeline_agent = Agent(
    name="shopee-sync",
    system_prompt="Bạn là data engineer. Nhiệm vụ: pull dữ liệu orders từ Shopee API, validate JSON schema theo định dạng ERP nội bộ, rồi insert vào PostgreSQL. Nếu API timeout, retry tối đa 3 lần.",
    tools=[fetch_shopee_api, validate_erp_schema, postgres_upsert],
    model="claude-3-5-sonnet-20241022"
)

# Runner tự động điều phối toàn bộ workflow
result = Runner.run_sync(
    pipeline_agent, 
    "Sync dữ liệu orders từ ngày hôm qua, batch size 100 records"
)

Thay vì viết hàng trăm dòng xử lý API, retry logic, và context management, SDK cho phép bạn định nghĩa agent như một class có cấu trúc. Agent tự động quyết định gọi tool nào trước (fetch → validate → insert), xử lý lỗi retry khi API timeout, và cập nhật trạng thái vào context cho lượt suy luận tiếp theo — tất cả trong một vòng lặp duy nhất được Runner quản lý.

Team 3 agent phối hợp: Auto Code Review cho startup fintech

Xây dựng hệ thống review PR tự động với 3 agent chạy song song trên cùng một codebase nhưng trong context window cô lập:

1. Explore Agent (dùng Haiku cho rẻ, nhanh): Đọc toàn bộ diff và xác định files thay đổi, trả về danh sách file ảnh hưởng.
2. Security Agent (dùng Sonnet): Kiểm tra lỗ hổng SQL injection, XSS trong các file đã thay đổi, chỉ tập trung vào input validation — cực kỳ quan trọng với hệ thống thanh toán VietQR.
3. TestGen Agent (dùng Sonnet): Viết unit tests cho logic mới dựa trên diff analysis.

Mỗi agent chạy trong process riêng với context isolation — giống như process isolation trong hệ điều hành, tránh hiện tượng "cognitive crosstalk" khi agent này bị nhiễu bởi suy luận trial-and-error của agent khác. Sau khi cả 3 hoàn thành, một Aggregator Agent tổng hợp kết quả thành báo cáo cuối cùng. Cách tiếp cận này giảm 40-60% token usage so với dùng một agent duy nhất phải "chứng kiến" toàn bộ quá trình tư duy của cả 3 nhiệm vụ trong cùng một context window.

Ứng dụng

• Backend Developer muốn nhúng AI: Xây dựng microservice tự động xử lý tin nhắn từ Zalo OA hoặc comment Facebook — agent phân loại độ khẩn cấp, query database qua MCP, và đề xuất response template qua REST API, hoạt động 24/7 không cần terminal mở.
• DevOps Engineer tại công ty công nghệ Việt Nam: Tạo autonomous debugging agent chạy trong CI pipeline — tự động đọc log lỗi từ GitHub Actions, grep source code, tạo patch fix và mở PR với mô tả lỗi chi tiết, rồi gửi thông báo vào Slack channel của team.
• Startup Founder xây dựng sản phẩm AI-native: Đóng gói SDK thành "AI Data Analyst" cho khách hàng doanh nghiệp — một agent service nhận truy vấn tiếng Việt về dữ liệu bán hàng trên Shopee/Lazada, tự động sinh SQL query qua MCP PostgreSQL, và trả về báo cáo tự động kèm insight về xu hướng mua sắm.

So sánh

Kết luận: SDK là lựa chọn khi bạn cần "productize" AI — biến agent thành một phần của hệ thống phần mềm chạy autonomously, trong khi CLI là công cụ để "leverage" AI trong quy trình phát triển cá nhân với sự giám sát của người dùng.

Bài viết liên quan

• Cùng cụm: Agent Teams: Nhiều Claude phối hợp cùng lúc — Tìm hiểu sâu hơn về orchestration nhiều agent song song và cách phối hợp chúng hiệu quả. Hands-on: Build agent đầu tiên với Agent SDK — Hướng dẫn từng bước cài đặt môi trường, viết file agent.ts đầu tiên, và triển khai agent lên server.

• Đọc tiếp: Case study: Dự án thực tế Level 4 — Xem cách áp dụng Agent SDK vào xây dựng SaaS và ERP thực tế, từ prototype đến production với CI/CD integration.