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 계정에는 신용카드와 같은 결제 수단이 필요합니다.
  • 특별 프로모션 기간 또는 이벤트의 일부로 이 Codelab을 진행하는 경우 Google Cloud 크레딧을 사용할 수 있습니다.
  • Firebase와 Google Cloud를 처음 사용하는 경우 $300 크레딧과 무료 체험판 Cloud Billing 계정을 받을 자격이 되는지 확인하세요.

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

  1. Firebase Console에서 요금제를 업그레이드할 를 선택합니다.
  2. Blaze 요금제를 선택합니다. 화면에 표시된 안내에 따라 Cloud Billing 계정을 프로젝트에 연결합니다.
    • 이 Codelab에 Google Cloud 크레딧을 사용하는 경우 결제 계정의 이름은 Google Cloud Platform Trial Billing Account 또는 My Billing Account일 수 있습니다.
    • 이 업그레이드의 일부로 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. Agent Platform Gemini API 카드에서 이 API 시작하기 를 클릭하고 화면에 표시된 안내를 따릅니다. 이 흐름을 통해 Agent Platform 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, AgentPlatformBackend } 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 AgentPlatformBackend() });

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

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

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

  1. Firebase Console에서 AI 서비스 > AI Logic > 프롬프트 템플릿 탭으로 이동합니다.
  2. 템플릿 만들기 를 클릭하고 빈 템플릿 을 선택합니다.
  3. 템플릿 이름을 Product Agent로, ID를 product-agent로 설정합니다.
  4. 모델을 gemini-3.1-flash-lite (또는 사용 가능한 최신 버전)로 설정합니다.
  5. 이 Codelab에 제공된 시작 코드에서 product-agent.prompt의 콘텐츠를 복사합니다 (루트 디렉터리에서 이 파일 찾기). 그런 다음 이 콘텐츠를 Firebase Console의 서버 프롬프트 템플릿에 있는 프롬프트 및 (선택사항) 시스템 안내 필드에 붙여넣습니다. 이 콘텐츠는 모델이 'Rugged Operator'로 동작하고 제품 카탈로그를 참조하는 방법을 안전하게 안내합니다.
  6. 테스트 입력 필드에서 입력 스키마를 다음과 같이 정확하게 정의합니다.
    {
  "type": "object",
  "required": [
    "query"
  ],
  "properties": {
    "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"
          }
        }
      }
    }
  }
}
  7. 템플릿 저장 을 클릭하여 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 앱 체크를 항상 사용하여 실제 웹 앱만 Gemini API에 성공적으로 요청할 수 있도록 하고 봇과 승인되지 않은 클라이언트를 차단해야 합니다.

  1. Google Cloud 콘솔에서 보안 > Fraud Defense로 이동합니다.
  2. 키 만들기 를 클릭하고 필드를 작성합니다.
    • 표시 이름: Codelab Key
    • 애플리케이션 유형: 웹
    • 도메인 목록: 로컬 Vite 서버가 요청을 할 수 있도록 localhost 및 127.0.0.1을 추가합니다.
  3. 키 만들기 를 클릭하여 키를 등록합니다.
  4. Fraud Defense 키 세부정보 페이지 상단에서 사이트 키 ID를 클립보드에 복사합니다.
  5. Firebase Console에서 보안 > 앱 체크 로 이동합니다.
  6. 앱 탭을 클릭하고 웹 앱 (Rugged Web)을 펼친 다음 reCAPTCHA Enterprise 제공자를 클릭합니다.
  7. reCAPTCHA Enterprise 사이트 키 필드에 Fraud Defense 키 세부정보 페이지의 사이트 키 ID를 붙여넣고 저장 을 클릭합니다.
  8. 코드 편집기에서 src/firebase.ts를 다시 엽니다.
  9. 상단에 다음 가져오기를 추가합니다.
    import { initializeAppCheck, ReCaptchaEnterpriseProvider } from "firebase/app-check";
  10. initializeApp(firebaseConfig) 호출 바로 뒤에 앱 체크 초기화를 추가하고 복사한 사이트 키 ID를 붙여넣습니다.
    // Initialize App Check
const appCheck = initializeAppCheck(app, {
  provider: new ReCaptchaEnterpriseProvider('YOUR_RECAPTCHA_ENTERPRISE_SITE_KEY'),
  isTokenAutoRefreshEnabled: true
});
  11. 이러한 토큰을 사용하도록 getAI() 함수 호출을 업데이트합니다. 다음과 같이 변경합니다.
    const ai = getAI(app, { backend: new AgentPlatformBackend(), 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. 보고 있는 프로젝트가 이 Codelab에 사용한 프로젝트인지 확인합니다. Codelab의 프로젝트가 아닌 경우 왼쪽 상단의 프로젝트 선택 도구 드롭다운을 사용하여 프로젝트를 변경할 수 있습니다.
  3. 페이지 하단으로 이동한 다음 프로젝트 삭제 를 클릭합니다.
  4. 화면에 표시된 안내에 따라 삭제를 확인합니다.

10. 수고하셨습니다

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

완료한 작업:

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

다음 단계