Thiết kế Tool Layer và Human Approval #10

Trả lời ngắn: Tool layer là ranh giới giữa ý định của model và thay đổi bên ngoài. Trước khi cho system gọi tool, hãy ghi rõ input/output, permission, side effect, owner, audit và điều kiện dừng. Human approval phải là control có dữ liệu và quyết định thật, không phải một nút bấm để trang trí.

Đọc xong, bạn sẽ hiểu:

• Tool, read/write/destructive và side effect khác nhau thế nào.
• Cách viết tool contract nhỏ và test được.
• Khi nào cần human approval và reviewer phải thấy gì.
• Cách dùng allowlist, audit, idempotency, fallback và rollback.

Lưu ý giáo dục: Ví dụ dùng ticket, draft và bài viết giả. Không dùng credentials, PII, customer data, API key, tiền thật hoặc production tool. Một tool được model gọi thành công chưa chứng minh tool đó được cấp quyền đúng.

1. Tool layer là ranh giới, không phải danh sách function

Tool là khả năng bên ngoài mà system có thể gọi, chẳng hạn đọc ticket, tạo draft hoặc gửi email. Side effect là thay đổi bên ngoài như ghi, gửi, xoá hoặc publish. Model có thể đề xuất tool call, nhưng một lớp thực thi riêng phải kiểm schema, quyền, policy và trạng thái trước khi làm.

Phân loại ban đầu:

• Read-only: get_ticket, search_policy, không thay đổi state.
• Create draft: tạo artifact để người sửa, chưa gửi ra ngoài.
• Write: cập nhật record hoặc queue.
• Destructive/public: xoá, publish, gửi khách hàng hoặc thay đổi quyền.

Content pipeline có thể cho agent tạo draft, chạy validator và ghi report giả; quyền publish phải tách khỏi các bước đó. Support assistant có thể xem ticket và draft reply; send_reply không được ẩn trong cùng function đọc dữ liệu.

Tool layer nên có boundary rõ: model chỉ thấy tool được phép cho task, system thực thi bằng identity giới hạn, người chịu trách nhiệm nhận evidence. OpenAI Agents SDK đặt tools, guardrails, state và tracing trong cùng thiết kế agent; tool không nên được xem như một lệnh không điều kiện. OpenAI Agents SDK

Hình 1 — Tool call đi qua contract, permission và approval trước khi tạo side effect.

Ví dụ đời thường: tool giống chìa khóa. Không chỉ cần biết chìa mở cửa nào; còn cần ghi ai mượn, mở để làm gì, hạn dùng và cách khóa lại khi giấy tờ không khớp.

2. Tool contract cần ghi những gì

a. Contract tối thiểu

Một tool contract nên có:

1. Purpose: tool làm đúng một việc gì?
2. Input schema: field nào bắt buộc, type/range/format nào?
3. Data scope: tenant, record và field nào được đọc?
4. Preconditions: state nào phải đúng trước khi gọi?
5. Permission: identity nào được gọi và mức nào?
6. Side effect: read, create, write, send, delete hay publish?
7. Output/error: kết quả, error code, timeout và retry nào?
8. Audit/version: ghi run id, owner, tool version và timestamp giả ra sao?

get_ticket có thể nhận ticket_id, trả status đã redact và không có side effect. create_draft_reply nhận ticket + policy version, trả draft id, nhưng không send. send_reply nhận draft id đã duyệt, có side effect và cần approval còn hạn.

Idempotency nghĩa là gọi lại không tạo side effect trùng. Gửi lại cùng một send_reply không được thành hai email. Nếu không bảo đảm được, cần idempotency key, trạng thái đã gửi và stop khi state không rõ. Đừng retry vô hạn một tool write chỉ vì model nhận timeout.

Hình 2 — Contract biến một function mơ hồ thành khả năng có scope, điều kiện và bằng chứng.

b. Test contract trước tool thật

Viết test allow, deny, thiếu field, sai tenant, state cũ, timeout và gọi lại. Với tool read-only, test dữ liệu ngoài scope phải bị từ chối. Với tool write, test chưa có approval phải không chạy. Contract tốt nói rõ NEEDS_REVIEW thay vì để model tự đoán lỗi.

Contract cũng cần dễ đọc với reviewer không viết code. Nếu một người vận hành không hiểu action sẽ tác động tới đâu, schema đó chưa sẵn sàng để cấp quyền. Hãy ghi một ví dụ hợp lệ, một ví dụ bị từ chối và lý do từ chối ngay cạnh tool card.

3. Quyền và least privilege

Least privilege là chỉ cấp quyền tối thiểu cần cho task. Allowlist là danh sách tool hoặc đích được phép. Agent research read-only có thể search vài domain public; không cần quyền ghi database. Content validator có thể đọc draft và ghi report; không cần quyền publish.

Tách identity theo tool và môi trường. Đừng dùng một token có quyền đọc, ghi, gửi và xoá cho mọi bước. Tách tenant/team, field nhạy cảm và owner. Retrieved text hoặc user prompt không tự tạo ra permission; permission phải đến từ policy thực thi.

Google Cloud mô tả production AI security cần nhìn application, data và infrastructure, cùng rủi ro prompt injection và data leakage. Tool layer nên coi data boundary là kiểm soát trước execution, không phải ghi chú sau khi chạy. Google Cloud production AI security

Một rule dễ dùng: default read-only; create draft trước write; approval trước send/publish; dual check với hành động khó đảo ngược. Nếu không biết tool đang dùng identity nào, dừng và tìm owner.

4. Human approval như một control thật

Approval là quyết định có điều kiện trước action cần kiểm. Reviewer không chỉ bấm Accept; reviewer phải thấy input, tool arguments, expected effect, evidence, policy/version, scope và thời hạn. Có thể approve, reject, edit rồi approve, hoặc chuyển NEEDS_REVIEW.

Approval matrix mẫu

Approval cần state machine: proposed → review → approved/rejected/expired → executed. Không execute nếu state đã stale. Audit là bản ghi ai làm gì, khi nào và bằng evidence nào; ghi cả rejection và lý do, không chỉ ghi thành công.

Microsoft AI observability khuyến nghị telemetry gắn với tín hiệu chất lượng và run; approval cũng cần run id, tool version và decision để replay ở mức an toàn. Microsoft AI observability

Hình 3 — Cùng là tool nhưng mức side effect quyết định approval, evidence và owner khác nhau.

5. Sai lầm, giới hạn và stop gate

Sai lầm đầu tiên là tool overreach: một function làm quá nhiều việc, từ đọc tới gửi. Sai lầm thứ hai là approval fatigue: reviewer thấy quá nhiều yêu cầu nên bấm cho xong. Hãy gom risk phù hợp, hiển thị evidence và chỉ yêu cầu người ở điểm có ý nghĩa.

Sai lầm thứ ba là stale state, tức state đã cũ so với lúc execute. Ticket có thể đã được người khác xử lý sau khi approval. Cần re-check precondition ngay trước action. Sai lầm thứ tư là duplicate side effect do retry hoặc double-click. Idempotency và trạng thái execute phải là một phần contract.

Dùng stop gate khi schema thiếu, identity sai, tenant không khớp, tool argument vượt allowlist, approval hết hạn, source không còn hợp lệ hoặc không ghi được audit. Fallback có thể là read-only, tạo draft, queue thủ công hoặc rollback. NIST AI RMF đặt risk management và accountability trong toàn vòng đời; không có owner thì stop gate chưa hoàn chỉnh. NIST AI Risk Management Framework

Không gọi tool chỉ vì model tự sinh tên function. Hệ thống phải kiểm policy ở server-side boundary. Nếu action public/destructive chưa có rollback rõ, giữ NEEDS_REVIEW.

6. Practice Bridge 15 phút

Bắt đầu từ đâu

Mở Google Sheets hoặc notes. Chọn content pipeline giả và thiết kế ba tool: đọc draft, tạo draft reply, publish. Điền risk, identity, input, side effect, approval, audit và fallback. Không dùng API key, PII hay production.

Mẫu đối chiếu đã điền

Hình 4 — Practice map biến tool layer thành contract có owner và điểm dừng.

Sau 15 phút, viết ba test deny: sai tenant, thiếu approval, execute lại cùng idempotency key. Kết quả mong đợi là tool card có owner và stop action, không phải code chạy thật. Nếu không biết ai nhận alert hoặc sửa state, ghi gap và giữ read-only.

7. Tổng kết: permission đi sau contract

a. Năm ý chính

• Tool layer là boundary giữa model intent và external effect; phân loại read/create/write/destructive trước khi cấp quyền.
• Tool contract cần purpose, schema, precondition, permission, side effect, error, audit và version.
• Least privilege, allowlist và read-only default giảm blast radius; prompt/retrieved text không tự cấp permission.
• Human approval phải có reviewer context, state, evidence, owner, expiry và audit; approve không đồng nghĩa execute mù.
• Schema, state, approval hoặc audit không đủ thì stop, fallback, rollback hoặc NEEDS_REVIEW.

b. Câu hỏi tự kiểm tra

• Vì sao create_draft nên tách khỏi send_reply?
• Reviewer cần thấy gì trước action có side effect?
• Idempotency bảo vệ khỏi lỗi nào?
• Khi nào một tool phải chuyển read-only hoặc stop?

c. Gợi ý đáp án

Xem gợi ý câu 1

Create draft chưa gửi ra ngoài, còn send có external side effect và cần approval/recipient check. Xem lại mục 1 và mục 2.

Xem gợi ý câu 2

Input, arguments, expected effect, evidence, policy/version, scope, owner và thời hạn approval. Xem lại mục 4.

Xem gợi ý câu 3

Nó giúp gọi lại hoặc retry không tạo side effect trùng, nhất là gửi/ghi khi timeout hoặc double-click. Xem lại mục 2 và mục 5.

Xem gợi ý câu 4

Khi schema/quyền/tenant/state/approval/audit không hợp lệ hoặc action khó đảo ngược mà chưa có rollback. Xem lại mục 3 và mục 5.

d. Thuật ngữ cần nhớ

e. Nguồn tham khảo

• OpenAI Agents SDK — tools, guardrails, state và tracing.
• Google Cloud production AI security — application/data/infrastructure security.
• Microsoft AI observability — telemetry và quality signals.
• NIST AI Risk Management Framework — risk management và accountability.

Bài trước là Thiết kế Context, Memory và Retrieval #9. Bài tiếp theo là Thiết kế Evaluation và Guardrails #11.

Lưu ý giáo dục: Tool contract, approval và audit không thay security review hoặc runbook thật. Hãy bắt đầu read-only, dữ liệu giả, identity hẹp và mở side effect từng bước khi evidence đủ.