Xây dựng tác tử LangGraph chú trọng quyền riêng tư với cơ chế phê duyệt công cụ và khôi phục
Mẫu thực tiễn sử dụng tính năng con người xem xét của LangGraph, checkpoint, giới hạn lượt chạy và công cụ an toàn thông tin xác thực cho tác tử xử lý dữ liệu nhạy cảm.
Tóm tắt · TL;DR
Dùng middleware human-in-the-loop của LangGraph để tạm dừng lời gọi công cụ nhạy cảm, xem xét hoặc từ chối, rồi tiếp tục từ checkpoint. Kết hợp quy trình này với ranh giới công cụ chặt chẽ, cô lập thông tin xác thực và giới hạn thực thi.
Điểm chính
- Giữ thông tin xác thực bên trong phần triển khai công cụ; chỉ truyền cho mô hình những đối số tối thiểu cần thiết.
- Yêu cầu con người xem xét các thao tác ghi hoặc truy vấn nhạy cảm, đồng thời cho phép các thao tác đọc an toàn tiếp tục.
- Dùng checkpointer bền vững và thread ID ổn định để tiếp tục công việc bị gián đoạn.
- Giới hạn thực thi đồ thị và thiết kế công cụ theo hướng idempotent hoặc an toàn khi thử lại độc lập.
- Coi trạng thái đã lưu trong checkpoint và payload interrupt là dữ liệu nhạy cảm.
Mục lục (5)
Một tác tử chú trọng quyền riêng tư không nên dựa vào mô hình để quyết định lời gọi công cụ có an toàn hay không. Hãy giữ thông tin xác thực ngoài cuộc hội thoại, giới hạn khả năng của từng công cụ và tạm dừng các hành động nhạy cảm để con người xem xét. Middleware human-in-the-loop của LangGraph cung cấp cơ chế tạm dừng và tiếp tục; ứng dụng của bạn vẫn cần xác định cách xử lý dữ liệu, phân quyền và giới hạn thực thi.
Hướng dẫn này xây dựng một mẫu nhỏ cho tác tử có thể đọc hồ sơ khách hàng và yêu cầu thay đổi cơ sở dữ liệu. Mã chỉ nhằm minh họa, chưa được kiểm thử trong bài viết này. Trước khi triển khai, hãy kiểm tra phiên bản gói và chữ ký công cụ phù hợp với môi trường của bạn.
1. Tách ngữ cảnh mô hình khỏi thông tin xác thực
Không đưa mật khẩu, API key, cookie phiên hoặc thông tin xác thực cơ sở dữ liệu không giới hạn vào prompt hay đối số công cụ. Thay vào đó, hãy cung cấp cho công cụ các thao tác giới hạn và để chúng lấy thông tin xác thực từ cơ chế quản lý bí mật của ứng dụng tại thời điểm thực thi. Mô hình chỉ nên thấy dữ liệu cần thiết để chọn hành động.
Ví dụ, nên dùng công cụ như find_customer_record(customer_id) thay vì công cụ đa năng nhận SQL tùy ý cùng thông tin kết nối. Hãy kiểm tra phân quyền ngay trong công cụ: yêu cầu của người dùng không chứng minh rằng họ được phép truy cập hồ sơ đó.
Con người xem xét là một biện pháp kiểm soát bổ sung, không phải hệ thống phân quyền. Người xem xét cần thấy đủ thông tin để đưa ra quyết định, nhưng tránh hiển thị dữ liệu cá nhân hoặc bí mật không cần thiết trên màn hình xem xét và trong nhật ký.
2. Cấu hình bước xem xét cho các hành động nhạy cảm
Tài liệu human-in-the-loop của LangChain được cung cấp mô tả middleware kiểm tra lời gọi công cụ theo một chính sách. Các lời gọi khớp chính sách có thể làm gián đoạn quá trình thực thi; checkpointer lưu trạng thái đồ thị để lượt chạy có thể tiếp tục sau đó. Các quyết định được tài liệu nêu gồm phê duyệt, chỉnh sửa đối số, từ chối kèm phản hồi và trả lời công cụ đặt câu hỏi cho người dùng.
Dưới đây là cấu hình minh họa. Hãy thay các công cụ giữ chỗ bằng phần triển khai có áp dụng quy tắc truy cập và xác thực đầu vào của ứng dụng.
from langchain.agents import create_agent
from langchain.agents.middleware import HumanInTheLoopMiddleware
from langgraph.checkpoint.memory import InMemorySaver
agent = create_agent(
model="YOUR_CONFIGURED_MODEL",
tools=[read_customer_record, update_customer_record],
middleware=[
HumanInTheLoopMiddleware(
interrupt_on={
"read_customer_record": False,
"update_customer_record": {
"allowed_decisions": ["approve", "edit", "reject"]
},
},
description_prefix="Review requested customer-data change",
),
],
# For production, use a persistent checkpointer appropriate to your stack.
checkpointer=InMemorySaver(),
)
InMemorySaver phù hợp để tạo mẫu thử, nhưng không cung cấp khả năng khôi phục bền vững sau khi tiến trình khởi động lại. Tài liệu yêu cầu có checkpointer cho các lần gián đoạn để con người xem xét và nêu những lựa chọn lưu trữ bền vững như AsyncPostgresSaver và MongoDBSaver. Hãy chọn phương thức lưu trữ có quyền truy cập, quy tắc lưu giữ và mã hóa phù hợp với dữ liệu được checkpoint. Checkpoint có thể chứa tin nhắn và đối số công cụ, vì vậy vẫn có thể chứa dữ liệu người dùng nhạy cảm ngay cả khi đã loại trừ thông tin xác thực.
Nếu chỉ một số lời gọi cần được xem xét, tài liệu cũng hỗ trợ predicate when để gián đoạn có điều kiện (yêu cầu langchain>=1.3.3). Chẳng hạn, bạn có thể tạm dừng thao tác ghi bên ngoài không gian làm việc được phê duyệt hoặc truy vấn không chỉ đọc. Đừng coi việc kiểm tra tiền tố chuỗi là chính sách bảo mật SQL đầy đủ; hãy áp dụng các thao tác an toàn ở cả tầng cơ sở dữ liệu và tầng công cụ.
3. Tạm dừng, xem xét và tiếp tục cùng một lượt chạy
Dùng thread ID ổn định để ứng dụng có thể liên kết yêu cầu xem xét đang chờ với đúng cuộc hội thoại. Bảo vệ mã định danh này và giao diện xem xét: chỉ sở hữu thread ID không đồng nghĩa với việc được phép phê duyệt hành động.
from langgraph.types import Command
config = {"configurable": {"thread_id": "conversation-123"}}
result = agent.invoke(
{"messages": [{"role": "user", "content": "Update this customer's address"}]},
config=config,
version="v2",
)
if result.interrupts:
# Present the requested action to an authenticated reviewer.
# Resume only after recording that reviewer's decision.
result = agent.invoke(
Command(resume={"decisions": [{"type": "reject", "message": "Verify the request first."}]}),
config=config,
version="v2",
)
Thứ tự quyết định phải khớp với thứ tự hành động trong yêu cầu interrupt khi nhiều lời gọi công cụ bị tạm dừng. Dùng reject để từ chối một hành động gây tác động phụ. Tài liệu cảnh báo rằng respond cung cấp kết quả công cụ tổng hợp; lựa chọn này dùng để trả lời công cụ kiểu “ask user”, không phải để từ chối thao tác ghi.
4. Giới hạn thực thi và thiết kế để khôi phục
Việc tạm dừng để xem xét tự nó không ngăn mô hình liên tục yêu cầu gọi công cụ. Hãy đặt giới hạn đệ quy cho các lần gọi đồ thị và xử lý lỗi giới hạn phát sinh như một lần dừng có kiểm soát. Mức giới hạn cụ thể tùy thuộc vào khối lượng công việc; hãy chọn mức dựa trên chuỗi bước mô hình và công cụ tối đa còn hữu ích, rồi kiểm thử hành vi tại ngưỡng đó.
config = {
"configurable": {"thread_id": "conversation-123"},
"recursion_limit": 12,
}
Cấu hình minh họa này giới hạn số bước đồ thị; nó không đảm bảo tránh được công cụ chạy chậm, đầu ra lớn hoặc tác động phụ bên ngoài bị lặp lại. Hãy đặt timeout cho các lệnh gọi mạng và cơ sở dữ liệu, giới hạn đầu ra công cụ và xác thực đầu vào. Với các thao tác có thể thử lại, hãy dùng cơ chế idempotency hoặc kiểm tra trạng thái hiện tại trước khi áp dụng thay đổi. Nếu lượt chạy gặp lỗi sau khi công cụ đã chạy thành công nhưng trước khi tác tử ghi nhận kết quả, thử lại một cách máy móc có thể khiến thao tác được thực hiện hai lần.
Khi khôi phục, chỉ tiếp tục thread đã lưu checkpoint sau khi xác minh hành động đang chờ và quyền thực hiện hành động đó vẫn còn hiệu lực. Nếu quyền của người dùng hoặc hồ sơ liên quan đã thay đổi trong khi chờ xem xét, hãy từ chối hoặc xác thực lại thay vì thực thi các đối số đã cũ.
5. Danh sách kiểm tra quyền riêng tư và xử lý lỗi
Trước khi đưa vào môi trường production, hãy xác nhận rằng:
- Phần triển khai công cụ lấy thông tin xác thực một cách riêng tư và không bao giờ trả chúng về trong kết quả công cụ hoặc thông báo lỗi.
- Mỗi công cụ đều kiểm tra quyền của người dùng và chỉ nhận các đối số tối thiểu cần thiết.
- Checkpoint, payload interrupt, nhật ký và màn hình dành cho người xem xét đều có quy định rõ ràng về quyền truy cập và thời hạn lưu giữ.
- Người xem xét có thể xác định đối tượng và hệ quả mà không cần xem dữ liệu cá nhân không liên quan.
- Việc từ chối không thực thi công cụ và thao tác thử lại không thể gây trùng lặp tác động phụ.
- Lượt chạy có giới hạn số bước, timeout cho công cụ, giới hạn đầu ra và quy trình rõ ràng để báo cáo công việc bị gián đoạn hoặc gặp lỗi.
Lựa chọn thiết kế cốt lõi là xem phê duyệt của con người như một điểm kiểm soát trong quy trình được bảo mật, chứ không phải giải pháp thay thế cho nguyên tắc đặc quyền tối thiểu, giảm thiểu dữ liệu hoặc xác thực ở cấp công cụ.
FAQ
Middleware human-in-the-loop của LangGraph có lưu trạng thái tác tử đang tạm dừng không?
Tính năng này dùng cơ chế persistence của LangGraph để lưu trạng thái khi bị interrupt. Cần có checkpointer; với môi trường production, nên chọn phương thức lưu trữ bền vững và áp dụng các biện pháp kiểm soát quyền truy cập, thời hạn lưu giữ phù hợp.
Tôi có nên dùng quyết định respond để từ chối một lời gọi công cụ nhạy cảm không?
Không. Theo tài liệu, respond được xử lý như kết quả công cụ thành công được tạo tổng hợp, dành cho những trường hợp như trả lời công cụ kiểu ask-user. Hãy dùng reject để từ chối hành động gây tác động phụ.
Làm cách nào để giữ thông tin xác thực riêng tư trong tác tử LangGraph?
Giữ thông tin xác thực trong môi trường thực thi của công cụ hoặc lớp quản lý bí mật. Không đưa chúng vào prompt, đối số công cụ mà mô hình có thể thấy, kết quả công cụ, tin nhắn interrupt hoặc nhật ký.
Phê duyệt của con người có ngăn tác tử chạy vô thời hạn không?
Không. Middleware phê duyệt xử lý việc xem xét các lời gọi công cụ được cấu hình. Hãy bổ sung riêng giới hạn thực thi, timeout cho công cụ, giới hạn đầu ra và cơ chế thử lại an toàn.
Bài viết liên quan
Guides
Xây dựng tác nhân gọi công cụ LangGraph có giới hạn và bước duyệt của con người
Mẫu thực tiễn để đánh giá tác nhân gọi công cụ LangGraph với giới hạn số bước rõ ràng, yêu cầu con người phê duyệt hành động rủi ro và các ca kiểm thử có thể lặp lại.
Guides
Tạo tác tử hỗ trợ khách hàng bằng LangGraph với gọi công cụ, phê duyệt của con người và giới hạn thực thi
Mẫu LangGraph thực tiễn để phân loại yêu cầu hỗ trợ khách hàng: định tuyến yêu cầu, gọi công cụ tra cứu, tạm dừng hoàn tiền để chờ người duyệt và giới hạn quá trình thực thi của đồ thị.
Guides
Xây dựng agent LangGraph có giới hạn để chẩn đoán sự cố API
Tạo agent LangGraph chẩn đoán sự cố, gọi các công cụ chỉ đọc, giới hạn quá trình thực thi, hiển thị lỗi và tạm dừng trước những hành động rủi ro.
Guides
Xây dựng agent LangGraph có giới hạn để trích xuất dữ liệu theo schema đã xác thực
Tạo quy trình LangGraph có thể gọi công cụ khi cần, dừng trong giới hạn thực thi đã định và trả về dữ liệu có cấu trúc được xác thực theo schema Pydantic.