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 콘솔에 로그인합니다.
  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 로직으로 이동합니다.
  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 로직 > 프롬프트 템플릿 탭으로 이동합니다.
  2. 템플릿 만들기를 클릭하고 빈 템플릿을 선택합니다.
  3. 템플릿 이름을 Product Agent로, ID를 product-agent로 설정합니다.
  4. 모델을 gemini-3.1-flash-lite (또는 사용 가능한 최신 버전)로 설정합니다.
  5. 이 Codelab에 제공된 시작 코드에서 product-agent.prompt의 콘텐츠를 복사합니다 (루트 디렉터리에서 이 파일을 찾음). 그런 다음 이 콘텐츠를 Firebase Console의 서버 프롬프트 템플릿에 있는 프롬프트 및 (선택사항) 시스템 지침 필드에 붙여넣습니다. 이 콘텐츠는 모델이 '러기드 오퍼레이터'로 행동하고 제품 카탈로그를 참조하는 방법을 안전하게 안내합니다.
  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. 키 만들기를 클릭하고 다음 필드를 작성합니다.
    • Display name(표시 이름): Codelab Key
    • 애플리케이션 유형: 웹
    • 도메인 목록: 로컬 Vite 서버가 요청을 할 수 있도록 localhost 및 127.0.0.1를 추가합니다.
  3. 키 만들기를 클릭하여 키를 등록합니다.
  4. Fraud Defense 키 세부정보 페이지 상단에서 사이트 키 ID를 클립보드에 복사합니다.
  5. Firebase Console에서 보안 > 앱 체크로 이동합니다.
  6. 앱 탭을 클릭하고 웹 앱 (Rugged Web)을 펼친 다음 reCAPTCHA Enterprise 제공자를 클릭합니다.
  7. reCAPTCHA Enterprise 사이트 키 필드에 사기 방지 키 세부정보 페이지의 사이트 키 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 결제 계정에 비용이 청구되지 않도록 하려면 이 Codelab에서 만든 리소스를 삭제하면 됩니다.

  1. Firebase Console에서 설정 > 일반 탭으로 이동합니다.
  2. 보고 있는 프로젝트가 이 Codelab에서 사용한 프로젝트인지 확인합니다. Codelab의 프로젝트가 아닌 경우 왼쪽 상단의 프로젝트 선택기 드롭다운을 사용하여 프로젝트를 변경할 수 있습니다.
  3. 페이지 하단으로 이동한 후 프로젝트 삭제를 클릭합니다.
  4. 화면에 표시된 안내에 따라 삭제를 확인합니다.

10. 수고하셨습니다

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

달성한 내용:

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

다음 단계