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.
Tóm tắt · TL;DR
Dùng giới hạn số bước của graph để giới hạn quá trình thực thi, HumanInTheLoopMiddleware để tạm dừng các lệnh gọi công cụ rủi ro và một bộ ca kiểm thử nhỏ, cố định để kiểm tra hành vi phê duyệt, từ chối và chạm giới hạn. Hãy xem các ví dụ là điểm khởi đầu: cần kiểm thử hành vi của mô hình và công cụ trong chính môi trường của bạn.
Điểm chính
- Giới hạn đệ quy của graph đặt ra ranh giới thực thi rõ ràng cho tác nhân, nhưng không đảm bảo tác nhân hoàn thành nhiệm vụ.
- Con người có thể duyệt và tạm dừng việc thực thi công cụ để tiếp tục sau đó, nếu graph có checkpointer và thread ID.
- Để đánh giá có thể lặp lại, hãy cố định dữ liệu đầu vào, kết quả mong đợi, bộ giả lập công cụ và giới hạn thực thi.
- Hãy kiểm thử riêng các hành động bị từ chối và trường hợp chạm giới hạn; không trường hợp nào đồng nghĩa với khôi phục thành công.
Mục lục (6)
Tác nhân gọi công cụ cần nhiều hơn một prompt tốt: cần có ranh giới dừng, phương án xử lý hành động rủi ro và các bài kiểm thử giúp tái lập hành vi. Trong LangGraph, bạn có thể kết hợp giới hạn đệ quy của graph với bước duyệt có con người tham gia (HITL) cho một số công cụ nhất định. Sau đó, hãy đánh giá quy trình bằng các ca kiểm thử cố định thay vì chỉ dựa vào vài lần chạy thành công.
Ví dụ dưới đây chỉ nhằm minh họa, không phải cấu hình đã được kiểm thử. Ví dụ giả định bạn có môi trường Python với các gói LangChain và LangGraph tương thích, một mô hình chat hỗ trợ gọi công cụ và một công cụ do bạn triển khai. Hãy kiểm tra phiên bản cũng như tham số của nhà cung cấp mô hình trong môi trường của mình.
Chọn ranh giới trước khi thêm công cụ
Giới hạn đệ quy đặt giới hạn cho các bước thực thi graph. Đây là ranh giới an toàn, không phải cam kết rằng tác nhân sẽ hoàn thành, cũng không phải giới hạn chính xác về số lần gọi công cụ: cấu trúc graph ảnh hưởng đến cách tính số bước. Nếu quá trình thực thi chạm giới hạn, hãy dự kiến có lỗi đệ quy của graph và xử lý lần chạy đó như một lần chạy chưa hoàn tất. Đừng xem đó là câu trả lời thành công.
Khi đánh giá, hãy bắt đầu với giới hạn nhỏ rồi chỉ tăng khi một ca kiểm thử cho thấy quy trình cần thêm bước. Đồng thời, hãy giới hạn phạm vi hoạt động của công cụ. Giới hạn ở cấp graph không thể hoàn tác tác dụng phụ mà công cụ đã thực hiện.
Cấu hình lệnh gọi công cụ có thể tạm dừng để duyệt
Ví dụ này dùng create_agent với middleware HITL. Công cụ write_file sẽ bị gián đoạn để chờ phê duyệt hoặc từ chối; còn read_data thì không. Phần triển khai công cụ và tên mô hình chỉ là chỗ giữ chỗ. Hãy xác nhận mô hình và endpoint đã chọn hỗ trợ các tham số cũng như hành vi gọi công cụ mà tác nhân sử dụng.
from langchain.agents import create_agent
from langchain.agents.middleware import HumanInTheLoopMiddleware
from langgraph.checkpoint.memory import InMemorySaver
# Replace these placeholders with your own tool implementations.
tools = [write_file, read_data]
agent = create_agent(
model="your-tool-capable-chat-model",
tools=tools,
middleware=[
HumanInTheLoopMiddleware(
interrupt_on={
"write_file": {"allowed_decisions": ["approve", "reject"]},
"read_data": False,
}
)
],
checkpointer=InMemorySaver(),
)
config = {
"configurable": {"thread_id": "evaluation-case-001"},
"recursion_limit": 8,
}
result = agent.invoke(
{"messages": [{"role": "user", "content": "Save the approved summary."}]},
config=config,
version="v2",
)
InMemorySaver phù hợp cho bản mẫu hoặc bài kiểm thử chạy trong một tiến trình; dữ liệu không được lưu bền vững sau khi tiến trình khởi động lại. Với quy trình triển khai thực tế, hãy dùng checkpointer bền vững. Hướng dẫn HITL của LangChain cho biết cần có checkpointer và thread ID để tạm dừng rồi tiếp tục thực thi. Nguồn: Human-in-the-loop.
Khi lần chạy trả về một interrupt, hãy hiển thị hành động được yêu cầu cùng các tham số của hành động đó cho người duyệt. Tiếp tục trên cùng thread với quyết định đã đưa ra. Thứ tự quyết định phải khớp với thứ tự hành động trong interrupt. Hãy từ chối hành động mà bạn không cho phép; respond dùng để trả lời của con người dưới dạng kết quả công cụ, không phải để từ chối một tác dụng phụ.
from langgraph.types import Command
# Use the same config, including the same thread ID, to resume.
result = agent.invoke(
Command(resume={"decisions": [{"type": "reject", "message": "Outside the approved scope."}]}),
config=config,
version="v2",
)
Giúp việc đánh giá có thể lặp lại
Lưu một bộ ca kiểm thử gọn trong hệ thống quản lý phiên bản. Mỗi ca nên nêu yêu cầu của người dùng, hành vi công cụ mong đợi, có cần duyệt hay không và trạng thái cuối dự kiến. Khi kiểm thử, hãy dùng bộ dữ liệu thử vô hại hoặc công cụ giả lập; không để các ca đánh giá ghi vào tệp thật hay thay đổi dữ liệu sản xuất.
| Ca kiểm thử | Thiết lập | Kết quả mong đợi |
|---|---|---|
| Đọc an toàn | Yêu cầu thông tin qua read_data | Không có HITL interrupt; kết quả công cụ được trả về |
| Ghi cần duyệt | Yêu cầu một thao tác ghi được phép | Interrupt xuất hiện trước khi thao tác ghi chạy; phê duyệt cho phép thực thi |
| Từ chối thao tác ghi | Yêu cầu thao tác ghi rồi từ chối | Công cụ ghi không được thực thi; phản hồi từ chối được trả về cho tác nhân |
| Ranh giới giới hạn số bước | Dùng bộ dữ liệu thử khiến quy trình không thể hoàn tất | Lần chạy dừng tại ranh giới đã cấu hình và được ghi nhận là chưa hoàn tất |
Với mỗi lần chạy, hãy ghi lại ID ca kiểm thử, giới hạn đã cấu hình, các lệnh gọi công cụ, quyết định trong interrupt, trạng thái hoàn tất và mọi lỗi phát sinh. Đối chiếu các trường đó với kết quả mong đợi. Đừng chỉ đánh giá câu trả lời cuối bằng ngôn ngữ tự nhiên: tác nhân vẫn có thể đưa ra câu trả lời nghe hợp lý sau khi thực hiện sai hành động.
Xử lý lỗi: tạm dừng, từ chối hoặc dừng
HITL là cơ chế tạm dừng có kiểm soát, không phải cơ chế thử lại chung. Tùy chính sách đã cấu hình, người duyệt có thể phê duyệt, chỉnh sửa, từ chối hoặc phản hồi. Khi bị từ chối, lệnh gọi công cụ được yêu cầu sẽ bị bỏ qua và phản hồi từ chối được gửi lại cho tác nhân. Việc tác nhân hoàn tất, yêu cầu hành động khác hay gặp lỗi sau đó phụ thuộc vào hành vi tiếp theo của tác nhân; vì vậy, hãy kiểm thử nhánh này.
Nếu graph chạm giới hạn đệ quy, hãy ghi nhận lần chạy là lỗi do chạm giới hạn và kiểm tra trạng thái cùng lịch sử công cụ. Đừng tự động chạy lại một lần có thể đã thực hiện tác dụng phụ. Khi khả thi, hãy thiết kế công cụ có tính idempotent hoặc yêu cầu một bước kiểm tra riêng trước khi lặp lại thao tác. Tài liệu được dẫn giải thích cách tạm dừng và tiếp tục bằng checkpoint; tài liệu không xác lập khả năng tự động khôi phục sau các lỗi bất kỳ của công cụ hoặc mô hình.
Danh sách kiểm tra khắc phục sự cố
- Không xuất hiện interrupt: Kiểm tra tên công cụ có khớp với ánh xạ
interrupt_onkhông và chính sách của công cụ có bật bước duyệt không. - Không tìm thấy lần chạy đang tạm dừng khi tiếp tục: Xác nhận bạn đang dùng cùng checkpointer và thread ID.
- Lần chạy dừng sớm: Kiểm tra giới hạn đệ quy đã cấu hình và đường đi trong graph; chỉ tăng giới hạn khi có ca kiểm thử chứng minh là cần thiết.
- Có vẻ như hành động bị từ chối đã được thực hiện: Xác minh công cụ chưa được gọi trước bước duyệt và người duyệt đã dùng
reject, không phảirespond. - Kết quả kiểm thử thay đổi giữa các lần chạy: Cố định bộ giả lập công cụ và dữ liệu đầu vào; đồng thời kiểm soát hoặc giả lập phản hồi của mô hình nếu thiết lập của bạn cho phép. Chỉ cố định đầu vào không đảm bảo đầu ra của mô hình sẽ có tính tất định.
Nguyên tắc thực tế
Dùng giới hạn đệ quy để giới hạn công việc của graph, HITL để kiểm soát các lệnh gọi công cụ có hệ quả đáng kể và một bộ ca kiểm thử rõ ràng, nhỏ gọn để xác minh cả luồng thành công lẫn luồng lỗi. Xem các lần chạy bị gián đoạn, bị từ chối và chạm giới hạn là những kết quả riêng biệt. Phân biệt rõ các trường hợp này giúp việc đánh giá tác nhân dễ dàng hơn và thay đổi an toàn hơn.
FAQ
Giới hạn đệ quy của LangGraph có giới hạn số lần gọi công cụ không?
Không hẳn. Giới hạn này áp dụng cho các bước thực thi graph; số lần gọi công cụ có thể thực hiện còn phụ thuộc vào cấu trúc graph. Hãy xem việc chạm giới hạn là một lần chạy chưa hoàn tất và kiểm thử ranh giới này.
Cần những gì để tiếp tục lệnh gọi công cụ đã được con người duyệt?
Hãy cấu hình checkpointer, cung cấp thread ID và tiếp tục bằng cùng thread cùng ngữ cảnh lưu trữ. Người duyệt đưa ra quyết định cho từng hành động bị gián đoạn.
HITL có tự động thử lại lệnh gọi công cụ bị lỗi không?
Không. Quy trình HITL được tài liệu mô tả sẽ tạm dừng để chờ quyết định của con người, sau đó thực thi hoặc bỏ qua hành động được duyệt. Quy trình này không xác lập khả năng tự động thử lại khi công cụ hoặc mô hình gặp lỗi bất kỳ.
Nên kiểm thử lệnh gọi công cụ bị từ chối như thế nào?
Dùng công cụ vô hại hoặc giả lập, kích hoạt interrupt, từ chối hành động rồi xác nhận công cụ không được thực thi và lần chạy có ghi nhận phản hồi từ chối.
Bài viết liên quan
Guides
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.
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
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
Agentic RAG với LangGraph: Gọi công cụ, dẫn nguồn và giới hạn thực thi
Xây dựng agent hỏi đáp tài liệu bằng LangGraph có thể quyết định khi nào cần truy xuất, đánh giá ngữ cảnh, thử lại khi tìm kiếm chưa hiệu quả và trả lời kèm nguồn mà không thực thi vô hạn.