เปิดเผยสถานะแอปพลิเคชันที่กำหนดเองต่อเอเจนต์ AI ด้วยเครื่องมือของบุคคลที่สาม

Matthias Rohmer

José Luis Zapata

เครื่องมือสำหรับนักพัฒนาซอฟต์แวร์ของบุคคลที่สามช่วยให้ Agent เขียนโค้ดมองเห็นได้มากกว่า DOM, คำขอเครือข่าย และบันทึกคอนโซล การแสดงเครื่องมือที่กำหนดเองจากเว็บไซต์ หรือเฟรมเวิร์กโดยตรงจะช่วยให้เอเจนต์โต้ตอบกับสถานะและข้อมูลของแอปพลิเคชันที่เข้าถึงไม่ได้

เครื่องมือเหล่านี้สร้างขึ้นผ่าน JavaScript และเครื่องมือสำหรับนักพัฒนาเว็บใน Chrome จะค้นพบเครื่องมือเหล่านี้โดยอัตโนมัติสำหรับตัวแทนเมื่อหน้าเว็บโหลด

ทำความเข้าใจเครื่องมือสำหรับนักพัฒนาแอปของบุคคลที่สาม

ในบริบทของ Agent การเขียนโค้ด เครื่องมือคือฟังก์ชันสำเร็จรูปสำหรับ Agent เพื่อ ดำเนินการที่เฉพาะเจาะจง สำหรับ DevTools สำหรับเอเจนต์โดยเฉพาะ เครื่องมือดังกล่าวสามารถ เปิดเผยสถานะรันไทม์ภายในต่อเอเจนต์การเขียนโค้ดโดยตรง ซึ่งจะช่วยลดช่องว่าง ระหว่างเอาต์พุตที่แสดงผลกับตรรกะภายใน

โปรดคำนึงถึงสิ่งต่อไปนี้เมื่อใช้เครื่องมือของบุคคลที่สาม

• การค้นพบรันไทม์ ระบบจะตรวจหาเครื่องมือโดยอัตโนมัติเมื่อแอปพลิเคชันตอบสนองต่อเหตุการณ์ devtoolstooldiscovery ที่ Chrome DevTools ปล่อยออกมาสำหรับเอเจนต์ในออบเจ็กต์ window ทั่วโลก
• ขอบเขตบริบท เครื่องมือจะทำงานภายในบริบทของหน้าที่กำหนดเครื่องมือเท่านั้น และจะไม่คงอยู่เมื่อมีการเปลี่ยนแหล่งที่มาและโหลดหน้าเว็บซ้ำ
• ความเฉพาะเจาะจงของเครื่องมือ เครื่องมือเป็นเพียงอีกวิธีหนึ่งที่ Agent ใช้ ทำงาน โดยอาจเลือกใช้เครื่องมือในตัวหรือความสามารถของโมเดลเปล่าๆ เพื่อตอบสนองพรอมต์ ดังนั้นโปรดตั้งชื่อและคำอธิบายเครื่องมือให้สื่อความหมายมากที่สุด

ข้อกำหนดเบื้องต้น

ก่อนติดตั้งใช้งานเครื่องมือของบุคคลที่สาม โปรดตรวจสอบว่าคุณมีคุณสมบัติตรงตามข้อกำหนดต่อไปนี้

• เครื่องมือสำหรับนักพัฒนาเว็บใน Chrome สำหรับตัวแทน ใช้เวอร์ชัน 0.25.0 ขึ้นไป
• เปิดใช้ JavaScript เปิดใช้และเรียกใช้ JavaScript

ติดตั้งใช้งานเครื่องมือ

หากต้องการใช้เครื่องมือ คุณต้องรอฟังเหตุการณ์การค้นพบบางอย่างและตอบกลับด้วย คำจำกัดความของเครื่องมือ โค้ดต่อไปนี้แสดงการตอบกลับที่มีคำจำกัดความของเครื่องมือ

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;
          },
        },
      ],
    });
  },
);

วิธีลงทะเบียนเครื่องมือในแอปพลิเคชัน

1. กำหนดกลุ่มเครื่องมือ สร้าง ToolGroup ที่มีชื่อ คำอธิบาย และอาร์เรย์ของคำจำกัดความเครื่องมือแต่ละรายการ

   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. รอฟังเหตุการณ์การค้นพบ เครื่องมือสำหรับนักพัฒนาเว็บใน Chrome สำหรับเอเจนต์จะส่งเหตุการณ์ devtoolstooldiscovery ที่กำหนดเองในออบเจ็กต์ window ทั่วโลกหลังจาก การนำทางแต่ละครั้งและเมื่อใดก็ตามที่ต้องการรายการเครื่องมือที่พร้อมใช้งานที่อัปเดตแล้ว

3. ลงทะเบียนเครื่องมือ เรียกใช้เมธอด respondWith() ของเหตุการณ์เพื่อระบุ กลุ่มเครื่องมือของคุณให้ตัวแทน

องค์ประกอบสำคัญสำหรับเครื่องมือแต่ละอย่าง

คำจำกัดความของเครื่องมือทุกรายการที่คุณใช้ต้องมี 3 ส่วนต่อไปนี้

• ชื่อและคำอธิบาย ซึ่งจะให้วิธีการที่เอเจนต์ใช้เพื่อ ตัดสินใจว่าจะเรียกใช้เครื่องมือของคุณเมื่อใดและอย่างไร
• สคีมาอินพุต สคีมา JSON ที่กำหนดโครงสร้างและประเภทของอาร์กิวเมนต์ที่เครื่องมือคาดหวัง
• ฟังก์ชันการดำเนินการ โค้ด JavaScript จริงที่ทำงานในหน้าเว็บ เมื่อตัวแทนเรียกใช้เครื่องมือ

ตัวอย่างต่อไปนี้แสดงคอมโพเนนต์ทั้ง 3 รายการนี้ในการกำหนดเครื่องมือเดียว

{
  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;
  },
}

กรณีการใช้งานเครื่องมือสำหรับนักพัฒนาซอฟต์แวร์ของบุคคลที่สาม

สั่งให้ตัวแทนตรวจสอบตรรกะของแอปพลิเคชันในระดับลึกแทนที่จะตรวจสอบเพียงองค์ประกอบ UI ระดับพื้นผิว ใช้เครื่องมือที่กำหนดเองเหล่านี้เพื่อเพิ่มประสิทธิภาพการแก้ไขข้อบกพร่องของแอปพลิเคชันที่มีสถานะหรือใช้เฟรมเวิร์กหนักๆ

เคล็ดลับในการค้นพบเครื่องมือ

เขียนชื่อและคำอธิบายเครื่องมือที่สื่อความหมายได้ดี Agent ใช้คำอธิบายเหล่านี้ เป็นบริบทในการตัดสินใจว่าจะใช้เครื่องมือใด ภาษาที่ชัดเจนจะช่วยให้ Agent สามารถพิจารณาได้ด้วยตนเองว่าเมื่อใดที่เครื่องมือหนึ่งๆ เหมาะสมกับงาน

แก้ไขข้อบกพร่องของเมตริกเวลาทำงานเฉพาะแอปพลิเคชัน

ปัญหาต่างๆ เช่น แคชที่ไม่พบโดยไม่มีการแจ้งเตือนหรือการเรียก API ที่ซ้ำซ้อน มักจะมองไม่เห็นในการตรวจสอบมาตรฐาน การแสดงสถิติภายในจะช่วยให้เอเจนต์อธิบายสาเหตุที่เกิดลักษณะการทำงานหนึ่งๆ ได้

สมมติว่าคุณมีฟังก์ชันที่แสดงสถิติภายใน ขั้นแรกคุณต้องสร้างเครื่องมือแบบนี้

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();
        }
      }
    ]
  });
});

หากคำอธิบายเครื่องมือชัดเจน เอเจนต์อาจใช้เครื่องมือโดยอัตโนมัติ เมื่อเห็นว่าเหมาะสม คุณสามารถแจ้งให้เอเจนต์ทำงานโดยใช้เครื่องมือ เช่นเดียวกับตัวอย่างต่อไปนี้

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.

ตัวอย่างการดำเนินการของ Agent: Agent ตรวจพบเครื่องมือ getCacheStatistics ที่แอปพลิเคชันของคุณแสดง ซึ่งจะเรียกใช้เครื่องมือ วิเคราะห์อัตราการเข้าชมต่อการไม่พบข้อมูลที่แคช และระบุว่าส่วนหน้ากำลังดึงข้อมูลไปที่ไปป์ไลน์ทั้งหมดโดยไม่จำเป็นแทนที่จะอัปเดตแคชในเครื่อง

การตรวจสอบฟีเจอร์แฟล็ก

กําหนดจุดข้อมูลที่กําหนดเองเพื่อแสดงตัวแปรสภาพแวดล้อมปัจจุบันหรือฟีเจอร์ Flag ที่ใช้งานอยู่สําหรับเซสชันของผู้ใช้ที่เฉพาะเจาะจง ซึ่งจะช่วยให้คุณแก้ไขข้อบกพร่องได้ว่าเหตุใดผู้ใช้บางรายจึงเห็นหรือไม่เห็นฟีเจอร์บางอย่าง หากผู้ใช้รายงานข้อบกพร่อง เจ้าหน้าที่สามารถตรวจสอบได้ว่าผู้ใช้เป็นกลุ่มทดสอบที่อาจทำให้เกิดปัญหาหรือไม่

ตัวอย่างเช่น สร้างเครื่องมือแบบนี้เพื่อแสดงผลสถานะแฟล็กฟีเจอร์ภายใน

// 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'
          };
        }
      }
    ]
  });
});

หากคำอธิบายเครื่องมือชัดเจน เอเจนต์อาจใช้เครื่องมือโดยอัตโนมัติ เมื่อเห็นว่าเหมาะสม คุณสามารถแจ้งให้เอเจนต์ทำงานโดยใช้เครื่องมือ เช่นเดียวกับตัวอย่างต่อไปนี้

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

ตัวอย่างการดำเนินการของ Agent: Agent ของคุณเรียกใช้getFeatureFlagsเครื่องมือ ยืนยันว่าnew-ui-enabledแฟล็กทำงานอยู่ และดำเนินการดีบัก คอมโพเนนต์ที่เชื่อมโยงกับอินเทอร์เฟซใหม่

ตรวจสอบสถานะแอปพลิเคชันทั่วโลก

เปิดเผยแผนผังสถานะรันไทม์ของแอปพลิเคชันเพื่อช่วยให้เอเจนต์เข้าใจ ตรรกะภายในโดยไม่ต้องดึงข้อมูล DOM ทั้งหมด

คุณสามารถสร้างเครื่องมือแบบนี้เพื่อค้นหาเส้นทางที่เฉพาะเจาะจงในแผนผังสถานะได้ เช่น

// 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);
        }
      }
    ]
  });
});

หากคำอธิบายเครื่องมือชัดเจน เอเจนต์อาจใช้เครื่องมือโดยอัตโนมัติ เมื่อเห็นว่าเหมาะสม คุณสามารถแจ้งให้เอเจนต์ทำงานโดยใช้เครื่องมือ เช่นเดียวกับตัวอย่างต่อไปนี้

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.

ตัวอย่างการดำเนินการของ Agent: Agent ของคุณเรียกใช้ getGlobalState โดยมีพารามิเตอร์ path โดยจะดึงรายการสินค้าจากรถเข็นและระบุ ความคลาดเคลื่อนระหว่างสถานะภายในกับสินค้าที่แสดงในหน้าเว็บ

หมายเหตุสำคัญบางประการเกี่ยวกับตัวอย่างเครื่องมือนี้มีดังนี้

• ตรรกะที่แยกออกจากกัน: AI Agent จะขอ "สถานะ" คุณในฐานะนักพัฒนาแอป เป็นผู้กำหนดวิธีแมปคำขอนั้นกับโครงสร้างข้อมูลจริงในexecute ฟังก์ชัน
• การแก้ไขข้อบกพร่องที่กำหนดเป้าหมาย: การใส่พารามิเตอร์ path จะช่วยให้ตัวแทนหลีกเลี่ยงการดึงแผนผังสถานะทั้งหมด (ซึ่งอาจมีขนาดใหญ่มาก) และมุ่งเน้นเฉพาะส่วนที่เกี่ยวข้อง ซึ่งจะช่วยประหยัดโทเค็นและปรับปรุงประสิทธิภาพ
• อินเทอร์เฟซที่ได้มาตรฐาน: แม้ว่าคุณจะเปลี่ยนไลบรารีการจัดการสถานะ แต่ตราบใดที่คุณอัปเดตฟังก์ชัน execute นี้ ตัวแทนการแก้ไขข้อบกพร่อง AI ก็ไม่จำเป็นต้องมีคำสั่งหรือเครื่องมือใหม่

ตรวจสอบเนื้อหาในฐานข้อมูล

ยืนยันว่าข้อมูลแบ็กเอนด์ตรงกับสถานะ UI โดยการค้นหาระเบียนฐานข้อมูล โดยตรงผ่านปลายทางการแก้ไขข้อบกพร่องแบบอ่านอย่างเดียว

เปิดเผยปลายทางการแก้ไขข้อบกพร่องที่ปลอดภัยและสร้างเครื่องมือเช่นเครื่องมือนี้เพื่อยืนยันบันทึกของแบ็กเอนด์

// 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}` };
          }
        }
      }
    ]
  });
});

หากคำอธิบายเครื่องมือชัดเจน เอเจนต์อาจใช้เครื่องมือโดยอัตโนมัติ เมื่อเห็นว่าเหมาะสม คุณสามารถแจ้งให้เอเจนต์ทำงานโดยใช้เครื่องมือ เช่นเดียวกับตัวอย่างต่อไปนี้

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.

ตัวอย่างการดำเนินการของเอเจนต์: เอเจนต์เรียกใช้ queryDatabaseTable สำหรับตารางคำสั่งซื้อ โดยจะดึงข้อมูลระเบียน JSON ระบุข้อผิดพลาดในการคำนวณภาษีของแบ็กเอนด์ และแนะนำวิธีแก้ไขตรรกะของเซิร์ฟเวอร์

หมายเหตุสำคัญบางประการเกี่ยวกับตัวอย่างเครื่องมือนี้มีดังนี้

• ความปลอดภัยและการตรวจสอบสิทธิ์: คุณไม่จำเป็นต้องส่งต่อข้อมูลเข้าสู่ระบบฐานข้อมูล ไปยัง AI Agent การเรียกใช้ fetch จะใช้เซสชันการเข้าสู่ระบบปัจจุบันของเบราว์เซอร์ เพื่อให้สิทธิ์คำขอในแบ็กเอนด์
• การแก้ไขข้อบกพร่องที่นำไปใช้ได้จริง: หากเอเจนต์ AI พบข้อบกพร่องใน UI เอเจนต์จะ เรียกใช้ queryDatabaseTable ทันทีเพื่อดูว่าข้อผิดพลาดนั้นมีอยู่ใน ข้อมูลต้นทางหรือการคำนวณส่วนหน้าหรือไม่
• การตั้งค่าขั้นต่ำ: คุณเพียงแค่ต้องเปิดเผยปลายทางการแก้ไขข้อบกพร่องแบบ "ปลอดภัย" (อ่านอย่างเดียว) 1 รายการในเซิร์ฟเวอร์ที่ยอมรับชื่อตารางและแสดงผล JSON ไม่ว่าคุณจะใช้เฟรมเวิร์กใดในการสร้างปลายทางนั้น