Firebase AI Logic을 사용하여 AI 기반 고객 지원 에이전트 빌드

1. 소개

이 Codelab에서는 Rugged Terrain Guide 라는 아웃도어 장비 전자상거래 쇼핑몰에 스마트 고객 지원 채팅 위젯을 추가합니다. Firebase AI Logic을 사용하여 이 에이전트를 빌드하고 AI의 페르소나, 엄격한 보상 예산 규칙을 처리하고 제품 카탈로그를 컨텍스트로 동적으로 사용하는 서버 측 프롬프트 템플릿 (product-agent)을 구성하는 방법을 알아봅니다.

수행할 작업:

  • 이 Codelab의 웹 앱용 시작 코드를 가져옵니다.
  • Firebase 프로젝트를 설정합니다.
  • 웹 앱에서 Firebase 서비스 (예: Firebase AI Logic)를 설정하고 초기화합니다.
  • Firebase Console에서 서버 측 프롬프트 템플릿을 구성합니다.
  • React와 유사한 TypeScript 프런트엔드에서 생성형 AI 서비스 호출을 통해 템플릿에 액세스합니다.

필요한 항목:

  • 웹브라우저(예: Chrome)
  • TypeScript 및 Node.js에 대한 기본 지식
  • 원하는 IDE 또는 텍스트 편집기 Antigravity를 사용하면 좋습니다.

2. 시작 코드 가져오기

  1. 터미널에서 시작 저장소를 클론합니다.
    git clone https://github.com/GoogleCloudPlatform/devrel-demos.git
  2. 코드 디렉터리로 이동하고 종속 항목을 설치합니다.
    cd devrel-demos/codelabs/firebase-server-prompt-templates-codelab
npm install

3. Firebase 프로젝트 설정

Firebase 프로젝트 만들기

  1. Google 계정을 사용하여 Firebase Console에 로그인합니다.
  2. 버튼을 클릭하여 새 프로젝트를 만든 다음 프로젝트 이름 (예: rugged-terrain-ai)을 입력합니다.
  3. 계속 을 클릭합니다.
  4. 메시지가 표시되면 Firebase 약관을 검토하고 이에 동의한 다음 계속을 클릭합니다.
  5. (선택사항) Firebase Console에서 AI 지원('Firebase의 Gemini'라고 함)을 사용 설정합니다.
  6. 이 Codelab에서는 Google 애널리틱스가 필요하지 않으므로 Google 애널리틱스 옵션을 사용 중지 합니다.
  7. 프로젝트 만들기 를 클릭하고 프로젝트가 프로비저닝될 때까지 기다린 후 계속 을 클릭합니다.

Firebase 요금제 업그레이드

이 Codelab에서 Firebase 서비스를 사용하려면 Firebase 프로젝트가 사용한 만큼만 지불하는 (Blaze) 요금제를 사용하고 있어야 합니다. 즉, 프로젝트가 Cloud Billing 계정에 연결되어 있어야 합니다.

  • Cloud Billing 계정에는 신용카드와 같은 결제 수단이 필요합니다.
  • Firebase와 Google Cloud를 처음 사용하는 경우 $300 크레딧과 무료 체험판 Cloud Billing 계정을 받을 자격이 되는지 확인하세요.
  • 이벤트의 일환으로 이 Codelab을 진행하는 경우 주최자에게 사용 가능한 클라우드 크레딧이 있는지 문의하세요.

프로젝트를 Blaze 요금제로 업그레이드하려면 다음 단계를 따르세요.

  1. Firebase Console에서 요금제를 업그레이드할 를 선택합니다.
  2. Blaze 요금제를 선택합니다. 화면에 표시된 안내에 따라 Cloud Billing 계정을 프로젝트에 연결합니다.
    이 업그레이드의 일환으로 Cloud Billing 계정을 만들어야 하는 경우 업그레이드를 완료하기 위해 Firebase Console의 업그레이드 흐름으로 돌아가야 할 수 있습니다.

4. Firebase 서비스 설정 및 앱 연결

이 Codelab에서는 Firebase 프로젝트에서 Firebase용 Cloud Storage와 Firebase AI Logic을 설정해야 합니다. 또한 앱의 소스 코드를 Firebase 프로젝트에 연결해야 합니다.

Firebase용 Cloud Storage 설정

이 Codelab에서는 Firebase용 Cloud Storage를 사용하여 제품 설명을 저장합니다.

  1. Firebase Console에서 데이터베이스 및 스토리지 > 스토리지로 이동합니다.
  2. 시작하기 를 클릭합니다.
  3. 기본 스토리지 버킷의 위치를 선택합니다.
    US-WEST1, US-CENTRAL1, US-EAST1의 버킷은 Google Cloud Storage의 '상시 무료' 등급을 활용할 수 있습니다. 다른 모든 위치의 버킷은 Google Cloud Storage 가격 책정과 사용량을 따릅니다.
  4. 프로덕션 모드 를 클릭합니다. 바로 아래 단계에서 이 Codelab에 맞게 이 보안 규칙을 업데이트합니다.
  5. 만들기 를 클릭합니다.
  6. 보안 규칙을 업데이트합니다.
    1. 버킷이 프로비저닝되면 규칙 탭으로 이동합니다.
    2. 다음 규칙을 복사한 후 붙여넣습니다.
      rules_version = '2';
service firebase.storage {
  match /b/{bucket}/o {
    match /products.txt {
      allow read;
    }
  }
}
    3. 게시 를 클릭합니다.
  7. 시작 코드에서 제품 설명을 업로드합니다.
    1. 스토리지 버킷의 파일 탭을 클릭합니다.
    2. 파일 업로드를 클릭한 다음 시작 코드에서 products.txt 파일을 업로드합니다. 이 파일은 src/data/products.txt에서 찾을 수 있습니다.

Firebase AI Logic 구성

Firebase AI Logic은 이 Codelab에서 사용할 기본 Firebase 서비스입니다.

  1. Firebase Console에서 AI 서비스 > AI Logic으로 이동합니다.
  2. 시작하기 를 클릭합니다.
  3. Vertex AI Gemini API 카드에서 이 API 시작하기 를 클릭하고 화면에 표시된 안내를 따릅니다. 이 흐름을 통해 Vertex AI Gemini API와 함께 Firebase AI Logic을 사용하는 데 필요한 API를 사용 설정할 수 있습니다.
  4. (선택사항) AI 모니터링 사용 설정 을 선택하여 다양한 앱 수준 측정항목과 사용량을 관찰하고 Firebase AI Logic을 통해 요청을 포괄적으로 파악할 수 있습니다.

코드를 Firebase 프로젝트에 연결

Firebase AI Logic을 설정하는 과정에서 Firebase 웹 앱을 만들고 소스 코드에 구성을 추가하라는 메시지가 표시됩니다.

  1. Firebase AI Logic 설정 흐름에서 메시지가 표시되면 웹 () 아이콘을 클릭하여 새 웹 앱을 등록합니다.
  2. 앱 이름을 지정합니다 (예: Rugged Web).
  3. 설정 안내에서 firebaseConfig 객체를 복사합니다.

그런 다음 시작 코드를 업데이트합니다.

  1. 코드 편집기에서 src/firebase.ts를 엽니다.
  2. 기존 firebaseConfig를 Firebase Console에서 복사한 것으로 바꿉니다.

파일은 다음과 같이 표시됩니다.

import { getAI, getTemplateGenerativeModel, VertexAIBackend } from "firebase/ai";
import { initializeApp } from "firebase/app";

// Your web app's Firebase configuration
const firebaseConfig = {
    apiKey: "YOUR_API_KEY",
    authDomain: "YOUR_PROJECT_ID.firebaseapp.com",
    projectId: "YOUR_PROJECT_ID",
    storageBucket: "YOUR_PROJECT_ID.firebasestorage.app",
    messagingSenderId: "YOUR_MESSAGING_SENDER_ID",
    appId: "YOUR_APP_ID"
};

// Initialize Firebase
export const app = initializeApp(firebaseConfig);

const ai = getAI(app, { backend: new VertexAIBackend() });

5. 서버 측 프롬프트 템플릿 만들기

클라이언트 앱에서 복잡한 AI 프롬프트를 하드 코딩하는 대신 Dotprompt 구문 을 사용하여 서버에서 안내를 안전하게 관리합니다.

이렇게 하면 최종 사용자가 비밀 '보상 예산' 규칙을 볼 수 없습니다.

  1. Firebase Console에서 Vertex AI 또는 프롬프트 관리 섹션으로 이동합니다.
  2. 새 프롬프트 템플릿을 만들고 이름을 product-agent로 지정합니다.
  3. 모델을 gemini-2.5-flash로 설정합니다.
  4. 입력 스키마를 다음과 같이 정확하게 정의합니다.
    input:
  schema:
    query:
      type: string
      description: the customers ask of the robot
    productId?:
      type: string
      description: the product the customer is looking at right now
    history?:
      type: array
      description: list of previous history between the user and system
      items:
        type: object
        required: [role, contents]
        properties:
          role:
            type: string
          contents:
            type: string
  5. 루트 디렉터리의 agent-product.prompt 콘텐츠를 프롬프트 및 선택적 시스템 안내 필드에 복사합니다. 이렇게 하면 모델에 'Rugged Operator'로 동작하고 제품 카탈로그를 삽입하는 방법을 안전하게 안내합니다.
  6. Firebase Console에서 product-agent 템플릿을 저장하고 게시합니다.

6. AI 모델 호출

이제 템플릿이 서버에서 안전하게 정의되었으므로 앱의 프런트엔드에서 호출하기만 하면 됩니다.

  1. 코드 편집기에서 src/firebase.ts로 돌아갑니다.
  2. 초기화 아래에서 getTemplateGenerativeModel을 사용하여 템플릿에 연결합니다.
    const model = getTemplateGenerativeModel(ai);

export const callCustomerSupportModel = async (query: string, productId?: string, history?: { role: string, contents: string }[]) => {
    // Generate content using the published 'product-agent' template
    const result = await model.generateContent('product-agent', {
        query,
        productId,
        history,
    });
    return result.response.text();
}

7. Firebase 앱 체크로 에이전트 보호

AI 모델은 강력하지만 공개 엔드포인트가 보호되지 않은 상태로 남아 있으면 악용될 수도 있습니다. Firebase 앱 체크를 항상 사용하여 실제 웹 앱만 Vertex AI 생성형 모델을 호출하고 봇과 승인되지 않은 클라이언트를 차단할 수 있도록 해야 합니다.

  1. Firebase Console에서 빌드 > 앱 체크 로 이동합니다.
  2. 앱 탭을 클릭하고 웹 앱 (Rugged Web)을 펼친 다음 reCAPTCHA Enterprise 제공자를 클릭합니다.
  3. 새 reCAPTCHA Enterprise 키 만들기 를 선택하고 프롬프트를 작성합니다.
    • 이름: Codelab Key
    • 도메인: 로컬 Vite 서버에서 요청을 할 수 있도록 localhost 및 127.0.0.1을 추가합니다.
  4. 저장 을 클릭하여 앱을 등록합니다.
  5. 등록되면 Firebase Console에 사이트 키 가 표시됩니다. 이 문자열을 복사합니다.
  6. 코드 편집기에서 src/firebase.ts를 다시 엽니다.
  7. 상단에 다음 가져오기를 추가합니다.
    import { initializeAppCheck, ReCaptchaEnterpriseProvider } from "firebase/app-check";
  8. initializeApp(firebaseConfig) 호출 바로 뒤에 앱 체크 초기화를 추가하고 복사한 사이트 키를 붙여넣습니다.
    // Initialize App Check
const appCheck = initializeAppCheck(app, {
  provider: new ReCaptchaEnterpriseProvider('YOUR_RECAPTCHA_ENTERPRISE_SITE_KEY'),
  useLimitedUseAppCheckTokens: true
});
  9. 이러한 토큰을 사용하도록 getAI() 함수 호출을 업데이트합니다. 다음과 같이 변경합니다.
    const ai = getAI(app, { backend: new VertexAIBackend(), useLimitedUseAppCheckTokens: true });
    useLimitedUseAppCheckTokens 값을 true로 설정하면 백엔드에서 받을 수 있는 악용을 제한하는 데 도움이 되는 단기 토큰이 적용됩니다.

8. 앱 실행

Firebase 구성이 완료되고 지원 채팅 위젯이 연결되었으므로 이제 앱을 실행할 수 있습니다.

  1. 터미널에서 Vite 개발 서버를 실행합니다.
    npm run dev
  2. 제공된 로컬 URL (일반적으로 http://localhost:5173/)을 엽니다.
  3. 오른쪽 하단에 있는 전술 지원 플로팅 작업 버튼 (FAB)을 클릭합니다.
  4. 제품에 관한 질문을 해 보세요(예:)
    • '방수 쉘을 찾고 있습니다.'
    • '영하의 비니에 결함이 있습니다. 어떻게 해야 하나요?'
    • AI의 '보상 예산' 로직을 트리거하기 위해 계속 밀어붙이세요.

9. (선택사항) Codelab에서 리소스 정리

Google Cloud Billing 계정에 요금이 청구되지 않도록 하려면 이 Codelab 중에 만든 리소스를 삭제하면 됩니다.

  1. Firebase Console로 이동합니다.
  2. rugged-terrain-ai 프로젝트를 선택합니다.
  3. 프로젝트 설정 (톱니바퀴 아이콘)으로 이동합니다.
  4. 하단으로 스크롤하여 프로젝트 삭제 를 클릭합니다.
  5. 화면에 표시된 안내에 따라 삭제를 확인합니다.

10. 수고하셨습니다

🎊 미션 완료! 템플릿 기반의 강력한 AI 고객 지원 에이전트를 통합했습니다.

완료한 작업:

  • 클라이언트 앱에서 Firebase 및 Vertex AI 백엔드를 초기화했습니다.
  • Handlebars 및 엄격한 입력 스키마를 사용하여 보안 서버 측 프롬프트 템플릿을 구성 하여 에이전트의 복잡한 동작을 정의했습니다.
  • 내부 프롬프트 로직을 클라이언트에 노출하지 않고 채팅 기록과 컨텍스트 제품 ID를 안전하게 전달하여 LLM을 동적으로 호출 했습니다.

다음 단계