Thực chiến Agent SDK: Xây dựng agent AI đầu tiên

Hướng dẫn thực chiến tạo AI agent tùy chỉnh bằng Claude Agent SDK: cài đặt, chạy agent loop đầu tiên với TypeScript/Python, không cần Claude Code CLI.

Định nghĩa

Agent SDK là bộ công cụ lập trình bằng TypeScript/Python từ Anthropic, giúp bạn xây dựng AI agent tùy chỉnh chạy độc lập hoàn toàn với Claude Code CLI. Thay vì chat qua terminal, bạn viết agent loop (suy luận → hành động → quan sát) bằng code thuần túy—định nghĩa rõ ràng, tái sử dụng, và tích hợp vào bất kỳ hệ thống nào từ CI/CD đến microservices.

Giải thích chi tiết

Kiến trúc Agent SDK: Từ chat sang state machine

Trước khi có SDK, developer phải tự viết boilerplate phức tạp để xử lý: (1) parallel tool calling, (2) error recovery khi tool fail, (3) context window management giữa agent và sub-agents. Agent SDK đóng gói những pattern này thành các component tái sử dụng: Agent Class (đóng gói system prompt và available tools), Runner (quản lý event loop), và Context Isolation (mỗi subagent nhận context window riêng).

Điểm cốt lõi là inverted control (đảo ngược luồng điều khiển): trong traditional function calling, code "kéo" data (result = function(args)), nhưng trong agent SDK, flow bị đảo ngược—LLM "đẩy" actions ra ngoài khi nó thấy cần. Runner implement điều này bằng cách sử dụng while loop chứ không phải linear execution, liên tục feeding tool outputs quay lại LLM cho đến khi task complete.

Progressive Disclosure: Bộ nhớ 3 tầng

SDK áp dụng kiến trúc progressive disclosure (tiết lộ từng phần) để tránh bloat context window:

Level 1 (Metadata): Khoảng 100 tokens, luôn được load. Giống như "mục lục" trên kệ sách—agent biết skill nào tồn tại nhưng không cần đọc nội dung.
Level 2 (Instructions): Dưới 5k tokens, chỉ load khi trigger qua description matching. Giống như "mở sách" khi cần—agent đọc hướng dẫn chi tiết khi quyết định "đây là security audit".
Level 3 (Resources): Không giới hạn, truy cập qua bash. Giống như "dùng máy tính"—script thực thi mà không cần agent đọc manual.

Cách tiếp cận này giảm tiêu thụ token 60-80% so với monolithic prompts, cho phép agent có hàng trăm skill mà context window không bị ô nhiễm.

Xây dựng Agent đầu tiên

Quy trình xây dựng agent với SDK bao gồm:

Khởi tạo Agent Class: Định nghĩa system prompt (vai trò, personality) và danh sách tools available. Ví dụ: tạo agent với tên "CodeReviewer", system prompt "You are a strict code reviewer...", và tools như readFile, postComment.
Thiết lập Runner: Tạo instance Runner để quản lý event loop. Runner sẽ handle việc gọi LLM, parse tool_use blocks, thực thi tools song song, và feed kết quả quay lại agent.
Kết nối MCP: Sử dụng Model Context Protocol để kết nối với external tools (GitHub, PostgreSQL, Slack) mà không cần hardcode integration logic. MCP cho phép agent "discover" capabilities động qua schema definitions.
Chạy agent loop: Runner bắt đầu vòng lặp: LLM reasoning → tool execution → state update → repeat cho đến khi natural stop (không còn tool_use) hoặc đạt max turns.

Subagent Delegation trong SDK

SDK hỗ trợ subagent delegation—spawn các specialized children agents từ parent agent. Mỗi subagent nhận context window riêng (như Claude Code subagents), tránh "context pollution" từ intermediate reasoning steps.

Ví dụ: Parent agent nhận task "refactor codebase", spawn subagent A để research dependencies, subagent B để viết tests, subagent C để thực hiện refactoring—chạy song song trong isolated worktrees. Parent chỉ nhận kết quả tổng hợp (lossy compression), không bị ngập trong chi tiết implementation.

Ví dụ thực tế

Code Review Agent tự động cho team startup

Giả sử bạn là tech lead ở một startup tại HCM—thay vì chờ senior dev rảnh để review PR, bạn xây dựng agent chạy headless trên GitHub Actions:

Agent được cấu hình với system prompt chuyên sâu về security và performance, kết nối GitHub MCP để đọc PR diff. Khi chạy, agent spawn Security Auditor Subagent (chỉ có quyền đọc, dùng model Haiku cho nhanh) để scan vulnerabilities, đồng thời spawn Performance Checker Subagent để phân tích complexity. Kết quả được tổng hợp và post comment lên GitHub bằng tool call. Toàn bộ chạy không cần human-in-the-loop, xử lý 1 PR trong 3 phút thay vì 30 phút manual review.

Data Processing Pipeline cho sàn thương mại điện tử

Team data của một sàn TMĐT lớn tại Việt Nam xây dựng agent xử lý đơn hàng hàng ngày:

Agent được lên lịch chạy mỗi sáng 8h, sử dụng SDK kết nối với PostgreSQL MCP để query đơn hàng đêm qua, dùng Python tool để làm sạch dữ liệu (loại trùng, chuẩn hóa địa chỉ tiếng Việt, xử lý VietQR), sau đó ghi vào data warehouse và gửi báo cáo tổng hợp qua Slack MCP. Agent này chạy headless trên AWS Lambda với SDK print mode, tự động retry khi gặp lỗi network mà không cần can thiệp.

Team 3 Agent phối hợp build tính năng mới

Mô hình phối hợp giống "công ty phần mềm thu nhỏ" để build tính năng thanh toán qua VietQR trong 2 giờ:

Researcher Agent: Dùng Browse MCP để tìm best practices và quy chuẩn VietQR của Napas.
Builder Agent: Nhận kết quả research, viết code implementation và unit tests. Chạy trong worktree riêng với Auto Mode.
Reviewer Agent: Review output của Builder, check logic errors và security issues (ví dụ: validate checksum VietQR), báo cáo lại cho Builder nếu cần sửa.

Cả 3 agent chạy song song qua SDK, coordinated qua filesystem hoặc message passing, hoàn thành feature sẵn sàng merge trong 2 giờ thay vì 2 ngày làm việc thông thường.

Ứng dụng

Developer muốn automation cụ thể: Thay vì dùng Claude Code CLI thủ công mỗi ngày, bạn có thể xây dựng agent chuyên biệt (ví dụ: "Dependency Update Agent") chạy tự động, tự động tạo PR cập nhật thư viện và chạy test.

Startup xây dựng sản phẩm AI-native: Dùng SDK để nhúng agent capabilities vào SaaS product của mình—ví dụ: automated customer support agent có thể truy cập database và tạo ticket, hoạt động như một "nhân viên" thực thụ trong hệ thống.

Team DevOps và Platform Engineering: Tích hợp AI vào CI/CD pipeline một cách deterministic. Thay vì dùng bash scripts phức tạp, dùng SDK để tạo agents có thể quyết định (approve deployment nếu tests pass và không có security alerts).

Data Engineer: Xây dựng ETL agents chạy scheduled, tự động xử lý data pipeline với error handling và retry logic phức tạp mà không cần maintain Airflow DAGs.

So sánh

Đặc điểm	Agent SDK	Claude Code CLI
Giao diện	Lập trình (TypeScript/Python)	Chat tương tác (Terminal)
Chế độ chạy	Headless, deterministic	Interactive, human-in-the-loop
Tích hợp	Nhúng vào app/infra/script standalone	Dùng trực tiếp cho daily workflow
Context management	Programmatic (tự định nghĩa memory)	Filesystem-based (CLAUDE.md)
Subagents	Spawn qua code với isolated context	Spawn qua slash commands hoặc tự động
Use case chính	Automation, CI/CD, production systems	Development hàng ngày, exploratory coding

Agent SDK và Claude Code CLI không loại trừ nhau—CLI phù hợp cho việc viết code hàng ngày với feedback nhanh, trong khi SDK phù hợp cho việc xây dựng hệ thống tự động hoá hoặc nhúng AI vào sản phẩm production.