Hiển thị các trạng thái ứng dụng tuỳ chỉnh cho các tác nhân AI bằng công cụ của bên thứ ba

Matthias Rohmer

José Luis Zapata

Các công cụ dành cho nhà phát triển bên thứ ba cho phép các tác nhân mã hoá nhìn thấy ngoài DOM, các yêu cầu mạng và nhật ký bảng điều khiển. Bằng cách hiển thị các công cụ tuỳ chỉnh trực tiếp từ trang web hoặc khung của bạn, bạn cho phép tác nhân tương tác với trạng thái và dữ liệu của ứng dụng mà nếu không thì không thể truy cập được.

Các công cụ này được tạo thông qua JavaScript và được Chrome DevTools tự động phát hiện cho các tác nhân khi trang của bạn tải.

Tìm hiểu về các công cụ dành cho nhà phát triển bên thứ ba

Trong bối cảnh của các tác nhân mã hoá, các công cụ là các hàm có sẵn để tác nhân thực hiện các hành động cụ thể. Đối với DevTools dành riêng cho tác nhân, các công cụ như vậy có thể hiển thị trực tiếp trạng thái thời gian chạy nội bộ cho các tác nhân mã hoá, thu hẹp khoảng cách giữa đầu ra được kết xuất và logic nội bộ.

Khi sử dụng các công cụ của bên thứ ba, hãy lưu ý những điều sau:

• Phát hiện thời gian chạy. Các công cụ sẽ tự động được phát hiện khi ứng dụng của bạn phản hồi sự kiện devtoolstooldiscovery do Chrome DevTools phát ra cho các tác nhân trên đối tượng window toàn cục.
• Phạm vi ngữ cảnh. Các công cụ chỉ thực thi trong ngữ cảnh của trang xác định các công cụ đó. Các công cụ này không tồn tại trên các nguồn gốc và khi tải lại trang.
• Tính cụ thể của công cụ. Các công cụ chỉ là một cách bổ sung để tác nhân thực hiện một công việc. Tác nhân có thể ưu tiên các công cụ tích hợp hoặc các chức năng của mô hình cơ bản để thực hiện một lời nhắc. Vì vậy, hãy đặt tên và mô tả công cụ rõ ràng nhất có thể.

Điều kiện tiên quyết

Trước khi triển khai các công cụ của bên thứ ba, hãy đảm bảo bạn đáp ứng các yêu cầu sau:

• Chrome DevTools cho các tác nhân. Sử dụng phiên bản 0.25.0 trở lên.
• Đã bật JavaScript. Đã bật và thực thi JavaScript.

Triển khai công cụ

Để triển khai một công cụ, bạn sẽ theo dõi một sự kiện phát hiện cụ thể và phản hồi bằng các định nghĩa công cụ. Mã sau đây đại diện cho một phản hồi bao gồm các định nghĩa công cụ:

window.addEventListener(
  'devtoolstooldiscovery',
  (event: DevtoolsToolDiscoveryEvent) => {
    event.respondWith({
      name: 'Page-specific DevTools',
      description: 'Provide runtime info directly from the JavaScript in the page.',
      tools: [
        {
          name: 'add',
          description: 'Calculates the sum of two numbers.',
          inputSchema: {
            type: 'object',
            properties: {
              a: {type: 'number'},
              b: {type: 'number'},
            },
            required: ['a', 'b'],
          },
          execute: async (input: {a: number; b: number}) => {
            return input.a + input.b;
          },
        },
      ],
    });
  },
);

Cách đăng ký công cụ trong ứng dụng:

1. Xác định nhóm công cụ. Tạo một ToolGroup chứa tên, nội dung mô tả và một mảng các định nghĩa công cụ riêng lẻ.

   export interface ToolDefinition {
     name: string;
     description: string;
     inputSchema: JSONSchema7;
     execute: (args: Record<string, unknown>) => unknown;
   }
   export interface ToolGroup {
     name: string;
     description: string;
     tools: ToolDefinition[];
   }
   

2. Theo dõi sự kiện phát hiện. Chrome DevTools cho các tác nhân sẽ gửi một sự kiện devtoolstooldiscovery tuỳ chỉnh trên đối tượng window toàn cục sau mỗi lần điều hướng và bất cứ khi nào cần danh sách công cụ hiện có được cập nhật.

3. Đăng ký công cụ. Gọi phương thức respondWith() của sự kiện để cung cấp nhóm công cụ cho tác nhân.

Các thành phần cần thiết cho từng công cụ

Mỗi định nghĩa công cụ mà bạn triển khai phải bao gồm 3 phần sau:

• Tên và nội dung mô tả. Các thành phần này cung cấp hướng dẫn mà tác nhân sử dụng để quyết định thời điểm và cách gọi công cụ.
• Giản đồ đầu vào. Một giản đồ JSON xác định cấu trúc và các loại đối số mà công cụ mong đợi.
• Hàm thực thi. Mã JavaScript thực tế chạy trên trang khi tác nhân gọi công cụ.

Ví dụ sau đây cho thấy 3 thành phần này trong một định nghĩa công cụ:

{
  name: 'add',
  description: 'Calculates the sum of two numbers.',
  inputSchema: {
    type: 'object',
    properties: {
      a: {type: 'number'},
      b: {type: 'number'},
    },
    required: ['a', 'b'],
  },
  execute: async (input) => {
    return input.a + input.b;
  },
}

Trường hợp sử dụng các công cụ dành cho nhà phát triển bên thứ ba

Hướng dẫn tác nhân kiểm tra logic sâu của ứng dụng thay vì chỉ các thành phần trên giao diện người dùng ở cấp độ bề mặt. Sử dụng các công cụ tuỳ chỉnh này để đơn giản hoá quá trình gỡ lỗi các ứng dụng có trạng thái hoặc có nhiều khung.

Mẹo phát hiện công cụ

Viết tên và nội dung mô tả công cụ rõ ràng. Các tác nhân sử dụng những nội dung mô tả này làm ngữ cảnh để quyết định sử dụng công cụ nào. Ngôn ngữ rõ ràng giúp tác nhân tự xác định thời điểm một công cụ phù hợp với một công việc.

Gỡ lỗi các chỉ số thời gian chạy dành riêng cho ứng dụng

Các vấn đề như lỗi bộ nhớ đệm ẩn hoặc các lệnh gọi API dư thừa thường không hiển thị trong quá trình kiểm tra tiêu chuẩn. Bằng cách hiển thị số liệu thống kê nội bộ, tác nhân có thể giải thích lý do xảy ra một hành vi nhất định.

Giả sử bạn có một hàm hiển thị số liệu thống kê nội bộ; trước tiên, bạn phải tạo một công cụ như công cụ này:

window.addEventListener('devtoolstooldiscovery', (event) => {
  event.respondWith({
    name: 'My app',
    description: 'Tools to debug my app',
    tools: [
      {
        name: 'getCacheStatistics',
        description: 'Exposes runtime cache hits and misses for the frontend API service.',
        inputSchema: {},
        execute: async () => {
          // Assuming window.__apiCacheService exists in your app
          return window.__apiCacheService.getStats();
        }
      }
    ]
  });
});

Nếu nội dung mô tả công cụ của bạn rõ ràng, tác nhân có thể tự sử dụng công cụ khi thấy phù hợp. Bạn có thể nhắc tác nhân thực hiện một công việc bằng công cụ như sau:

When I reassign a lead to a new sales rep, the dashboard takes a second to
update. Please verify if the frontend is correctly updating the local cache,
or if it is doing a full cache miss and refetching the entire pipeline from the
database.

Ví dụ về quá trình thực thi của tác nhân: Tác nhân phát hiện công cụ getCacheStatistics do ứng dụng của bạn hiển thị. Tác nhân này gọi công cụ, phân tích tỷ lệ truy cập thành công/thất bại được trả về và xác định rằng giao diện người dùng đang tìm nạp lại toàn bộ quy trình một cách không cần thiết thay vì cập nhật bộ nhớ đệm cục bộ.

Kiểm tra cờ tính năng

Xác định các điểm dữ liệu tuỳ chỉnh để hiển thị các biến môi trường hiện tại hoặc cờ tính năng đang hoạt động cho một phiên người dùng cụ thể. Điều này giúp bạn gỡ lỗi lý do một số tính năng hiển thị hoặc không hiển thị cho một số người dùng. Nếu người dùng báo cáo lỗi, tác nhân có thể xác minh xem người dùng đó có nằm trong nhóm thử nghiệm có thể gây ra vấn đề hay không.

Ví dụ: tạo một công cụ như công cụ này để trả về trạng thái cờ tính năng nội bộ:

// Implementation for a website creator to expose feature flags
window.addEventListener('devtoolstooldiscovery', (event) => {
  event.respondWith({
    name: 'Application Configuration Tools',
    description: 'Tools for inspecting runtime environment and feature toggles',
    tools: [
      {
        name: 'getFeatureFlags',
        description: 'Returns a list of all active feature flags and their current values for the session.',
        inputSchema: {
          type: 'object',
          properties: {} // No input parameters required for this tool
        },
        execute: async () => {
          // This should return your internal feature flag state
          // Example: return window.AppConfig.getFlags();
          return {
            "new-ui-enabled": true,
            "beta-search-v2": false,
            "experiment-group": 'control',
            "log-level": 'debug'
          };
        }
      }
    ]
  });
});

Nếu nội dung mô tả công cụ của bạn rõ ràng, tác nhân có thể tự sử dụng công cụ khi thấy phù hợp. Bạn có thể nhắc tác nhân thực hiện một công việc bằng công cụ như sau:

Check the active feature flags and tell me if the new-ui-enabled flag is set to
true for this session.

Ví dụ về quá trình thực thi của tác nhân: Tác nhân gọi công cụ getFeatureFlags, xác nhận rằng cờ new-ui-enabled đang hoạt động và tiến hành gỡ lỗi các thành phần liên kết với giao diện mới.

Kiểm tra trạng thái ứng dụng toàn cục

Hiển thị cây trạng thái thời gian chạy của ứng dụng để giúp tác nhân hiểu logic nội bộ mà không cần tìm nạp toàn bộ DOM.

Bạn có thể tạo một công cụ như công cụ này để truy vấn các đường dẫn cụ thể trong cây trạng thái, như sau:

// Library-agnostic implementation for inspecting global application state
window.addEventListener('devtoolstooldiscovery', (event) => {
  event.respondWith({
    name: "Global State Inspector",
    description: 'Tools to inspect the runtime state tree of the application',
    tools: [
      {
        name: 'getGlobalState',
        description: "Returns the current application state. Use the 'path' parameter to drill down into specific sections (for example, 'auth.user' or 'cart.items'). ",
        inputSchema: {
          type: 'object',
          properties: {
            path: {
              type: 'string',
              description: 'Optional dot-notation path to a specific property in the state tree.'
            }
          }
        },
        execute: async (input) => {
          // Library-agnostic access:
          // Website creators can point this to whatever global store they use.
          const state = window.__APP_STATE__ ||
                        (window.store && typeof window.store.getState === 'function' ? window.store.getState() : null);

          if (!state) {
            return { error: 'Application state is not accessible via window.__APP_STATE__ or window.store.' };
          }

          if (!input.path) {
            return state;
          }

          // Helper to resolve a dot-notated path against the state object
          return input.path.split('.').reduce((acc, part) => {
            return acc && acc[part] !== undefined ? acc[part] : undefined;
          }, state);
        }
      }
    ]
  });
});

Nếu nội dung mô tả công cụ của bạn rõ ràng, tác nhân có thể tự sử dụng công cụ khi thấy phù hợp. Bạn có thể nhắc tác nhân thực hiện một công việc bằng công cụ như sau:

The number of items in my cart is not updating. Inspect the global state at the
path cart.items and list the current items and their quantities, see if they are
the same.

Ví dụ về quá trình thực thi của tác nhân: Tác nhân gọi getGlobalState bằng path tham số. Tác nhân này truy xuất danh sách các mặt hàng trong giỏ hàng và xác định sự khác biệt giữa trạng thái nội bộ và các mặt hàng được kết xuất trên trang.

Một số lưu ý quan trọng liên quan đến ví dụ về công cụ này:

• Logic tách biệt: Tác nhân AI yêu cầu "trạng thái". Với tư cách là nhà phát triển, bạn quyết định cách liên kết yêu cầu đó với cấu trúc dữ liệu thực tế trong hàm execute.
• Gỡ lỗi có mục tiêu: Bằng cách đưa tham số path, tác nhân có thể tránh kéo toàn bộ cây trạng thái (có thể rất lớn) và chỉ tập trung vào phần có liên quan, tiết kiệm mã thông báo và cải thiện hiệu suất.
• Giao diện được chuẩn hoá: Ngay cả khi bạn chuyển đổi thư viện quản lý trạng thái, miễn là bạn cập nhật hàm execute này, tác nhân gỡ lỗi AI sẽ không cần bất kỳ hướng dẫn hoặc công cụ mới nào.

Kiểm tra nội dung cơ sở dữ liệu

Xác minh rằng dữ liệu phụ trợ khớp với trạng thái giao diện người dùng bằng cách truy vấn trực tiếp các bản ghi cơ sở dữ liệu thông qua điểm cuối gỡ lỗi chỉ đọc.

Hiển thị điểm gỡ lỗi an toàn và tạo một công cụ như công cụ này để xác minh các bản ghi phụ trợ:

// Framework-agnostic implementation for inspecting database content
window.addEventListener('devtoolstooldiscovery', (event) => {
  event.respondWith({
    name: 'Database Inspection Tools',
    description: 'Tools to query backend database records using existing browser session',
    tools: [
      {
        name: 'queryDatabaseTable',
        description: 'Retrieves a limited set of records from a specific table. Useful for verifying that backend data matches the UI state.',
        inputSchema: {
          type: 'object',
          properties: {
            tableName: {
              type: 'string',
              description: 'The name of the database table to inspect.'
            },
            limit: {
              type: 'number',
              default: 5,
              description: 'Maximum number of rows to return.'
            }
          },
          required: ['tableName']
        },
        execute: async (input) => {
          // This calls a generic debug endpoint you've set up on your server.
          // It's framework-agnostic because it just expects a JSON response.
          try {
            const response = await fetch(`/api/debug/db-inspect?table=${input.tableName}&limit=${input.limit}`);
            if (!response.ok) {
              return { error: `Backend returned ${response.status}: ${response.statusText}` };
            }
            return await response.json();
          } catch (error) {
            return { error: `Failed to connect to debug endpoint: ${error.message}` };
          }
        }
      }
    ]
  });
});

Nếu nội dung mô tả công cụ của bạn rõ ràng, tác nhân có thể tự sử dụng công cụ khi thấy phù hợp. Bạn có thể nhắc tác nhân thực hiện một công việc bằng công cụ như sau:

The total price on the checkout page seems wrong. Query the orders table for my
last order to verify the subtotal and tax values and see what may be causing the
problem, if any.

Ví dụ về quá trình thực thi của tác nhân: Tác nhân gọi queryDatabaseTable cho bảng đơn đặt hàng. Tác nhân này truy xuất bản ghi JSON, xác định lỗi trong quá trình tính thuế của phụ trợ và đề xuất cách khắc phục cho logic máy chủ.

Một số lưu ý quan trọng liên quan đến ví dụ về công cụ này:

• Bảo mật và xác thực: Bạn không cần chuyển thông tin đăng nhập cơ sở dữ liệu cho tác nhân AI. Lệnh gọi fetch sử dụng phiên đăng nhập hiện tại của trình duyệt để cho phép yêu cầu trên phụ trợ của bạn.
• Gỡ lỗi có thể thực hiện: Nếu tác nhân AI xác định lỗi giao diện người dùng, tác nhân đó có thể gọi ngay queryDatabaseTable để xem lỗi có tồn tại trong dữ liệu nguồn hay trong quá trình tính toán ở giao diện người dùng hay không.
• Thiết lập tối thiểu: Bạn chỉ cần hiển thị một điểm gỡ lỗi "an toàn" (chỉ đọc) trên máy chủ chấp nhận tên bảng và trả về JSON. Khung bạn sử dụng để tạo điểm cuối đó không quan trọng.