브라우저 AI 기능을 활용한 이커머스 결제 개선

1. 소개

최신 웹 개발은 AI 사용을 위한 클라우드 기반 왕복의 대안을 제공합니다. Chrome은 번역을 위한 소규모 전문가 모델부터 성능이 뛰어난 증류된 전체 언어 모델까지 모든 것을 사용할 수 있는 내장 AI API를 제공하기 시작했습니다. 이 API는 사용자 또는 개발자에게 토큰 비용이 청구되지 않으며 기기에서 비공개로 실행됩니다.

동시에 AI 에이전트는 사용자가 웹 애플리케이션과 상호작용할 수 있는 새로운 방법을 제공하며, WebMCP를 사용하여 웹 환경을 에이전트 지원으로 만들면 스크린샷과 DOM 스크래핑이 필요한 기존 작동보다 더 정확한 결과를 제공하면서 토큰 사용량을 줄일 수 있습니다.

이 Codelab에서는 아웃도어 장비 전자상거래 사이트인 Mont-Royal Plein Air를 사용합니다. 내장 AI API와 WebMCP를 빌드하고 통합하여 다음 작업을 하는 방법을 알아봅니다.

1. 방문 기록에서 고객 의도를 추론하고 온디바이스 모델을 사용하여 고객에게 추천을 동적으로 빌드합니다.
2. 도구 에이전트와 브라우저 어시스턴트가 사이트를 탐색하고, 제품과 추천을 검사하고, 사용자의 장바구니를 관리하는 데 사용할 수 있는 도구를 노출합니다.
3. (선택사항) 소규모 온디바이스 전문가 모델을 사용하여 사이트를 즉석에서 번역합니다.
4. (선택사항) 외부 에이전트가 사용하는 것과 동일한 도구를 사용하여 기본 사이트 검색을 온사이트 에이전트로 변환합니다.

학습할 내용

• Prompt API를 사용하고 구조화된 JSON 출력을 강제하는 방법
• WebMCP 도구를 등록하는 방법과 도구 구성 및 세부사항에 관한 전략
• (선택사항) 기기 내 전문가 모델을 사용하여 Translator API로 콘텐츠를 빠르게 번역하는 방법
• (선택사항) WebMCP 도구를 직접 호출하는 방법

기본 요건

• 개인 Google 계정 및 Google Cloud
• #enable-webmcp-testing 및 #devtools-webmcp-support 플래그가 사용 설정된 Google Chrome 버전 150 이상 또는 Canary, 개발자 또는 베타 채널
• HTML, CSS, JavaScript, TypeScript에 대한 이해
• JSON 스키마에 대한 이해

2. 프로젝트 설정

Google 계정

아직 개인 Google 계정이 없다면 Google 계정을 만들어야 합니다.

Google Cloud 콘솔에 로그인

개인 Google 계정을 사용하여 Google Cloud 콘솔에 로그인합니다.

결제 사용 설정

도움말: Google Cloud 크레딧을 사용하여 결제를 설정한 경우 이 단계를 건너뛸 수 있습니다.

개인 결제 계정을 설정하려면 Cloud 콘솔에서 결제를 사용 설정하세요.

프로젝트 만들기(선택사항)

이 실습에 사용할 현재 프로젝트가 없는 경우 여기에서 새 프로젝트를 만드세요.

Cloud Shell 편집기 열기

1. 이 링크를 클릭하여 Cloud Shell 편집기로 바로 이동합니다.
2. 오늘 언제든지 승인하라는 메시지가 표시되면 승인을 클릭하여 계속합니다.
3. 터미널이 화면 하단에 표시되지 않으면 다음을 통해 엽니다.
   • 보기를 클릭합니다.
   • 터미널을 클릭합니다.

프로젝트 설정

1. 터미널에서 다음 명령어를 사용하여 프로젝트를 설정합니다.

   gcloud config set project [PROJECT_ID]
   

   예: gcloud config set project lab-project-id-example

   프로젝트 ID가 기억나지 않는 경우 gcloud projects list를 사용하여 모든 프로젝트 ID를 나열할 수 있습니다.

   
2. 다음 메시지가 표시됩니다. Updated property [core/project].

   WARNING가 표시되고 Do you want to continue (Y/n)?라는 메시지가 표시되면 프로젝트 ID를 잘못 입력한 것일 수 있습니다. n를 누르고 Enter를 누른 다음 gcloud config set project 명령어를 다시 실행해 보세요.

로컬 및 작업공간 설정

1. 터미널 (또는 Cloud Shell 터미널)에서 프로젝트 저장소를 클론하고 프로젝트 디렉터리로 이동합니다.

   git clone https://github.com/GoogleChromeLabs/codelabs mont-royal
   cd mont-royal
   

2. ecommerce-ai-enhancements/starter 폴더로 이동합니다.

   cd ecommerce-ai-enhancements/starter
   

3. pnpm를 사용하여 종속 항목을 설치합니다.

   pnpm install
   

4. 로컬 개발 서버를 시작합니다.

   pnpm dev
   

   브라우저를 열어 http://localhost:5173에서 Mont-Royal Plein Air 스토어를 확인합니다.

(선택사항) WebMCP 인스펙터 확장 프로그램 설치

WebMCP를 더 쉽게 사용할 수 있도록 WebMCP 모델 컨텍스트 도구 검사기를 설치할 수 있습니다. 설치 후 사용하려면 Gemini API 키를 가져와야 합니다.

• AI Studio로 이동합니다.
• API 키 만들기 버튼을 클릭하여 이 단계에서 이전에 설정한 프로젝트에 연결된 새 Gemini API 키를 생성합니다.
• WebMCP 모델 컨텍스트 도구 인스펙터 (측면 패널에서 열림)를 열고 Gemini API 키 업데이트 버튼을 클릭합니다.
• 팝업에 API 키를 붙여넣고 저장합니다.

이 확장 프로그램에는 WebMCP를 사용할 수 있는 기본 에이전트가 있어 DevTools를 통해 WebMCP 도구를 직접 호출하는 대신 이를 통해 웹사이트를 사용해 볼 수 있습니다.

3. 웹의 기본 AI 모델

Prompt API란 무엇인가요?

프롬프트 API를 사용하면 웹 애플리케이션이 사용자 기기에서 완전히 실행되는 소규모 멀티모달 언어 모델에 직접 액세스할 수 있습니다. 추론이 로컬에서 실행되므로 다음 사항에 유의하세요.

• 제로 클라우드 지연 시간: 네트워크 왕복이나 백엔드 서버 대기열이 없습니다.
• 기본적으로 비공개: 프롬프트와 프롬프트에 전달된 컨텍스트는 기기 외부로 유출되지 않습니다.
• 비용 제로: 토큰 청구 또는 클라우드 호스팅 비용 없이 클라이언트 하드웨어에서 추론이 실행됩니다.
• 오프라인 지원: 인터넷에 연결되어 있지 않아도 안정적으로 작동합니다.

Chrome에서 Prompt API는 전역 LanguageModel 인터페이스를 통해 액세스됩니다.

// 1. Set your expected inputs and outputs. This is multimodal, so you can
// include other types here, too
const languages = {
   expectedInputs: [{type: "text", languages: ["en"]}],
   expectedOutputs: [{type: "text", languages: ["en"]}],
}

// 2. Check availability. Always pass in your expected inputs and outputs,
// as some models may only support some inputs and outputs
const availability = await LanguageModel.availability(languages);
// 'available', 'downloading', or 'unavailable'

// 3. Create an isolated session with system prompt and language constraints
const session = await LanguageModel.create({
  ...languages,
  // Optional: add initial context to your session, like a system prompt
  initialPrompts: [
   {
      role: 'system',
      content: 'You are an expert outdoors sales assistant...'
   }
  ]
});

// 4. Define your expected output as JSON Schema
const schema = {
   //...
}

// 5. Prompt the model (supports plain text or structured models)
const result = await session.prompt('Recommend a 3-season tent footprint.', {
  responseConstraint: schema,
});

메모리 관리 권장사항:

• 세션을 clone()하여 전체 컨텍스트 윈도우 상태를 복사하고 클론을 독립적으로 사용하여 새 세션을 가동하는 데 걸리는 시간을 줄일 수 있습니다.
• 세션 사용이 완료되면 destroy()하여 리소스를 확보합니다.

연습 1: 여정 기반 추천

이커머스 사이트에는 일반적으로 '함께 자주 구매된 상품'의 캐러셀이나 업셀이 있습니다. 아웃도어 사이트와 같은 경우에는 탐색 기록을 기반으로 추천을 생성하는 것이 더 유용할 수 있습니다.

이를 위해 다음 세 단계로 구성된 추천 파이프라인을 빌드합니다.

1. 여정 프로파일러: Prompt API를 사용하여 고객의 시간순 탐색 타임라인을 분석하여 사용자의 진정한 모험 의도를 추론합니다.
2. 제품 쿼리: 이 인텐트에서 가짜 제품 백엔드에 API 요청을 보내 관련 상품을 가져옵니다.
3. 제품 추천: 이러한 제품을 제품 API에 다시 전달하여 순위를 매기고 사용자가 보고 있는 항목과 가장 일관성이 있는 5개의 제품을 반환합니다.

태스크 1.1: Prompt API 초기화

프롬프트 API를 사용할 때마다 개별적으로 초기화하는 대신 호출을 단일 파일로 중앙 집중화하고 시스템 프롬프트로 생성을 메모이제이션하여 동일한 에이전트에 대한 여러 호출의 시작 시간을 줄입니다.

src/ai/prompt-api.ts 파일로 이동하여 27~58번째 줄에서 getPromptSession()을 검사합니다.

export async function getPromptSession(
  systemPrompt: string = '',
  options: { signal?: AbortSignal } = {}
): Promise<LanguageModel>

1. 캐시된 기본 세션을 재사용합니다. 시스템 프롬프트로 키가 지정된 캐시 맵이 21번째 줄(baseSessions)에 이미 있습니다. 새 기본 모델을 clone()하는 대신 기본 모델을 재사용하면 시작 시간이 단축되고 각 세션이 서로 방해하지 않고 핵심 설정을 상속받습니다. 클론 반환: 호출자는 캐시된 기본값을 삭제하지 않고도 자유롭게 클론과 상호작용할 수 있습니다(destroy() 포함).
2. API의 기능 감지 API가 있으면 기능 감지, 없으면 오류 발생
3. 모달리티와 언어를 선언합니다. 기본 제공 모델은 멀티모달 입력을 지원할 수 있습니다. 필요한 모드와 지원하려는 언어를 선언해야 합니다. LLM에 전달하는 모든 콘텐츠는 영어로 되어 있습니다.
4. 무언가를 만들기 전에 사용 가능 여부를 확인하세요. API가 있더라도 요구사항을 지원하는 모델이 없을 수 있습니다. 하나가 있는지 확인합니다. 그렇지 않으면 오류를 발생시킵니다. 아직 다운로드되지 않은 경우 다운로드 진행률을 보고합니다.
5. 세션을 만듭니다. 새 Prompt API 세션을 만들 옵션과 시스템 프롬프트(포함된 경우)를 설정합니다.

작업 1.2: 여정 프로파일러 구현

src/ai/journey-profiler.ts 파일로 이동하여 42~100번째 줄에서 타겟 함수를 검사합니다.

export async function inferJourneyProfile(
  context: ProfilerInputContext,
  catalogMap: ReadonlyMap<string, Product>
): Promise<JourneyProfile>

1. 작업 1의 함수를 사용하여 사용할 새 프롬프트 세션을 생성합니다.
2. 구조화된 반환을 위해 JSON 스키마로 journeyProfileSchema를 사용하여 제공된 프롬프트 텍스트로 모델에 프롬프트를 표시합니다.
3. 프롬프트 출력을 파싱하고 타겟 카테고리를 중복 삭제합니다.
4. 하드코딩된 문자열 반환을 프롬프트의 실제 결과로 바꿉니다.
5. 세션이 완료되면 세션을 소멸시켜 메모리를 확보합니다.

src/utils/journey-helpers.ts를 읽고 컨텍스트 수집이 프롬프트로 변환되는 방식을 확인하세요.

작업 1.3: 시너지 재순위 지정 도구 구현

src/ai/synergy-reranker.ts 파일로 이동하여 30~71번째 줄에서 타겟 함수를 검사합니다.

export async function rankComplementaryGear(
  profile: JourneyProfile,
  candidates: readonly Product[],
  currentProduct?: Product | null,
  cartProducts?: readonly Product[],
  limit: number = 5
): Promise<readonly RecommendedItem[]>

1. 작업 1의 함수를 사용하여 사용할 새 프롬프트 세션을 생성합니다.
2. 제공된 프롬프트 텍스트와 생성된 스키마로 모델에 프롬프트를 표시합니다.
3. 프롬프트 출력을 파싱합니다.
4. assembleRecommendations를 사용하여 조립된 추천 목록을 반환합니다.
5. 세션이 완료되면 세션을 소멸시켜 메모리를 확보합니다.

src/utils/reranker-helpers.ts 및 src/utils/recommendation-schemas.ts을 읽고 프롬프트와 스키마가 생성되는 방식과 프롬프트 결과에서 추천이 조립되는 방식을 확인하세요.

추천 파이프라인 확인

1. Chrome을 열어 http://localhost:5173/catalog/tent-mont-tremblant-3p로 이동합니다.
2. 추천 섹션까지 아래로 스크롤합니다.
3. 5개의 동반자 카드가 무작위 제품이 아닌 스마트 키트 페어링 (예: 지면 발자국, 슬리핑 패드, 경량 스테이크)을 반영하도록 업데이트되는 방식을 확인합니다.
4. Chrome DevTools 콘솔을 열어 두 추론 단계의 실시간 실행 시간을 검사합니다.

(선택사항) 작업 1.4: 더 많은 내장 AI 모델 살펴보기

Translator API 전문가 모델을 비롯한 여러 기본 제공 AI 모델을 사용할 수 있습니다. 이 코드베이스의 구성요소는 이미 현재 언어의 변경사항을 수신 대기하고 번역을 요청하는 서비스에 연결되어 있으며, 여러분은 이 모든 것을 연결해야 합니다.

src/ai/translator.ts 파일로 이동합니다.

29~45번째 줄에서 타겟 함수 createTranslator를 검사합니다.

export async function createTranslator(
  targetLang: SupportedLanguage
): Promise<Translator | null>

1. Translator API 지원을 확인하고 타겟 언어가 영어 (콘텐츠는 기본적으로 영어로 제공됨)가 아닌지 확인합니다.
2. 영어에서 타겟 언어로 된 언어 쌍을 빌드하고 해당 쌍이 사용 가능한지 확인합니다.
3. 번역기 옵션을 만들고 모델 다운로드 진행률을 모니터에 표시합니다.
4. 초기화된 변환기를 반환합니다.

다음으로 50~58번째 줄에서 타겟 함수 translate를 검사합니다.

export async function translate(
  text: string,
  targetLang: SupportedLanguage
): Promise<string>

5. targetLang을 전달하는 getCachedTranslator로 사용할 수 있는 번역기가 있는지 확인합니다. 그렇지 않으면 정리된 텍스트를 반환합니다.
6. 있는 경우 번역기를 사용하여 깨끗한 텍스트를 번역합니다.

src/ai/translator.ts 파일로 이동합니다.

204번째 줄에서 타겟 함수 render를 검사합니다.

export async function translate(
  text: string,
  targetLang: SupportedLanguage
): Promise<string>

7. 언어 선택 도구 구성요소 사용 설정

src/utils/translator-helpers.ts를 읽고 번역 캐시와 구독이 어떻게 작동하는지 확인하세요.

4. WebMCP를 사용하여 에이전트 환경 개선

WebMCP란 무엇인가요?

사용자가 자율 에이전트와 공동 탐색 에이전트를 사용하기 시작하면서 웹사이트가 이에 적응하는 것이 중요해졌습니다. 에이전트는 일반적으로 스크린샷을 찍고 DOM과 접근성 트리를 스크랩하는 실행을 통해 사이트와 상호작용하는 방법을 결정합니다. 이 방법은 느리고 불안정하며 오류가 발생하기 쉬우며 사용자 토큰을 낭비합니다.

WebMCP를 사용하면 개발자가 에이전트가 현재 페이지와 상호작용할 수 있는 도구를 에이전트에게 직접 제공할 수 있으므로 이 문제를 해결할 수 있습니다. 이러한 도구를 지원하는 에이전트는 코딩 하네스의 도구처럼 명확하고 구조화된 입력과 반환 값을 사용하여 도구를 사용할 수 있습니다.

// Register a tool directly on document.modelContext
document.modelContext.registerTool({
  name: 'get_product_specs',
  title: 'Get Product Specs',
  description: 'Retrieve technical specifications for the active product.',
  inputSchema: {
    type: 'object',
    properties: {
      // ...
    },
  },
  annotations: {
    readOnlyHint: true, // Informs the agent this tool causes no side-effects
  },
  execute: async (input) => {
    return {
      weight: '1.8 kg',
      capacity: '3 persons',
      seasons: '3-season',
    };
  },
});

상담사가 웹페이지에 연결되면 document.modelContext.getTools()를 쿼리합니다. 등록된 각 도구는 다음을 노출합니다.

• name: 에이전트가 도구를 실행할 때 사용하는 프로그래매틱 도구 식별자입니다 (예: 'get_product_specs').
• title: 검사기 및 상담사 인터페이스에서 사용하는 사람이 읽을 수 있는 표시 라벨입니다 (예: 'Get Product Specs').
• description: 도구가 하는 일과 도구를 호출해야 하는 시기를 모델에 알리는 일반 텍스트 설명입니다. 에이전트가 도구를 호출해야 하는지 여부를 판단하는 방식이므로 설명이 필요합니다.
• inputSchema: 허용되는 인수를 정의하는 JSON 스키마입니다.
• annotations: 상태 부작용을 일으키지 않는 읽기 전용 도구의 { readOnlyHint: true }와 같은 동작 힌트입니다.
• execute: 도구가 호출될 때 실행되는 비동기 함수입니다.

권장사항: 도구를 얼마나 상세하게 만들어야 하는지에 관한 권장사항은 계속 달라집니다. 에이전트가 자체 사용자 여정을 구축할 수 있는 더 세부적인 도구가 옴니버스 도구보다는 권장사항으로 떠오르고 있으므로 여기에서는 이러한 도구를 소개합니다.

작업 2.1: 추천 및 제품 도구

먼저 에이전트가 이전 연습에서 빌드한 추천을 가져올 수 있도록 도구를 등록합니다.

src/components/product/ForYouSection.ts 파일로 이동합니다.

71~94행에서 registerWebMCPTools()을 검사합니다.

private registerWebMCPTools(): void

1. WebMCP가 지원되는지 확인합니다.
2. 그렇다면 도구를 등록합니다.

• 에이전트가 도구를 선택하도록 유도하는 제목과 설명을 선택합니다. 여기서는 프롬프트 엔지니어링을 고려하세요.
• 입력이 없으므로 빈 객체 JSON 스키마를 포함합니다.
• 읽기 전용 도구입니다.
• 실행 함수에서 recommendationStore를 사용하여 현재 추천 세트를 가져온 다음 현재 제품 ID와 제품 추천 세트를 반환합니다.
• 중단 신호를 추가하고 오류가 발생하지 않도록 이를 포착합니다. 이렇게 하면 구성요소가 마운트 해제될 때 도구가 올바르게 삭제됩니다.

src/views/ProductView.ts 파일로 이동합니다.

3. 동일한 프로세스를 반복하여 get_current_product 도구를 등록합니다. 이번에는 추천뿐만 아니라 전체 제품도 반환합니다.

도움말: 도구 등록은 구성요소 수준에서 이루어지므로 구성요소를 함께 구성하여 페이지를 만들면 도구가 함께 제공됩니다.

작업 2.2: 장바구니 창 도구

src/components/cart/CartDrawer.ts 파일로 이동합니다.

83~114행에서 registerWebMCPTools()을 검사합니다.

private registerWebMCPTools(): void

1. view_cart 도구를 등록합니다.

• inputSchema는 단일 부울 옵션 openDrawer이 있는 객체여야 합니다.
• 읽기 전용이어야 합니다.
• execute 함수의 일부로 입력을 읽고, 장바구니를 표시할지 숨길지 결정하고, recommendationStore을 새로고침한 후 장바구니 요약을 반환합니다.

2. manage_cart 도구를 등록합니다.

• inputSchema는 items이 있는 객체여야 합니다. 은 productID, add, remove, update action enum과 정수 quantity이 있는 객체의 배열입니다.
• execute 함수는 항목을 this.updateCart에 전달해야 합니다.

작업 2.3: 언어 전환 도구

언어 도구를 외부 상담사에게 노출하여 WebMCP를 더욱 발전시키세요.

src/components/navigation/LanguagePicker.ts 파일로 이동합니다.

61~63번째 줄에서 registerWebMCPTools()을 검사합니다.

private registerWebMCPTools(): void

1. switch_language 도구를 등록합니다.
   • inputSchema에는 SUPPORTED_LANGUAGE_CODES의 열거형인 language 속성이 있어야 합니다.
   • execute 함수는 제공된 언어로 this.switchLanguage를 호출해야 합니다.

작업 2.4: 탐색 도구 저장

자율 에이전트가 매장을 탐색하고, 제품 페이지로 이동하고, 카테고리를 탐색하거나 검색을 시작할 수 있도록 지원합니다.

src/components/navigation/SiteHeader.ts 파일로 이동합니다.

155~171행에서 registerWebMCPTools()을 검사합니다.

private registerWebMCPTools(): void

1. WebMCP가 지원되는지 확인합니다.
2. search 도구를 등록합니다.
   • 입력 스키마는 query 문자열을 사용합니다.
   • execute에서 this.search(input?.query)를 호출합니다.
3. go_to_catalog 도구를 등록합니다.
   • 입력 스키마는 선택사항인 activity (ACTIVITIES 열거형) 및 category (PRODUCT_CATEGORIES 열거형)을 허용합니다.
   • execute에서 this.goToCatalog(input?.activity, input?.category)를 호출합니다.
4. get_categories_and_activities 도구를 등록합니다.
   • 입력 매개변수가 없는 읽기 전용 도구입니다.
   • execute에서 this.getCategoriesAndActivities()를 호출합니다.
5. go_to_product 도구를 등록합니다.
   • 입력 스키마에는 productId 문자열이 필요합니다.
   • execute에서 this.goToProduct(input?.productId)를 호출합니다.

WebMCP 검사기로 확인

1. Chrome에서 http://localhost:5173/catalog/tent-mont-tremblant-3p을 새로고침하고 제품 페이지로 이동합니다.
2. Chrome DevTools > Application > WebMCP를 엽니다.
3. WebMCP 도구(get_recommendations, get_current_product, view_cart, manage_cart, switch_language, search, go_to_catalog, get_categories_and_activities, go_to_product)가 표시됩니다.
4. 하나를 클릭하여 세부정보와 매개변수를 확인합니다.
5. 매개변수가 있는 도구를 선택하고 일부를 선택한 다음 도구 실행을 클릭하여 작동하는 모습을 확인합니다.
6. (선택사항) WebMCP Model Context Tool Inspector를 설치하고 설정한 경우 이를 엽니다. Chrome의 측면 패널에 열립니다. 채팅 인터페이스를 사용하여 에이전트에게 도구 중 하나를 호출해야 한다고 생각되는 작업을 수행하도록 지시하여 에이전트의 응답을 확인합니다.

5. (선택사항) 온사이트 에이전트 빌드

페이지 내에서 WebMCP 도구 호출

WebMCP 도구는 외부 브라우저 확장 프로그램이나 서드 파티 봇 전용이 아닙니다. 자체 애플리케이션에서 직접 호출할 수 있습니다. document.modelContext.getTools()를 쿼리하면 클라이언트 측 코드에서 도구를 동적으로 검색하고 실행할 수 있습니다.

이를 사용하여 사이트 내 AI 쇼핑 어시스턴트를 구축하여 검색창을 자연어 입력을 기반으로 하는 제품 탐색 도구로 전환할 수 있습니다. 다수의 패싯 필터를 조정하기 위해 맞춤 명령형 코드를 작성하는 대신 검색창에서 자연어 쿼리를 Prompt API에 전달할 수 있습니다. 그러면 Prompt API에서 호출할 페이지 내 WebMCP 도구를 결정합니다.

권장사항: 빌드 중인 에이전트가 검색창을 대체하지만 사이트 검색에는 LLM을 사용해서는 안 됩니다. 사이트 검색에는 훨씬 더 효율적이고 정확하며 잘 정립된 패턴과 알고리즘이 있습니다. 이는 자체 사이트의 WebMCP 도구를 비결정적으로 호출하는 것을 보여주기 위한 것입니다.

JavaScript에서 WebMCP 도구를 검색하고 호출하려면 다음 단계를 따르세요.

// getTools() returns a Promise — it must be awaited.
const tools = await document.modelContext.getTools();
const tool = tools.find(t => t.name === 'list_items');

const json = await document.modelContext.executeTool(tool, args);
const result = JSON.parse(json); // executeTool resolves with a DOMString

작업 3.1: 사이드바 패싯 도구

에이전트 (및 페이지 내 검색 어시스턴트)가 프로그래매틱 방식으로 필터를 전환할 수 있도록 각 카탈로그 사이드바 패싯을 WebMCP에 노출합니다.

src/components/facets/의 각 패싯 구성요소는 이미 클래스에 도우미 메서드를 제공하고 src/utils/filter-schemas.ts에 내보낸 입력 스키마를 제공합니다.

1. src/components/facets/ActivityFacet.ts:
   • activityFilterSchema을 사용하여 activity_filter를 등록합니다.
   • execute에서 this.filterActivity(input?.activity, input?.selected)를 호출합니다.
2. src/components/facets/CategoryFacet.ts:
   • categoryFilterSchema을 사용하여 category_filter를 등록합니다.
   • execute에서 this.filterCategory(input?.category, input?.selected)를 호출합니다.
3. src/components/facets/ConditionFacet.ts:
   • conditionFilterSchema을 사용하여 condition_filter를 등록합니다.
   • execute에서 this.filterCondition(input?.condition, input?.selected)를 호출합니다.
4. src/components/facets/PriceFacet.ts:
   • priceFilterSchema을 사용하여 price_filter를 등록합니다.
   • execute에서 this.filterPrice(input?.priceRange || input?.bracket, input?.selected)를 호출합니다.
5. src/components/facets/WeightFacet.ts:
   • weightFilterSchema을 사용하여 weight_filter를 등록합니다.
   • execute에서 this.filterWeight(input?.weightRange || input?.bracket, input?.selected)를 호출합니다.
6. src/components/facets/RatingFacet.ts:
   • ratingFilterSchema을 사용하여 rating_filter를 등록합니다.
   • execute에서 this.filterRating(input?.minRating || input?.rating, input?.selected)를 호출합니다.
7. src/components/facets/SearchFacet.ts:
   • keywordFilterSchema을 사용하여 keyword_filter를 등록합니다.
   • execute에서 this.updateKeyword(input?.keyword)를 호출합니다.

2단계에서 배운 대로 WebMCP 지원을 확인하고 .catch(() => {})로 { signal: this.signal }를 전달해야 합니다.

작업 3.2: 카탈로그 보기 도구

이제 document.modelContext에서 카탈로그 수준 등록정보, 필터 재설정, 시맨틱 검색 도구를 등록합니다.

src/views/CatalogView.ts 파일로 이동합니다.

125~140번째 줄에서 registerWebMCPTools()을 검사합니다.

private registerWebMCPTools(): void

1. WebMCP가 지원되는지 확인합니다.
2. list_items 도구를 등록합니다.
   • 입력 매개변수가 없으며 읽기 전용입니다.
   • execute 함수는 this.getItemsSummary()를 호출해야 합니다.
3. reset_filters 도구를 등록합니다.
   • 입력 매개변수를 사용하지 않습니다.
   • execute 함수는 this.resetFilters()를 호출해야 합니다.
4. semantic_catalog_filter 도구를 등록합니다.
   • semanticCatalogFilterSchema을 사용합니다.
   • execute 함수는 interpretAndApplySemanticFilter(input.query)를 호출해야 합니다.

작업 3.3: 시맨틱 필터 에이전트 오케스트레이션

이제 모든 것을 연결할 차례입니다. 이 작업은 검색을 semantic_catalog_filter 도구를 지원하는 시맨틱 파이프라인으로 변환합니다.

src/ai/catalog-semantic-filter.ts 파일로 이동합니다.

84~88번째 줄에서 prewarmSemanticFilterSession()을 검사합니다.

export async function prewarmSemanticFilterSession(): Promise<void>

1. warmSession이 이미 있는지 확인하고 있는 경우 일찍 반환합니다.
2. getPromptSession()를 사용하여 SEMANTIC_FILTER_SYSTEM_PROMPT로 프롬프트 API 세션을 사전 워밍하고 warmSession에 저장합니다. 사전 워밍이 실패하는 경우 검색 생성에서 정상적으로 대체할 수 있도록 try/catch 블록으로 래핑

93~134행에서 inferSearchFacets()을 검사합니다.

async function inferSearchFacets(
  searchTerm: string,
  cachedJourney: JourneyProfile | null
): Promise<{ parsed: SemanticFilterResponse; cacheHit: boolean }>

3. 사용 가능한 경우 warmSession에서 사전 워밍된 세션을 요청하고 (warmSession을 null로 재설정) getPromptSession(SEMANTIC_FILTER_SYSTEM_PROMPT)를 사용하여 새 세션을 만듭니다.
4. semanticFilterSchema을 responseConstraint로 사용하여 promptText으로 모델에 프롬프트를 제공합니다.
5. 반환된 JSON을 파싱하고, 파싱된 결과를 cacheKey를 사용하여 영구 캐시에 저장하고, finally 블록에서 세션을 소멸시킵니다.

139~270행에서 applyFacetsViaWebMCP()을 검사합니다.

async function applyFacetsViaWebMCP(
  searchTerm: string,
  parsed: SemanticFilterResponse
): Promise<{ appliedFilters: SemanticFilterResult['appliedFilters']; toolsExecuted: string[] }>

6. await document.modelContext.getTools()을 사용하여 document.modelContext에 등록된 도구를 검색합니다.
7. await executeFacet('reset_filters', {})를 호출하여 필터를 재설정하여 처음부터 시작합니다.
8. await Promise.all(facetTasks)을 사용하여 활성 패싯을 동시에 적용합니다.

272~316행에서 interpretAndApplySemanticFilter()을 검사합니다.

export async function interpretAndApplySemanticFilter(
  searchTerm: string
): Promise<SemanticFilterResult>

9. inferSearchFacets(searchTerm, cachedJourney)를 호출하여 검색 패싯을 추론합니다.
10. applyFacetsViaWebMCP(searchTerm, parsed)를 사용하여 추론된 패싯을 카탈로그에 적용합니다.

인페이지 에이전트 확인

1. http://localhost:5173/catalog로 이동합니다.
2. 상단의 검색창에 "lightweight 3 season tent for wet hikes"를 입력합니다.
3. Prompt API가 요청을 파싱하고 activity_filter (하이킹), category_filter (텐트), condition_filter (젖음)를 호출하여 수동으로 체크박스를 클릭하지 않고도 카탈로그를 일치하는 장비로 즉시 좁히는 것을 확인하세요.

6. 학습한 내용

축하합니다 이커머스 애플리케이션을 온디바이스 AI와 표준 웹 플랫폼 API로 완전히 구동되는 지능형 에이전트 중심 환경으로 변환했습니다.

빌드한 항목:

• 온디바이스 프롬프트 API: LanguageModel로 사용자 탐색 타임라인을 합성하여 실시간 JourneyProfile 컨텍스트를 생성하고 구조화된 JSON 스키마 (responseConstraint)를 사용하여 rankComplementaryGear 시너지 엔진을 빌드했습니다.
• WebMCP 구성요소 도구: document.modelContext를 통해 UI 구성요소 (get_recommendations, get_current_product, view_cart, manage_cart) 전반에 등록된 모듈식 캡슐화 도구
• 에이전트 전달 아키텍처: Chrome WebMCP Inspector 확장 프로그램을 사용하여 도구 실행을 테스트하고 확인했습니다.
• 사이트 내 페이지 상담사: 브라우저에서 직접 클라이언트 측 도구를 오케스트레이션하여 사이트 헤더 검색창에서 다면적인 자연어 카탈로그 검색을 지원합니다.
• 특화된 온디바이스 AI 모델: Translator를 사용한 동적 온디바이스 번역을 살펴봤습니다.

핵심 내용:

1. 지연 시간 제로 및 높은 개인 정보 보호: Gemini Nano와 같은 온디바이스 모델은 클라우드 API 키, 네트워크 지연 시간, 데이터 무단 반출 문제를 없애줍니다.
2. 구조화된 출력은 필수입니다: responseConstraint와 함께 JSON 스키마를 사용하면 창의적인 텍스트 생성이 안정적이고 유형이 안전한 애플리케이션 로직으로 바뀝니다.
3. WebMCP는 AI 에이전트를 위해 웹을 준비합니다: DOM에 직접 도구를 등록하면 내부 지원 기능과 외부 자율 브라우저 에이전트 모두 검증된 결정론적 작업을 수행할 수 있습니다.
4. 모델이 제안만 하고 실행하지 않도록 설정: 모델을 등록된 도구의 enum로 제한하고 결과를 직접 디스패치하면 에이전트 동작을 감사할 수 있으며 모델이 작업을 발명하는 것을 방지할 수 있습니다.