Tự Xây Trợ Lý AI Riêng Với Claude Agent SDK

Claude Code chạy tốt trong terminal, nhưng có việc mình cần chạy tự động lúc 6 giờ sáng mà không ngồi mở app: kiểm tra đơn hàng mới, tóm tắt rồi gửi báo cáo. Đó là lúc Claude Agent SDK vào việc: dựng một agent chạy độc lập, không cần người ngồi gõ lệnh.

Khác gì so với dùng Claude Code trực tiếp

Claude Code là công cụ tương tác, cần người mở lên và ra lệnh. Agent SDK là thư viện lập trình để nhúng vòng lặp agent (suy nghĩ, gọi tool, quan sát kết quả, lặp lại) vào chính ứng dụng hoặc script của bạn, chạy nền không cần giao diện chat.

📌 Chưa chắc nên chọn gì? Đọc trước Học AI: Dùng Claude, ChatGPT, Gemini Đúng Việc — hướng dẫn tổng hợp của Kudomax về học ai.

Agent SDK dùng chung phần ruột với Claude Code: cùng vòng lặp agent, cùng bộ công cụ đọc ghi file và chạy lệnh. Khác biệt nằm ở chỗ ai điều khiển. Với Claude Code, bạn ngồi gõ từng yêu cầu. Với SDK, code của bạn quyết định agent nhận việc gì, được dùng công cụ nào, giới hạn quyền tới đâu, và chạy được trên server không màn hình, không cần ai đăng nhập.

Các bước dựng một agent tối giản

• 1. Cài SDK vào dự án Python hoặc TypeScript, tuỳ ngôn ngữ đang dùng.
• 2. Định nghĩa tool: mỗi tool là một hàm cụ thể agent được phép gọi, ví dụ đọc file, gọi API nội bộ, hay ghi vào database. Càng mô tả rõ tool làm gì, agent càng gọi đúng lúc.
• 3. Viết prompt hệ thống mô tả vai trò và giới hạn của agent: việc nào được làm, việc nào phải dừng lại hỏi người dùng.
• 4. Chạy vòng lặp và log lại từng bước agent thực hiện trong lúc test, để biết agent đang nghĩ gì trước khi tin tưởng để nó chạy không giám sát.
• 5. Triển khai thành dịch vụ: chạy như một cron job, một worker nền, hoặc một endpoint API tuỳ nhu cầu, sau khi đã test đủ kỹ với dữ liệu thật.

Một agent Python tối giản trông thế này:

from claude_agent_sdk import query, ClaudeAgentOptions

options = ClaudeAgentOptions(
    system_prompt="Ban la tro ly kiem tra don hang. Chi doc du lieu, khong sua file.",
    allowed_tools=["Read", "Grep"],
)

async for message in query(
    prompt="Doc file orders.csv va tom tat don hang moi hom nay",
    options=options,
):
    print(message)

Đoạn trên giao cho agent một việc và một hàng rào: chỉ được đọc và tìm kiếm trong file, không được ghi hay chạy lệnh. Trong phạm vi đó, agent tự quyết mở file nào, đọc phần nào, lặp bao nhiêu bước, rồi trả kết quả về cho code của bạn xử lý tiếp, ví dụ gửi báo cáo vào nhóm chat nội bộ.

SDK cho sẵn những gì để đỡ tự viết

Điểm đáng tiền nhất của SDK là bạn không phải tự dựng hạ tầng agent: vòng lặp, công cụ và cơ chế quyền đều có sẵn.

• Bộ công cụ dựng sẵn: đọc ghi file, tìm kiếm, chạy lệnh hệ thống, những thứ nếu tự viết từ đầu sẽ ngốn nhiều tuần.
• Cơ chế quyền theo từng công cụ: cho phép, chặn, hoặc bắt hỏi xác nhận trước những hành động nhạy cảm.
• Nối được MCP server để thêm công cụ ngoài như database hay lịch làm việc; cách chuẩn này hoạt động có trong bài MCP là gì và cách nối Claude với công cụ ngoài.
• Chia việc cho nhiều agent con chạy song song khi tác vụ lớn, tương tự cách chia việc bằng sub-agent trong Claude Code.
• Hook để chèn bước kiểm tra tự động trước và sau mỗi lần agent gọi công cụ, ví dụ chặn mọi thao tác đụng tới thư mục cấm.

Tình huống dùng thật

Ba kiểu agent mình thấy đáng dựng sớm nhất với người làm kinh doanh nhỏ:

• Báo cáo sáng: cron job 6 giờ chạy agent đọc dữ liệu đơn hàng hôm trước, tóm tắt biến động rồi gửi vào nhóm chat. Cả team chỉ việc đọc, không ai phải mở máy sớm.
• Bot tra cứu nội bộ: agent đọc kho tài liệu quy trình, trả lời câu hỏi của nhân viên qua một endpoint, đỡ leader trả lời lặp đi lặp lại.
• Dọn dữ liệu định kỳ: agent rà file mới trong thư mục dùng chung, đổi tên sai chuẩn, gom báo cáo về đúng chỗ, ghi log lại những gì đã làm.

Lỗi hay gặp khi mới xây agent

• Cấp quyền rộng ngay từ đầu cho tiện test: thói quen này theo lên môi trường thật lúc nào không hay. Bắt đầu bằng quyền chỉ đọc.
• Prompt hệ thống mơ hồ: agent lan man, gọi tool lung tung. Ghi rõ việc được làm và việc phải dừng lại chờ người quyết.
• Không log từng bước: khi kết quả sai, bạn không biết agent đã đọc gì, gọi gì, rẽ nhầm ở đâu để sửa.
• Quên trần chi phí: agent lặp nhiều bước tốn token hơn hẳn một câu hỏi thường. Đặt giới hạn số vòng, và bật cache cho phần ngữ cảnh lặp lại theo hướng dẫn trong bài prompt caching giảm chi phí gọi API Claude.
• Test bằng dữ liệu giả quá sạch: vào dữ liệu thật thiếu cột, sai định dạng là gãy ngay. Cho agent va bản sao dữ liệu thật càng sớm càng tốt.

Giới hạn quyền là bước không được bỏ qua

Một agent chạy tự động không có người giám sát trực tiếp mỗi lệnh, nên phải giới hạn rõ tool nào được gọi và dữ liệu nào được ghi. Đừng cấp quyền ghi vào database sản xuất cho một agent còn đang thử nghiệm. Luôn chạy trên môi trường test trước, theo dõi log vài ngày rồi mới đưa vào sản xuất.

Nếu agent cần thao tác trực tiếp trên máy tính thay vì chỉ gọi API, xem thêm Computer Use: để Claude tự thao tác trên máy tính để hiểu thêm giới hạn và rủi ro riêng của hướng đó.

Chọn Claude Code, Agent SDK hay gọi API thường

Chốt theo ba câu hỏi: ai ngồi điều khiển, việc có lặp lại không, và có cần nhiều bước không.

• Dùng Claude Code nếu: bạn trực tiếp ngồi làm, mỗi lần một việc khác nhau, cần trao đổi qua lại liên tục.
• Dùng Agent SDK nếu: việc lặp lại theo lịch hoặc theo sự kiện, cần chạy nền như một dịch vụ, không có người ngồi cạnh.
• Gọi API thường nếu: chỉ cần một câu trả lời cho một đầu vào, không cần agent tự gọi tool nhiều bước.

Bước tiếp theo

Chọn đúng một việc bạn đang làm tay mỗi sáng, dựng agent bản chỉ đọc cho việc đó, rồi cho nó chạy song song với quy trình tay trọn một tuần. Khớp kết quả cả tuần rồi hãy cấp quyền ghi. Cách vào nghề chậm mà chắc này giúp bạn tin agent vì đã tự kiểm chứng, chứ đừng tin vì demo chạy được một lần.