Xây dựng agent LangGraph có giới hạn để chẩn đoán sự cố API

Quyết định: tự động chẩn đoán, chủ động khắc phục

Agent xử lý sự cố API có thể tiết kiệm thời gian bằng cách thu thập bằng chứng từ log, kiểm tra tình trạng hoạt động và metadata của các lần triển khai gần đây. Agent không nên âm thầm khởi động lại dịch vụ, khôi phục bản phát hành trước hoặc thay đổi cấu hình. Thiết kế an toàn hơn sẽ tách riêng việc chẩn đoán chỉ đọc khỏi các thao tác khắc phục có tác dụng phụ, giới hạn phạm vi công việc của agent và cho người vận hành biết khi bằng chứng bị thiếu hoặc không thu thập được.

Đây là thiết kế thực tiễn, không phải một tích hợp đã được kiểm thử hay dịch vụ sẵn sàng đưa vào production. Phần thân công cụ bên dưới chỉ có tính minh họa: hãy thay bằng các ứng dụng khách quan sát hệ thống của riêng bạn, có xác thực và giới hạn quyền.

Điều kiện tiên quyết và quy trình

Bạn cần Python, một mô hình chat tương thích với LangGraph đã được cấu hình trong ứng dụng, cùng các hàm client cho những hệ thống chẩn đoán bạn đang sử dụng. Ví dụ này giả định các hàm client trả về dữ liệu hoặc phát sinh ngoại lệ. Ví dụ không giả định một nhà cung cấp mô hình, endpoint hay tích hợp công cụ cụ thể nào.

Một lượt xử lý sự cố hữu ích tuân theo vòng lặp có giới hạn:

1. Thu thập một tập hợp nhỏ các tín hiệu đã xác định trước cho dịch vụ và khoảng thời gian bị ảnh hưởng.
2. Đánh dấu mỗi kết quả là thành công, thất bại hoặc không khả dụng.
3. Yêu cầu mô hình tóm tắt bằng chứng và xác định những điều còn chưa rõ.
4. Dừng sau số bước đồ thị có giới hạn; yêu cầu con người xem xét trước mọi hành động làm thay đổi trạng thái.

Trường trạng thái có ý nghĩa thiết thực trong vận hành: truy vấn log thất bại không được hiển thị giống như một lượt tìm kiếm log thành công nhưng không có sự kiện phù hợp.

Định nghĩa công cụ chẩn đoán với tín hiệu lỗi rõ ràng

Giữ hợp đồng của công cụ ở phạm vi hẹp. Yêu cầu tên dịch vụ và khoảng thời gian có giới hạn; tránh cho mô hình quyền truy vấn tùy ý nếu một truy vấn cố định là đủ. Trả về kết quả có cấu trúc để các node phía sau và báo cáo sự cố có thể phân biệt dữ liệu trống với lỗi công cụ.

from typing import Literal, TypedDict
from langchain.tools import tool

class Signal(TypedDict):
    status: Literal["ok", "error", "unavailable"]
    source: str
    data: str
    error: str | None


def query_logs(service: str, minutes: int) -> Signal:
    if not 1 <= minutes <= 60:
        return {
            "status": "error", "source": "logs", "data": "",
            "error": "minutes must be between 1 and 60",
        }
    try:
        # Replace with a read-only, scoped observability client call.
        rows = logs_client.search(service=service, minutes=minutes)
        return {
            "status": "ok", "source": "logs",
            "data": str(rows), "error": None,
        }
    except TimeoutError as exc:
        return {
            "status": "unavailable", "source": "logs", "data": "",
            "error": f"timeout: {exc}",
        }

@tool
def inspect_api(service: str, minutes: int = 15) -> dict:
    """Collect scoped, read-only API incident signals."""
    return query_logs(service, minutes)

Thêm các công cụ riêng cho kiểm tra tình trạng hoạt động hoặc metadata triển khai, sử dụng cùng một cấu trúc kết quả. Đừng bắt mọi ngoại lệ rồi trả về chuỗi rỗng: hãy giữ lại đủ thông tin lỗi để chẩn đoán tích hợp bị hỏng, đồng thời tránh đưa bí mật hoặc payload nhạy cảm vào log và ngữ cảnh của mô hình.

Giới hạn thực thi và hiển thị các lượt chạy chưa hoàn tất

Với agent được xây dựng bằng create_agent của LangGraph, hãy đặt giới hạn đệ quy cho đồ thị khi gọi. Giới hạn này khống chế số bước của đồ thị; nó không đảm bảo câu trả lời hữu ích và cũng không thay thế timeout ở cấp công cụ. Hãy xử lý trường hợp chạm giới hạn trong ứng dụng bao quanh và trả về trạng thái “chưa hoàn tất” rõ ràng, thay vì xem lượt chạy là một chẩn đoán hoàn chỉnh.

from langchain.agents import create_agent

agent = create_agent(
    model=your_configured_chat_model,
    tools=[inspect_api],
    system_prompt=(
        "Diagnose API incidents using available evidence. "
        "Report each source as ok, error, or unavailable. "
        "Do not claim a cause without supporting evidence. "
        "Do not perform remediation."
    ),
)

try:
    result = agent.invoke(
        {"messages": [{"role": "user", "content":
            "Investigate elevated errors for payments-api over the last 15 minutes."}]},
        config={"recursion_limit": 12},
    )
except Exception as exc:
    # Map known graph-limit and provider/tool failures to your app's
    # incident-run status; do not expose credentials or raw secrets.
    result = {"status": "incomplete", "reason": type(exc).__name__}

Giá trị giới hạn chỉ là ví dụ, không phải khuyến nghị áp dụng cho mọi trường hợp. Hãy chọn giá trị dựa trên số công cụ và lượt trao đổi với mô hình mà bạn cho phép, đồng thời đặt timeout và giới hạn kích thước yêu cầu ở cả lớp công cụ lẫn lớp ứng dụng. Ghi lại ID lượt chạy, dịch vụ và khoảng thời gian được chọn, các công cụ đã gọi, trạng thái công cụ và lý do kết thúc. Những tín hiệu này giúp người vận hành phân biệt “không tìm thấy lỗi” với “hệ thống log đã hết thời gian chờ”.

Thêm bước con người xem xét trước khi khắc phục

Nếu sau này bổ sung công cụ làm thay đổi trạng thái production, hãy kiểm soát các công cụ đó bằng middleware human-in-the-loop của LangChain cùng một checkpointer. Middleware được tài liệu hóa có thể tạm dừng các lệnh gọi công cụ phù hợp để chờ phê duyệt, chỉnh sửa, từ chối hoặc phản hồi trực tiếp. Trạng thái được lưu để có thể tiếp tục thực thi sau khi có quyết định; khi sử dụng trong production, cần có checkpointer bền vững thay vì tùy chọn lưu trong bộ nhớ chỉ dành cho tạo mẫu. Xem tài liệu human-in-the-loop của LangChain.

Một chính sách thực tiễn là cho phép chẩn đoán chỉ đọc mà không cần tạm dừng, đồng thời yêu cầu phê duyệt đối với công cụ khởi động lại, khôi phục bản phát hành trước hoặc thay đổi cấu hình. Hãy từ chối hành động được đề xuất khi không chấp thuận; tài liệu lưu ý rằng “respond” dùng để hành động thay cho công cụ, không phải để từ chối một lệnh gọi có tác dụng phụ. Tự xác thực các đối số đã chỉnh sửa trong phần triển khai công cụ: middleware được tài liệu hóa không xác thực nội dung chỉnh sửa theo schema hiển thị.

Các trường hợp lỗi cần tính đến

• Kết quả trống: Báo “không có sự kiện phù hợp nào được trả về”, không phải “dịch vụ đang hoạt động bình thường”.
• Công cụ hết thời gian chờ hoặc lỗi phân quyền: Giữ lại nguồn bị lỗi và loại lỗi; không âm thầm thử lại vô hạn.
• Gọi công cụ lặp lại: Giới hạn quá trình thực thi đồ thị và ràng buộc dữ liệu đầu vào của công cụ. Nếu thêm cơ chế thử lại, hãy đặt chính sách thử lại rõ ràng với số lần nhỏ và hiển thị số lần đã thử.
• Không thể tiếp tục sau interrupt: Kiểm tra đã cấu hình checkpointer hay chưa và có dùng cùng định danh thread khi tiếp tục hay không. Tài liệu nguồn yêu cầu checkpointing để con người xem xét.
• Tóm tắt cuối cùng gây hiểu nhầm: Yêu cầu báo cáo dẫn nguồn cho các kết luận dựa trên tín hiệu đã thu thập, đồng thời liệt kê nguồn không khả dụng và câu hỏi chưa được giải đáp.

Danh sách kiểm tra lượt xử lý sự cố

Trước khi triển khai, hãy xác minh các công cụ chẩn đoán chỉ đọc và có phạm vi giới hạn; khoảng thời gian và khối lượng truy vấn được khống chế; lỗi công cụ vẫn có thể quan sát; quá trình thực thi đồ thị có giới hạn; và mọi hành động có tác dụng phụ đều tạm dừng để chờ quyết định của con người. Kiểm thử các luồng hết thời gian chờ, kết quả trống, hành động bị từ chối và tiếp tục sau khi bị gián đoạn. Một agent tốt không chỉ đưa ra nguyên nhân gốc có vẻ hợp lý — agent còn cho biết mình thực sự thu thập được bằng chứng nào và quá trình chẩn đoán dừng ở đâu.

Nguồn

• LangChain: Middleware human-in-the-loop — quyết định ngắt, xem xét công cụ có điều kiện, checkpointing và tiếp tục thực thi đã tạm dừng.