Hook Trong Agent SDK

Những điều bạn cần biết

Hook trong Agent SDK là cơ chế để đưa hành vi tất định vào một hệ thống vốn mang tính xác suất. Chúng nằm ở ranh giới giữa các quyết định của model và thế giới thực, can thiệp vào các lệnh gọi tool và kết quả để thực thi các quy tắc nghiệp vụ và chuẩn hóa dữ liệu. Task statement này kết nối trực tiếp với dải phổ thực thi từ mục 1.4 — hook chính là cách bạn triển khai việc thực thi bằng lập trình trên thực tế.

Hai Loại Hook

Agent SDK cung cấp hook tại hai điểm trong vòng đời thực thi tool:

PostToolUse hook chạy sau khi tool thực thi nhưng trước khi model xử lý kết quả. Chúng can thiệp vào kết quả của tool và biến đổi chúng trước khi model nhìn thấy. Model nhận được dữ liệu sạch, đã chuẩn hóa bất kể tool nào tạo ra nó.

PreToolUse hook (đôi khi được mô tả là can thiệp lệnh gọi tool) chạy trước khi tool thực thi. Chúng can thiệp vào lệnh gọi tool đang gửi đi và có thể chặn nó, sửa đổi nó, hoặc chuyển hướng nó sang một quy trình thay thế. Tool sẽ không bao giờ chạy nếu hook quyết định chặn nó.

Khái niệm chính

PostToolUse hook biến đổi dữ liệu sau khi thực thi. PreToolUse hook thực thi chính sách trước khi thực thi. Hãy nắm rõ hướng hoạt động của từng hook — kỳ thi kiểm tra sự phân biệt này.

PostToolUse Hook: Chuẩn Hóa Dữ Liệu

Các tool MCP khác nhau trả về dữ liệu ở các định dạng khác nhau. Một cơ sở dữ liệu khách hàng có thể trả về Unix timestamp (1710489600). Một hệ thống quản lý đơn hàng có thể trả về ngày theo ISO 8601 ("2024-03-15T12:00:00Z"). Một status API có thể trả về mã số (200, 404, 500) trong khi một API khác trả về chuỗi ("active", "cancelled", "pending").

Nếu không có chuẩn hóa, model phải diễn giải các định dạng không đồng nhất này ở mỗi lượt lặp. Điều này gây ra sự không nhất quán — model có thể phân tích đúng một Unix timestamp lần này nhưng diễn giải sai lần sau.

Một PostToolUse hook giải quyết điều này bằng cách chuẩn hóa mọi định dạng trước khi model xử lý chúng:

Unix timestamp → ngày ISO 8601
Mã trạng thái dạng số → chuỗi dễ đọc cho con người
Giá trị tiền tệ → định dạng thập phân nhất quán kèm mã tiền tệ
Chuỗi ngày ở nhiều định dạng khu vực khác nhau → một định dạng chuẩn duy nhất

Model luôn nhận được dữ liệu sạch, nhất quán, bất kể tool hay hệ thống backend nào đã tạo ra nó.

PreToolUse Hook: Thực Thi Chính Sách

PreToolUse hook là cơ chế triển khai cho các cổng điều kiện tiên quyết được mô tả trong mục 1.4. Chúng can thiệp vào các lệnh gọi tool đang gửi đi trước khi thực thi và áp dụng các quy tắc nghiệp vụ:

Trường hợp sử dụng: Thực thi ngưỡng hoàn tiền. Một hook can thiệp mọi lệnh gọi đến process_refund. Nếu số tiền hoàn vượt quá 500 đô la, hook chặn lệnh gọi và chuyển hướng đến một quy trình leo thang cho con người. Tool hoàn tiền không bao giờ thực thi — hook ngăn chặn nó trước khi nó có thể chạy.

Trường hợp sử dụng: Cổng điều kiện tiên quyết tuân thủ. Một hook can thiệp các lệnh gọi đến transfer_funds. Nếu kiểm tra chống rửa tiền (AML) bắt buộc chưa được hoàn thành cho phiên này, hook chặn lệnh gọi và trả về thông báo lỗi hướng dẫn agent hoàn thành kiểm tra AML trước.

Trường hợp sử dụng: Quy trình phê duyệt của quản lý. Một hook can thiệp các lệnh gọi đến approve_discount cho các mức giảm giá trên 20%. Hook tạm dừng thực thi và định tuyến yêu cầu đến hàng đợi phê duyệt của quản lý. Chỉ sau khi quản lý phê duyệt, tool mới thực thi.

Bẫy thi: Exam Trap

Kỳ thi sẽ trình bày PostToolUse hook như một giải pháp để chặn các hành động vi phạm chính sách. Điều này sai. PostToolUse chạy sau khi thực thi — vào thời điểm nó kích hoạt, hành động không tuân thủ đã xảy ra rồi. Hãy dùng PreToolUse hook (trước khi thực thi) để chặn các hành động trước khi chúng xảy ra.

Khung Ra Quyết Định

Khung này là mô hình tư duy cốt lõi cho kỳ thi:

Yêu cầu	Cơ chế	Bảo đảm
Phải được tuân thủ 100% thời gian	Hook	Tất định
Được ưu tiên nhưng thỉnh thoảng sai lệch có thể chấp nhận được	Prompt	Xác suất

Nếu doanh nghiệp sẽ mất tiền vì một lần thất bại duy nhất → hãy dùng hook. Nếu doanh nghiệp sẽ đối mặt với rủi ro pháp lý vì một lần thất bại duy nhất → hãy dùng hook. Nếu đó chỉ là sở thích định dạng hoặc hướng dẫn phong cách → hướng dẫn dựa trên prompt là phù hợp.

Kỳ thi luôn trình bày các giải pháp dựa trên prompt như các phương án gây nhiễu cho những tình huống đòi hỏi thực thi tất định. Quyết định không nằm ở việc prompt có "đủ tốt" hay không — mà nằm ở việc hậu quả của một lần thất bại duy nhất có đáng để đảm bảo tính tất định hay không.

Hook so với Prompt: So Sánh Song Song

Tình huống: Chuyển khoản quốc tế phải vượt qua kiểm tra AML.

Cách tiếp cận bằng prompt: "Luôn hoàn thành xác minh AML trước khi xử lý chuyển khoản quốc tế." Hoạt động đúng 95% thời gian. Tỷ lệ thất bại 5% có nghĩa là một số giao dịch chuyển khoản bỏ qua kiểm tra AML — một vi phạm quy định.
Cách tiếp cận bằng hook: Một PreToolUse hook chặn transfer_funds cho đến khi aml_check trả về kết quả đạt. Hoạt động đúng 100% thời gian. Không giao dịch chuyển khoản nào có thể thực thi mà không có xác minh AML.

Tình huống: Các phản hồi nên được định dạng bằng markdown.

Cách tiếp cận bằng prompt: "Định dạng mọi phản hồi bằng markdown với tiêu đề và gạch đầu dòng." Hoạt động đúng hầu hết thời gian. Thỉnh thoảng có phản hồi dạng văn bản thuần không phải là rủi ro kinh doanh.
Cách tiếp cận bằng hook: Chi phí không cần thiết. Sở thích định dạng không cần thực thi tất định.

Tình huống: Hoàn tiền trên 500 đô la yêu cầu con người phê duyệt.

Cách tiếp cận bằng prompt: "Đối với các khoản hoàn tiền trên 500 đô la, hãy leo thang cho một agent con người." Hoạt động đúng hầu hết thời gian. Một lần thất bại duy nhất có nghĩa là một khoản hoàn tiền lớn được xử lý mà không có phê duyệt.
Cách tiếp cận bằng hook: Can thiệp process_refund, kiểm tra số tiền, chặn nếu trên 500 đô la và định tuyến đến leo thang cho con người. Hoạt động đúng 100% thời gian.

Ví Dụ Thực Tế: Hỗn Loạn Định Dạng Dữ Liệu

Một agent hỗ trợ khách hàng sử dụng ba tool MCP:

get_customer trả về ngày dưới dạng Unix timestamp và trạng thái dưới dạng mã số.
lookup_order trả về ngày dưới dạng chuỗi ISO 8601 và trạng thái dưới dạng chuỗi tiếng Anh.
check_shipping trả về ngày dưới dạng "DD/MM/YYYY" và trạng thái dưới dạng mã một ký tự ("S" cho đã giao, "P" cho đang chờ).

Nếu không có PostToolUse hook, model phải diễn giải ba định dạng ngày khác nhau và ba cách biểu diễn trạng thái khác nhau ở mỗi lượt lặp. Đôi khi nó chuyển đổi đúng một Unix timestamp; đôi khi nó nhầm lẫn thứ tự ngày/tháng trong "DD/MM/YYYY"; đôi khi nó diễn giải sai "P" là "đã xử lý" thay vì "đang chờ".

Với một PostToolUse hook, mọi kết quả tool đều được chuẩn hóa trước khi model nhìn thấy chúng:

Mọi ngày → ISO 8601 ("2024-03-15T12:00:00Z")
Mọi mã trạng thái → chuỗi dễ đọc cho con người ("shipped", "pending", "delivered")

Model luôn nhận được dữ liệu nhất quán, loại bỏ hoàn toàn các lỗi diễn giải.

Bẫy thi

Bẫy thi: Using PostToolUse hooks to block policy-violating actions

PostToolUse hook chạy sau khi tool thực thi. Vào thời điểm hook kích hoạt, hành động không tuân thủ đã được xử lý rồi. Hãy dùng PreToolUse hook (trước khi thực thi) để chặn các hành động trước khi chúng xảy ra.

Bẫy thi: Enhanced prompt instructions as the solution for 100% compliance requirements

Prompt cung cấp sự tuân thủ mang tính xác suất. Nếu doanh nghiệp yêu cầu thực thi 100% (các nghiệp vụ tài chính, tuân thủ quy định, kiểm tra bảo mật), chỉ hook mới cung cấp bảo đảm tất định.

Bẫy thi: Suggesting model-side data transformation instead of PostToolUse hooks for normalisation

Dựa vào model để chuẩn hóa các định dạng dữ liệu không đồng nhất gây ra sự không nhất quán. PostToolUse hook đảm bảo dữ liệu sạch, nhất quán đến được với model mỗi lần, bất kể tool nào đã tạo ra nó.

Bẫy thi: Confusing the direction of hooks — PostToolUse runs after execution, PreToolUse runs before

PostToolUse biến đổi kết quả sau khi một tool chạy. PreToolUse chặn hoặc sửa đổi lệnh gọi trước khi một tool chạy. Dùng sai hướng hook nghĩa là hoặc bỏ lỡ cơ hội ngăn chặn một hành động hoặc chặn một cách không cần thiết công việc đã hoàn thành.

Tình huống luyện tập

Không tìm thấy câu hỏi luyện tập "q-1-5-001".

Bài tập thực hành

Triển Khai Hook Trong Agent SDK Để Chuẩn Hóa Và Thực Thi Chính Sách

Bạn sẽ học được gì

Sự khác biệt giữa PostToolUse hook (sau khi thực thi, chuẩn hóa dữ liệu) và PreToolUse hook (trước khi thực thi, thực thi chính sách)
Vì sao hook cung cấp bảo đảm tất định mà prompt không thể sánh được
Cách chuẩn hóa các định dạng dữ liệu không đồng nhất từ nhiều tool MCP thành một schema nhất quán
Cách triển khai thực thi chính sách dựa trên ngưỡng và điều kiện tiên quyết bằng cách dùng hook trước khi thực thi
Khung ra quyết định: hook cho các yêu cầu 100%, prompt cho các sở thích

Các bước

Vì sao: Điều này tái tạo lại ví dụ hỗn loạn định dạng dữ liệu từ kỳ thi. Nếu không có chuẩn hóa, model phải diễn giải ba định dạng ngày khác nhau và ba cách biểu diễn trạng thái khác nhau, dẫn đến việc phân tích không nhất quán qua các lượt lặp.

Bạn sẽ thấy: Ba cách triển khai tool, mỗi cái trả về dữ liệu với định dạng ngày và trạng thái riêng biệt. Tool A dùng epoch giây và mã số, Tool B dùng chuỗi ISO và trạng thái tiếng Anh, Tool C dùng DD/MM/YYYY và một ký tự.

Vì sao: PostToolUse hook chạy sau khi thực thi nhưng trước khi model xử lý kết quả. Đây là hướng hook đúng cho việc chuẩn hóa dữ liệu — kỳ thi kiểm tra xem bạn có biết rằng PostToolUse biến đổi dữ liệu sau khi thực thi, chứ không phải trước đó hay không.

Bạn sẽ thấy: Một hàm hook phát hiện định dạng của từng trường và chuyển đổi nó: Unix timestamp thành ISO 8601, DD/MM/YYYY thành ISO 8601, mã trạng thái dạng số thành chuỗi tiếng Anh, và mã một ký tự thành từ đầy đủ.

Vì sao: Dữ liệu nhất quán loại bỏ các lỗi diễn giải. Nếu không có chuẩn hóa, model có thể nhầm lẫn thứ tự ngày/tháng trong DD/MM/YYYY hoặc diễn giải sai mã trạng thái P là đã xử lý thay vì đang chờ. Bước xác minh chứng minh hook hoạt động trên toàn bộ đầu ra của các tool.

Bạn sẽ thấy: Ba kết quả tool đều dùng ngày ISO 8601 và chuỗi trạng thái tiếng Anh, bất kể tool nào đã tạo ra chúng. Phản hồi của model nên tham chiếu ngày và trạng thái một cách nhất quán mà không nhầm lẫn.

Vì sao: Một PreToolUse hook chạy trước khi thực thi — khoản hoàn tiền không bao giờ được xử lý. Kỳ thi cảnh báo cụ thể về việc dùng PostToolUse để chặn, bởi vì đến lúc đó hành động đã xảy ra rồi. Can thiệp trước khi thực thi là hướng hook đúng duy nhất cho việc thực thi chính sách.

Bạn sẽ thấy: Một hook trước khi thực thi kiểm tra các lệnh gọi process_refund, kiểm tra tham số số tiền, và chặn lệnh gọi kèm thông báo chuyển hướng nếu số tiền vượt quá 500. Tool hoàn tiền không bao giờ thực thi đối với các lệnh gọi bị chặn.

Vì sao: Đây là tình huống tuân thủ AML từ kỳ thi. Hướng dẫn bằng prompt đạt được 95% tuân thủ, nhưng các yêu cầu quy định đòi hỏi 100%. Hook cung cấp sự thực thi tất định mà không prompt nào có thể sánh được — một lần bỏ sót kiểm tra AML duy nhất có thể dẫn đến các hình phạt pháp lý.

Bạn sẽ thấy: Một hook trước khi thực thi kiểm tra trạng thái phiên để tìm một kiểm tra AML đã hoàn thành trước khi cho phép transfer_funds thực thi. Nếu không có aml_check đạt trước đó, giao dịch chuyển khoản bị chặn kèm một thông báo lỗi mô tả rõ.

Vì sao: Việc kiểm thử xác nhận rằng các hook cung cấp sự thực thi tất định. Điểm xác minh then chốt là các tool bị chặn không bao giờ thực thi — hook ngăn chặn lệnh gọi, chứ không chỉ ghi log cảnh báo sau khi sự việc đã xảy ra.

Bạn sẽ thấy: Cả hai thao tác bị chặn đều trả về thông báo can thiệp mà không có tool cơ bản nào thực thi. Sau khi đáp ứng các điều kiện tiên quyết (hoàn thành kiểm tra AML, giảm số tiền hoàn), các thao tác thành công.

Nguồn tham khảo

Claude Agent SDK Overview — Anthropic
Claude Agent SDK Hooks Documentation — Anthropic
Building with Claude API (Skilljar) — Anthropic