12. Xử lý lỗi với Wrap Hooks (Retry & Fallback)

Trong bài học trước, chúng ta đã học cách quan sát Agent thông qua các trạm dừng chân (Node-style hooks). Tuy nhiên, để giải quyết bài toán về Tính đáng tin cậy (Reliability) đã nêu ở Bài 1, chúng ta cần một cơ chế mạnh mẽ hơn để điều khiển việc thực thi. Bài học này sẽ hướng dẫn bạn sử dụng Wrap Hooks để triển khai logic tự động thử lại (Retry) và dự phòng (Fallback).

I. Wrap-style Hooks là gì?

Nếu Node-style hooks là các "trạm quan sát" bên lề đường, thì Wrap Hooks giống như một "đường hầm" bao quanh toàn bộ hành động của Agent. Bạn có 2 hook chính:

1. wrapModelCall: Bao quanh lệnh gọi LLM (Gemini).
2. wrapToolCall: Bao quanh việc thực thi các Công cụ (Tools).

Điểm khác biệt cốt lõi là bạn nhận được một hàm handler. Nếu bạn không gọi handler, AI sẽ không chạy. Nếu bạn gọi handler trong một vòng lặp for, AI sẽ chạy nhiều lần — đây chính là chìa khóa để tạo ra cơ chế Retry.

II. Xây dựng Middleware Tự động thử lại (Retry)

Một Agent sẵn sàng cho production phải chịu đựng được các lỗi tạm thời như: mất kết nối internet, API của Google bị quá tải (Rate limit), hoặc timeout. Chúng ta sẽ xây dựng một middleware bao bọc lệnh gọi model để tự phục hồi khi gặp sự cố.

III. Mã nguồn: 12-handling-errors-with-wrap-hooks.ts

Chúng ta sử dụng hệ thống nạp môi trường ./env và tiện ích createGeminiModel để đảm bảo cấu hình Agent luôn nhất quán.

// apps/langchain/scripts/12-handling-errors-with-wrap-hooks.ts
// pnpm --filter=ai-notes-langchain run tsx scripts/12-handling-errors-with-wrap-hooks.ts

import './env';
import { createGeminiModel, generateImage } from '@workspace/util-langchain';
import { createAgent, createMiddleware } from 'langchain';

// 1. Define Middleware with Retry Logic
const retryMiddleware = createMiddleware({
  name: 'AutoRetry',

  // Wrap the Model execution logic
  wrapModelCall: async (request, handler) => {
    const MAX_RETRIES = 3;
    let lastError;

    for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
      try {
        console.log(`[ATTEMPT ${attempt}]: Calling AI model...`);

        // 'handler(request)' triggers the actual LLM call
        const result = await handler(request);

        console.log(`[SUCCESS]: AI responded correctly on attempt ${attempt}.`);
        return result; // Exit middleware with result
      } catch (error: any) {
        lastError = error;
        console.warn(
          `[FAILED]: Attempt ${attempt} failed. Error: ${error.message}`,
        );

        // If attempts are remaining, wait before retrying (Exponential Backoff)
        if (attempt < MAX_RETRIES) {
          const delay = attempt * 1000;
          console.log(`> Waiting ${delay}ms before retrying...`);
          await new Promise((res) => setTimeout(res, delay));
        }
      }
    }

    // If all retries fail, throw the final error
    console.error(`[CRITICAL]: All ${MAX_RETRIES} attempts failed.`);
    throw lastError;
  },
});

async function main() {
  // To simulate failure, you could temporarily change your GEMINI_API_KEY in .env
  const model = createGeminiModel();

  // 2. Initialize Agent with the Retry Middleware
  const agent = createAgent({
    model,
    tools: [],
    middleware: [retryMiddleware],
  });

  // 3. Generate visual diagram
  await generateImage(
    agent.graph,
    'images/courses/langchain-course/scripts-12-retry-logic.jpg',
  );

  console.log('--- Starting Resilient Agent Test ---');

  try {
    const response = await agent.invoke({
      messages: [
        { role: 'user', content: 'Say hello in a very friendly way.' },
      ],
    });
    console.log('\nFinal Outcome:', response.messages.at(-1).content);
  } catch (e: any) {
    console.error('\n[FINAL_ERROR]: Agent gave up after multiple retries.');
  }
}

main().catch(console.error);

IV. Phân tích kỹ thuật

• handler(request): Đây là "trái tim" của Wrap Hook. Nếu bạn không gọi hàm này, model sẽ không bao giờ được kích hoạt. Bạn có quyền kiểm tra hoặc thay đổi request (như đổi model khác mạnh hơn) trước khi gọi handler.
• Kiểm soát luồng: Khối try-catch bao quanh handler cho phép bạn bắt mọi lỗi từ API. Thay vì làm sập toàn bộ ứng dụng, bạn có thể log lỗi và quyết định thử lại.
• Tính linh hoạt (Fallback): Trong thực tế, nếu model Gemini Pro bị lỗi, bạn có thể đổi request.model sang Gemini Flash ngay trong khối catch để đảm bảo hệ thống luôn có câu trả lời cho người dùng.

Sơ đồ hoạt động:

V. Tổng kết

• Wrap Hooks cung cấp quyền kiểm soát 360 độ đối với việc thực thi của AI và Công cụ.
• handler(request) cho phép triển khai các chiến lược quan trọng như Retry (thử lại khi lỗi) và Fallback (dùng phương án dự phòng).
• Sử dụng hệ thống util-langchain giúp bạn tập trung vào logic xử lý lỗi mà không phải lo lắng về việc cấu hình model lặp đi lặp lại.

Trong bài học tiếp theo, chúng ta sẽ học về PII Detection — cách sử dụng Guardrails để tự động bảo vệ thông tin cá nhân của người dùng một cách chuyên nghiệp!

👉 Bài tiếp theo: 13. Bảo mật với PII Detection Guardrails