GuidesOneMux

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.

AI

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ậpKết quả mong đợi
Đọc an toànYêu cầu thông tin qua read_dataKhông có HITL interrupt; kết quả công cụ được trả về
Ghi cần duyệtYêu cầu một thao tác ghi được phépInterrupt 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 ghiYêu cầu thao tác ghi rồi từ chốiCô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ướcDùng bộ dữ liệu thử khiến quy trình không thể hoàn tấtLầ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_on khô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ải respond.
  • 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