Dựng agent với Claude - tự viết vòng lặp, Agent SDK hay Managed Agents

Quyết định "làm agent" xong, câu hỏi tiếp theo là dựng nó bằng gì. Bạn có thể tự viết vòng lặp gọi API, dùng một thư viện lo sẵn vòng lặp, hoặc để Anthropic chạy luôn cả agent.

Bài này giúp bạn trả lời: mỗi cách dựng agent lo sẵn phần nào, agent chạy ở đâu, và việc gì phải giao cho hook thay vì prompt?

Ví dụ xuyên suốt: agent điều tra sự cố của công ty hosting

Một công ty hosting nhỏ quản lý khoảng 400 máy chủ cho khách. Mỗi đêm có vài cảnh báo: ổ đĩa sắp đầy, dịch vụ web trả lỗi 502, chứng chỉ TLS sắp hết hạn. Đội vận hành muốn một agent tự điều tra trước: đọc log, chạy vài lệnh chẩn đoán chỉ đọc, rồi viết báo cáo kèm đề xuất cách sửa cho người trực sáng hôm sau.

Hai yêu cầu cứng: agent không bao giờ được khởi động lại dịch vụ hay xoá file trên máy của khách, và mỗi lần điều tra không được tốn quá một mức chi phí cố định.

Ba cách dựng, khác nhau ở chỗ ai làm gì

Trang tổng quan Agent SDK so sánh các cách dựng agent với Claude theo ba điểm: ai chạy agent, cái gì có sẵn, và bạn gọi nó bằng cách nào.

Tự viết vòng lặp với Client SDK nghĩa là viết đúng cái khuôn docs mô tả: gửi yêu cầu kèm danh sách tool; khi stop_reason là "tool_use" thì chạy tool, gửi kết quả về trong khối tool_result, rồi gọi tiếp; dừng khi stop_reason là giá trị khác. Cách này hợp khi bạn cần kiểm soát từng bước, hoặc agent chỉ dùng tool của riêng bạn.

Docs Agent SDK cũng nhắc: muốn dùng cùng vòng lặp đó từ ngôn ngữ khác Python, TypeScript thì chạy Claude Code CLI như một process con với cờ -p và --output-format json.

Với agent điều tra sự cố, đội chọn Agent SDK: agent cần chạy lệnh shell và đọc file log, mà Agent SDK có sẵn các tool đó cùng cơ chế quyền và hook.

Agent SDK lo sẵn những gì

Một lần gọi query() của Agent SDK chạy trọn vòng lặp: Claude nhận prompt, gọi tool, SDK chạy tool và gửi kết quả về, lặp lại cho tới khi Claude trả lời bằng chữ mà không gọi tool nữa. Cuối cùng SDK trả một ResultMessage có kết quả, số token, chi phí và session ID.

Bạn điều khiển vòng lặp bằng các tuỳ chọn, ví dụ trong Python:

Yêu cầu "không tốn quá một mức chi phí" của ví dụ ứng với max_budget_usd. Docs lưu ý SDK so chi phí sau khi mỗi phản hồi về, nên tổng có thể vượt mức đặt một chút: hãy chừa khoảng trống. Luôn kiểm subtype của ResultMessage trước khi đọc kết quả, vì trường result chỉ có khi subtype là success.

Đội cũ của công ty từng tự viết lớp thử lại và lưu lịch sử riêng trước khi chuyển sang Agent SDK. Không nên gỡ hết hay giữ hết. Xem từng tuỳ chỉnh: ngày trước thêm nó vì lý do gì, và SDK bây giờ đã làm được việc đó chưa.

Agent chạy ở đâu

Đề thi hỏi về mô hình triển khai agent tự host hay do Anthropic host (self-hosted vs. Anthropic-hosted). Có ba khả năng:

Managed Agents xoay quanh bốn khái niệm:

• Agent: model, system prompt, tool, MCP server và skill. Tạo một lần, dùng lại bằng ID.
• Environment: nơi session chạy, sandbox trên cloud hoặc sandbox tự host.
• Session: một lần agent chạy trong một environment để làm một việc.
• Events: tin nhắn qua lại giữa ứng dụng và agent (lượt người dùng, kết quả tool, cập nhật trạng thái), trả về dạng server-sent events.

Docs nói Managed Agents hợp với việc chạy lâu (vài phút tới vài giờ), chạy bất đồng bộ, cần session có trạng thái, hoặc chạy theo lịch. Sandbox tự host dùng khi cần giữ việc chạy tool, file và lưu lượng mạng trong hạ tầng của mình, ví dụ vì yêu cầu tuân thủ hay nơi lưu dữ liệu. Vài điều cần biết: Managed Agents đang beta, mọi endpoint cần header managed-agents-2026-04-01 (SDK tự gửi), và vì session lưu ở server nên không áp dụng được Zero Data Retention.

Nếu sau này công ty muốn agent điều tra chạy theo lịch mỗi đêm mà không phải nuôi máy chạy agent, Managed Agents với sandbox tự host là hướng hợp lý: Anthropic chạy vòng lặp, còn lệnh chẩn đoán vẫn chạy trong mạng nội bộ của công ty.

1. Cần kiểm soát từng lần gọi, hoặc chỉ dùng tool của riêng mình?Client SDK, tự viết vòng lặp
2. Muốn tool, quyền, hook có sẵn và tự vận hành process?Agent SDK
3. Việc chạy lâu, bất đồng bộ, không muốn nuôi hạ tầng agent?Managed Agents
4. Tool phải chạy trong mạng của mình?Managed Agents với sandbox tự host
5. Còn lạiBắt đầu từ cách ít hạ tầng nhất đáp ứng yêu cầu

Hook cho những việc phải xảy ra chắc chắn

Prompt có thể dặn "đừng khởi động lại dịch vụ", nhưng đó chỉ là lời dặn; model có thể không làm theo. Đề thi gọi đây là dùng hook cho hành động tất định (hooks for deterministic actions). Hook là hàm của bạn, SDK gọi nó ở những thời điểm cố định, như ngay trước khi một tool chạy (PreToolUse) hay sau khi tool chạy xong (PostToolUse). Hook PreToolUse có thể trả quyết định "deny" để chặn lời gọi tool, bất kể model muốn gì.

Agent điều tra sự cố dùng một hook chặn lệnh nguy hiểm:

async def chan_lenh_nguy_hiem(input_data, tool_use_id, context):
    lenh = input_data["tool_input"].get("command", "")
    if "systemctl restart" in lenh or "rm " in lenh:
        return {
            "hookSpecificOutput": {
                "hookEventName": input_data["hook_event_name"],
                "permissionDecision": "deny",
                "permissionDecisionReason": "Agent chỉ được chạy lệnh chẩn đoán",
            }
        }
    return {}

options = ClaudeAgentOptions(
    max_budget_usd=2.0,
    hooks={"PreToolUse": [HookMatcher(matcher="Bash", hooks=[chan_lenh_nguy_hiem])]},
)

matcher lọc theo tên tool, ở đây chỉ chạy hook với tool Bash. Docs nói khi nhiều hook PreToolUse trả quyết định khác nhau thì deny thắng. Hook so chuỗi đơn giản như trên chỉ là ví dụ; ở môi trường thật, nên kết hợp với danh sách lệnh được phép và chạy agent trong sandbox. Hook PostToolUse hợp với việc ghi lại mọi lệnh đã chạy vào nhật ký kiểm tra.