1.5 Agent SDK Hooks

Những gì cần nắm

Agent SDK hook tiêm hành vi tất định vào một hệ thống vốn mang bản chất xác suất. Chúng nằm đúng ranh giới giữa quyết định của model và thế giới thật, chặn tool call và tool result để cưỡng chế business rule và chuẩn hóa dữ liệu. Nhớ phổ cưỡng chế ở bài 1.4 chứ? Hook chính là cách bạn hiện thực hóa phía “bằng code” của phổ đó.

Hai loại hook

Agent SDK cung cấp hook ở 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 chặn tool result và biến đổi nó 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à tool-call interception) chạy trước khi tool thực thi. Chúng chặn lời gọi tool đi ra và có thể chặn hẳn, sửa lại, hoặc chuyển hướng sang một workflow khác. Tool không bao giờ chạy nếu hook quyết định chặn.

Mỗi hook trả về gì. Trong Agent SDK, PreToolUse hook trả lời bằng permissionDecision với giá trị allow, deny, ask hoặc defer, kèm updatedInput tùy chọn để viết lại tham số của tool trước khi nó chạy. PostToolUse hook có thể đặt updatedToolOutput để thay thế thứ model nhìn thấy, áp dụng cho cả built-in tool lẫn MCP tool. Trường cũ updatedMCPToolOutput chỉ áp cho MCP tool và đã deprecated. Có một điều không trường nào đổi được: tới lúc PostToolUse kích hoạt thì tool đã chạy rồi, nên chặn ở đó dừng được vòng lặp nhưng không hoàn tác được side effect. (Agent SDK hooks guide, kiểm tra tháng 9/2026.)

PostToolUse hook: chuẩn hóa dữ liệu

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

Không chuẩn hóa thì model phải tự diễn giải mớ định dạng hỗn tạp này ở mọi vòng lặp. Điều đó đẻ ra sự thiếu nhất quán. Lần này nó parse đúng một Unix timestamp, lần sau nó đọc sai.

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

Unix timestamp thành ngày ISO 8601
Mã trạng thái dạng số thành chuỗi người đọc được
Giá trị tiền tệ thành định dạng thập phân thống nhất kèm mã tiền tệ
Chuỗi ngày theo các quy ước vùng miền khác nhau thành một định dạng chuẩn duy nhất

Model luôn nhận dữ liệu sạch và nhất quán, bất kể tool hay hệ backend nào tạo ra nó.

PreToolUse hook: cưỡng chế chính sách

PreToolUse hook là cơ chế hiện thực các prerequisite gate mô tả ở bài 1.4. Chúng chặn lời gọi tool đi ra trước khi thực thi và áp business rule:

Tình huống: ngưỡng hoàn tiền. Một hook chặn mọi lời gọi tới process_refund. Nếu số tiền hoàn vượt 500 USD, hook chặn lời gọi và chuyển sang workflow escalate lên người thật. Tool hoàn tiền không bao giờ chạy — hook đã chặn trước khi nó kịp chạy.

Tình huống: prerequisite gate cho tuân thủ. Một hook chặn lời gọi tới transfer_funds. Nếu bước kiểm tra chống rửa tiền (AML) chưa hoàn tất cho session này, hook chặn lời gọi và trả về lỗi yêu cầu agent làm AML check trước.

Tình huống: workflow phê duyệt của quản lý. Một hook chặn lời gọi approve_discount với mức chiết khấu trên 20%. Hook tạm dừng thực thi và đẩy yêu cầu vào hàng đợi phê duyệt của quản lý. Chỉ sau khi quản lý duyệt thì tool mới chạy.

Khung 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ế	Mức đảm bảo
Phải được tuân thủ 100% số lần	Hook	Tất định
Ưu tiên tuân thủ, nhưng lệch thỉnh thoảng thì chấp nhận được	Prompt	Xác suất

Nếu một lần lỗi làm doanh nghiệp mất tiền → dùng hook. Nếu một lần lỗi đẩy doanh nghiệp vào rủi ro pháp lý → dùng hook. Nếu đó là sở thích định dạng hay style guideline → hướng dẫn bằng prompt là đủ.

Đề thi thường xuyên đặt giải pháp dạng prompt làm mồi nhử cho các tình huống đòi cưỡng chế tất định. Quyết định ở đây không phải là prompt “đủ tốt hay chưa” — mà là hậu quả của một lần lỗi có đáng để đòi đảm bảo tất định hay không.

Hook và prompt đặt cạnh nhau

Tình huống: chuyển khoản quốc tế phải qua AML check.

Hướng prompt: “Luôn hoàn tất xác minh AML trước khi xử lý chuyển khoản quốc tế.” Đúng 95% số lần. 5% còn lại nghĩa là có những giao dịch bỏ qua AML check — vi phạm quy định.
Hướng hook: một PreToolUse hook chặn transfer_funds cho tới khi aml_check trả về pass. Đúng 100% số lần. Không giao dịch nào chạy được mà chưa xác minh AML.

Tình huống: response nên được định dạng bằng markdown.

Hướng prompt: “Định dạng mọi response bằng markdown với heading và bullet.” Đúng phần lớn thời gian. Thỉnh thoảng lòi ra plain text cũng không phải rủi ro kinh doanh.
Hướng hook: overhead không cần thiết. Sở thích định dạng không đòi cưỡng chế tất định.

Tình huống: hoàn tiền trên 500 USD cần người duyệt.

Hướng prompt: “Với khoản hoàn trên 500 USD, escalate lên nhân viên người thật.” Đúng phần lớn thời gian. Một lần lỗi nghĩa là một khoản hoàn lớn được xử lý không qua duyệt.
Hướng hook: chặn process_refund, kiểm tra số tiền, chặn nếu trên 500 USD và đẩy sang escalate lên người thật. Đúng 100% số lần.

Ví dụ thực tế: loạn định dạng dữ liệu

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

get_customer trả ngày dưới dạng Unix timestamp và trạng thái dưới dạng mã số.
lookup_order trả 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ả ngày dạng “DD/MM/YYYY” và trạng thái dạng mã một ký tự (“S” là shipped, “P” là pending).

Không có PostToolUse hook, model phải diễn giải ba định dạng ngày và ba cách biểu diễn trạng thái ở mọi vòng lặp. Lúc thì nó chuyển đúng Unix timestamp; lúc thì nó lẫn thứ tự ngày/tháng trong “DD/MM/YYYY”; lúc thì nó hiểu “P” thành “processed” thay vì “pending”.

Có PostToolUse hook, mọi tool result được chuẩn hóa trước khi model nhìn thấy:

Mọi ngày thành ISO 8601 (“2024-03-15T12:00:00Z”)
Mọi mã trạng thái thành chuỗi người đọc được (“shipped”, “pending”, “delivered”)

Model luôn nhận dữ liệu nhất quán, triệt tiêu hoàn toàn lỗi diễn giải.

Bẫy thi

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

Một agent thỉnh thoảng xử lý chuyển khoản quốc tế mà thiếu bước kiểm tra tuân thủ bắt buộc. Đội compliance yêu cầu cưỡng chế 100% việc kiểm tra chống rửa tiền (AML) trước mọi giao dịch quốc tế. Hệ thống hiện tại dùng chỉ thị trong prompt, đúng khoảng 95% số lần. Cách làm đúng là gì?

A. Cài PreToolUse hook chặn tool transfer_funds cho tới khi aml_check trả về kết quả pass đã xác minh
B. Thêm chỉ thị AML chi tiết vào system prompt kèm ví dụ về hành vi đúng và cảnh báo rõ về chế tài khi vi phạm
C. Thêm PostToolUse hook đánh dấu mọi giao dịch đã hoàn tất mà bỏ qua AML check rồi đẩy vào hàng đợi cho đội compliance rà tay
D. Huấn luyện agent bằng ví dụ few-shot minh họa đúng quy trình xác minh AML trước mỗi giao dịch

Đáp án & giải thích

Đúng: A

A — PreToolUse hook chặn lời gọi tool đi ra trước khi thực thi và chặn vật lý cho tới khi AML check pass. Đây là mức đảm bảo tất định 100% mà quy định pháp lý đòi hỏi. Không giao dịch nào chạy được khi chưa xác minh.
B — Chỉ thị prompt gắt hơn có thể nâng từ 95% lên 97–98% nhưng không chạm được 100%. Với quy định AML, chỉ một lần bỏ sót cũng có thể dẫn tới chế tài nặng. Cải thiện xác suất là không đủ cho yêu cầu pháp lý.
C — PostToolUse hook chạy sau khi thực thi. Tới lúc hook phát hiện thiếu AML check thì giao dịch vi phạm đã được xử lý xong. Tuân thủ pháp lý đòi ngăn chặn, không phải phát hiện sau.
D — Few-shot nâng độ chính xác nhưng vẫn là xác suất. Nó không đảm bảo được 100%. Yêu cầu pháp lý về AML đòi cưỡng chế tất định mà chỉ hook mới cho được.

Nguồn

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

Exam Simulator

Năm câu trắc nghiệm theo format đề thi về Agent SDK Hooks. Chọn đáp án trước, rồi mở phần giải thích.

Câu 1

Một agent thỉnh thoảng xử lý chuyển khoản quốc tế mà thiếu bước kiểm tra tuân thủ bắt buộc. Đội compliance yêu cầu cưỡng chế 100% việc kiểm tra AML trước mọi giao dịch quốc tế. Hệ thống hiện tại dùng chỉ thị trong prompt, đúng khoảng 95% số lần. Cách làm đúng là gì?

A. Thêm chỉ thị AML chi tiết vào system prompt kèm ví dụ về hành vi đúng và cảnh báo rõ về chế tài khi vi phạm
B. Thêm PostToolUse hook đánh dấu các giao dịch đã hoàn tất mà bỏ qua AML check để rà tay
C. Cài PreToolUse hook chặn tool transfer_funds cho tới khi aml_check trả về kết quả pass đã xác minh
D. Huấn luyện agent bằng ví dụ few-shot minh họa đúng quy trình xác minh AML trước mỗi giao dịch

Đáp án & giải thích

Đúng: C

C đúng vì PreToolUse hook chặn lời gọi tool đi ra trước khi thực thi và chặn vật lý cho tới khi AML check pass. Đây là mức đảm bảo tất định 100% mà quy định pháp lý đòi hỏi. Không giao dịch nào chạy được khi chưa xác minh.
A sai vì chỉ thị prompt gắt hơn có thể nâng từ 95% lên 97–98% nhưng không chạm được 100%. Với quy định AML, một lần bỏ sót cũng có thể dẫn tới chế tài nặng.
B sai vì PostToolUse hook chạy sau khi thực thi. Tới lúc hook phát hiện thiếu AML check thì giao dịch vi phạm đã xong. Tuân thủ pháp lý đòi ngăn chặn, không phải phát hiện sau.
D sai vì few-shot nâng độ chính xác nhưng vẫn mang tính xác suất. Nó không đảm bảo được 100%. Yêu cầu pháp lý đòi cưỡng chế tất định.

Câu 2

Một agent hỗ trợ khách hàng dùng ba MCP tool trả ngày ở ba định dạng khác nhau: Unix timestamp (1710489600), chuỗi ISO 8601 (“2024-03-15T12:00:00Z”), và dạng DD/MM/YYYY (“15/03/2024”). Model thỉnh thoảng lẫn thứ tự ngày/tháng. Giải pháp tốt nhất là gì?

A. Thêm chỉ thị vào system prompt giải thích ba định dạng ngày và cách diễn giải từng loại
B. Chỉ dùng một MCP tool để tránh định dạng không nhất quán
C. Cài PreToolUse hook chuyển đổi ngày trước khi gửi tới các tool
D. Cài PostToolUse hook chuẩn hóa mọi định dạng ngày về ISO 8601 trước khi model xử lý

Đáp án & giải thích

Đúng: D

D đúng vì PostToolUse hook chặn tool result sau khi thực thi nhưng trước khi model xử lý. Chuẩn hóa mọi ngày về ISO 8601 ở điểm này đảm bảo model luôn nhận dữ liệu nhất quán, bất kể tool nào tạo ra nó.
A sai vì trông chờ model diễn giải đúng ba định dạng ngày ở mọi vòng lặp sẽ đẻ ra thiếu nhất quán. Model có thể parse đúng một lần rồi hiểu sai ở lần sau.
B sai vì giới hạn còn một tool là cắt bớt chức năng. Cách đúng là chuẩn hóa output hỗn tạp, không phải né việc dùng nhiều tool.
C sai vì PreToolUse hook chạy trước khi tool thực thi. Ngày nằm trong tool result (sau khi thực thi), không nằm trong tool call (trước khi thực thi). Chiều của hook sai với tình huống này.

Câu 3

Phát biểu nào mô tả đúng khác biệt giữa PostToolUse hook và PreToolUse hook?

A. PostToolUse biến đổi kết quả sau khi thực thi; PreToolUse chặn hoặc sửa lời gọi trước khi thực thi
B. PostToolUse chạy trước khi tool thực thi; PreToolUse chạy sau
C. Cả hai chạy ở cùng một điểm, nhưng PostToolUse lo dữ liệu còn PreToolUse lo lỗi
D. PostToolUse chỉ hoạt động với MCP tool; PreToolUse hoạt động với mọi loại tool

Đáp án & giải thích

Đúng: A

A đúng vì PostToolUse hook chạy sau khi tool thực thi nhưng trước khi model xử lý kết quả (hợp cho chuẩn hóa dữ liệu). PreToolUse hook chạy trước khi tool thực thi (hợp cho cưỡng chế chính sách và chặn hành động).
B sai vì nó đảo ngược chiều. PostToolUse là sau khi thực thi, không phải trước. PreToolUse là trước, không phải sau.
C sai vì hai hook chạy ở hai điểm khác nhau trong vòng đời, không cùng một điểm. Thời điểm chính là điểm phân biệt nền tảng.
D sai vì cả hai loại hook đều làm việc được với mọi loại tool. Điểm phân biệt là thời điểm (trước hay sau khi thực thi), không phải tính tương thích tool.

Câu 4

Một developer cài PostToolUse hook để chặn các khoản hoàn tiền trên 500 USD. Vì sao cách này sai?

A. PostToolUse hook không đọc được tham số số tiền hoàn
B. Tới lúc PostToolUse hook kích hoạt thì khoản hoàn tiền đã được thực thi rồi
C. PostToolUse hook chỉ có ở gói trả phí của Agent SDK
D. PostToolUse hook chỉ biến đổi được dữ liệu, không chặn được thao tác

Đáp án & giải thích

Đúng: B

B đúng vì PostToolUse hook chạy sau khi tool thực thi. Tới lúc hook kích hoạt thì tool process_refund đã chạy và khoản hoàn đã được xử lý. Muốn chặn hành động thì cần PreToolUse hook, chặn trước khi thực thi.
A sai vì PostToolUse hook đọc được toàn bộ tool result, gồm cả tham số. Vấn đề là thời điểm, không phải quyền đọc dữ liệu.
C sai vì đây không phải giới hạn theo gói giá. Vấn đề là PostToolUse hook về bản chất chạy quá muộn để ngăn một hành động.
D sai vì tuy PostToolUse hook thường được dùng để biến đổi dữ liệu, vấn đề cốt lõi vẫn là nó chạy sau khi thực thi. Kể cả nếu chặn được thì hành động cũng đã xảy ra rồi.

Câu 5

Khi nào nên dùng hook thay vì chỉ thị trong prompt để cưỡng chế một business rule?

A. Khi quy tắc phức tạp và cần nhiều bước để kiểm chứng
B. Khi quy tắc liên quan tới sở thích định dạng hoặc style output mà người đọc sẽ nhận ra
C. Khi agent có hơn 5 tool
D. Khi một lần vi phạm duy nhất gây thiệt hại tài chính, rủi ro pháp lý hoặc sự cố bảo mật

Đáp án & giải thích

Đúng: D

D đúng vì khung quyết định dựa trên hậu quả. Hook cho đảm bảo tất định (cưỡng chế 100%). Prompt cho hướng dẫn mang tính xác suất. Nếu một lần lỗi gây thiệt hại tài chính, rủi ro pháp lý hay sự cố bảo mật thì chỉ hook mới cho mức đảm bảo cần thiết.
A sai vì độ phức tạp của quy tắc không quyết định cơ chế. Quy tắc đơn giản (chặn hoàn tiền trên 500 USD) vẫn cần hook vì rủi ro tài chính, còn quy tắc phức tạp (theo một quy ước định dạng cụ thể) có khi chỉ cần prompt.
B sai vì sở thích định dạng rõ ràng là rủi ro thấp, hợp với hướng dẫn bằng prompt. Dùng hook ở đây là overhead thừa.
C sai vì số lượng tool không liên quan tới quyết định hook hay prompt. Hậu quả của một lần vi phạm mới là yếu tố quyết định.