서드 파티 도구를 사용하여 맞춤 애플리케이션 상태를 AI 에이전트에 노출

서드 파티 개발자 도구를 사용하면 코딩 에이전트가 DOM, 네트워크 요청, 콘솔 로그를 넘어 확인할 수 있습니다. 웹사이트 또는 프레임워크에서 직접 커스텀 도구를 노출하면 에이전트가 액세스할 수 없는 애플리케이션 상태 및 데이터와 상호작용할 수 있습니다.

이러한 도구는 JavaScript를 통해 생성되며 페이지가 로드될 때 에이전트용 Chrome DevTools에서 자동으로 검색됩니다.

서드 파티 개발자 도구 이해

코딩 에이전트의 컨텍스트에서 도구는 에이전트가 특정 작업을 실행할 수 있는 즉시 사용 가능한 함수입니다. 특히 에이전트용 DevTools의 경우 이러한 도구는 내부 런타임 상태를 코딩 에이전트에 직접 노출하여 렌더링된 출력과 내부 로직 간의 격차를 해소할 수 있습니다.

서드 파티 도구를 사용할 때는 다음 사항에 유의하세요.

  • 런타임 검색. 애플리케이션이 전역 window 객체에서 에이전트용 Chrome DevTools에서 내보낸 devtoolstooldiscovery 이벤트에 응답하면 도구가 자동으로 감지됩니다.
  • 컨텍스트 범위. 도구는 도구를 정의하는 페이지의 컨텍스트 내에서만 실행됩니다. 출처 및 페이지 새로고침 간에 유지되지 않습니다.
  • 도구 구체성. 도구는 에이전트가 작업을 실행하는 추가 방법일 뿐입니다. 프롬프트를 충족하기 위해 기본 제공 도구 또는 기본 모델 기능을 선호할 수 있습니다. 따라서 도구 이름과 설명을 최대한 설명적으로 작성하세요.

기본 요건

서드 파티 도구를 구현하기 전에 다음 요구사항을 충족하는지 확인하세요.

  • 에이전트용 Chrome DevTools. 버전 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 DevTools는 각 탐색 후와 사용 가능한 도구의 업데이트된 목록이 필요할 때마다 전역 window 객체에서 커스텀 devtoolstooldiscovery 이벤트를 디스패치합니다.

  3. 도구 등록. 이벤트의 respondWith() 메서드를 호출하여 도구 그룹을 에이전트에 제공합니다.

개별 도구의 필수 구성요소

구현하는 모든 도구 정의에는 다음 세 가지 부분이 포함되어야 합니다.

  • 이름 및 설명. 에이전트가 도구를 호출할 시점과 방법을 결정하는 데 사용하는 안내를 제공합니다.
  • 입력 스키마. 도구가 예상하는 인수 구조와 유형을 정의하는 JSON 스키마입니다.
  • 실행 함수. 에이전트가 도구를 호출할 때 페이지에서 실행되는 실제 JavaScript 코드입니다.

다음 예에서는 단일 도구 정의에서 이러한 세 가지 구성요소를 보여줍니다.

{
  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 요소뿐만 아니라 심층 애플리케이션 로직을 검사하도록 안내합니다. 이러한 커스텀 도구를 사용하여 상태 저장 또는 프레임워크가 많은 애플리케이션의 디버깅을 간소화합니다.

도구 검색 도움말

설명적인 도구 이름과 설명 을 작성합니다. 에이전트는 이러한 설명을 컨텍스트로 사용하여 사용할 도구를 결정합니다. 명확한 언어를 사용하면 에이전트가 작업에 적합한 도구를 자율적으로 결정하는 데 도움이 됩니다.

애플리케이션별 런타임 측정항목 디버그

자동 캐시 누락 또는 중복 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.

에이전트 실행 예: 에이전트가 애플리케이션에서 노출하는 getCacheStatistics 도구를 감지합니다. 도구를 호출하고 반환된 적중 대 누락 비율을 분석하며 프런트엔드가 로컬 캐시를 업데이트하는 대신 전체 파이프라인을 불필요하게 다시 가져오고 있음을 확인합니다.

기능 플래그 확인

특정 사용자 세션에 활성 상태인 현재 환경 변수 또는 기능 플래그를 노출하도록 커스텀 데이터 포인트를 정의합니다. 이렇게 하면 특정 사용자에게 특정 기능이 표시되거나 표시되지 않는 이유를 디버그하는 데 도움이 됩니다. 사용자가 버그를 신고하면 에이전트가 문제를 일으킬 수 있는 실험 그룹에 있는지 확인할 수 있습니다.

예를 들어 다음과 같은 도구를 만들어 내부 기능 플래그 상태를 반환합니다.

// 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.

에이전트 실행 예: 에이전트가 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.

에이전트 실행 예: 에이전트가 getGlobalStatepath 매개변수와 함께 호출합니다. 장바구니에서 항목 목록을 가져오고 내부 상태와 페이지에 렌더링된 항목 간의 불일치를 확인합니다.

이 도구 예와 관련된 몇 가지 중요한 참고사항은 다음과 같습니다.

  • 분리된 로직: AI 에이전트가 "상태"를 요청합니다. 개발자는 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 에이전트에 전달할 필요가 없습니다. fetch 호출은 브라우저의 현재 로그인 세션을 사용하여 백엔드에서 요청을 승인합니다.
  • 실행 가능한 디버깅: AI 에이전트가 UI 버그를 식별하면 즉시 queryDatabaseTable를 호출하여 오류가 소스 데이터 또는 프런트엔드 계산에 있는지 확인할 수 있습니다.
  • 최소 설정: 테이블 이름을 허용하고 JSON을 반환하는 서버에서 '안전한'(읽기 전용) 디버그 엔드포인트 하나만 노출하면 됩니다. 해당 엔드포인트를 빌드하는 데 사용하는 프레임워크는 중요하지 않습니다.