Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

새 모델로 마이그레이션

이 문서에서는 기존 CX Agent Studio 에이전트 애플리케이션을 다른 기반 모델로 마이그레이션하고, 에이전트 품질을 검증하고, 실시간 프로덕션 트래픽을 중단하지 않고 업데이트된 구성을 단계적으로 배포하는 방법을 설명합니다.

마이그레이션 워크플로 개요

전체 모델 마이그레이션은 다음 네 단계를 따릅니다.

변경사항 격리: 프로덕션 에이전트 애플리케이션의 변경 불가능한 버전을 만들거나 애플리케이션을 별도의 테스트 환경으로 내보내고 가져옵니다.
모델 설정 업데이트: 콘솔, 내보낸 구성 파일 또는 REST API를 사용하여 전역 모델을 변경하고, 하위 에이전트 및 도구 모델 재정의를 검토하고, 재시도 및 대체 설정을 확인합니다.
성능 평가 및 미세 조정: 시뮬레이터에서 대화를 테스트하고, AI로 문제 찾기를 사용하여 평가를 실행하고, AI Co-Builder: Arc를 사용하여 품질 측정항목이 목표 기준점을 충족할 때까지 안내를 조정합니다.
단계별 배포: 검증된 구성을 버전으로 저장하고 배포 채널에서 트래픽 분할을 사용하여 결과를 모니터링하면서 실시간 트래픽을 점진적으로 전환합니다.

1단계: 변경사항 격리

모델 설정을 변경하기 전에 업데이트 및 테스트가 실제 고객 대화에 영향을 미치지 않도록 작업을 격리합니다. 동일한 에이전트 애플리케이션 내에서 버전을 사용하거나 애플리케이션을 별도의 샌드박스 환경으로 내보내 변경사항을 격리할 수 있습니다.

동일한 에이전트 애플리케이션에서 버전 사용

배포 채널이 변경 불가능한 특정 버전을 가리키는 경우, 버전을 만들고 배포 채널에 할당할 때까지 초안 에이전트 애플리케이션에 대한 수정사항이 실시간 트래픽에 영향을 미치지 않습니다.

현재 구성의 기준 스냅샷을 저장하려면 다음 단계를 따르세요.

CX Agent Studio 콘솔을 열고 에이전트 애플리케이션을 선택합니다.
Agent Builder에서 버전 창을 엽니다.
+ 버전 만들기를 클릭합니다.
구체적인 이름(예: pre-model-migration-baseline)과 설명(선택사항)을 입력한 후 만들기를 클릭합니다.
배포 탭을 열고 활성 배포 채널이 변경 가능한 초안이 아닌 변경 불가능한 버전(버전 창의 Live 배지로 표시됨)을 가리키는지 확인합니다.

샌드박스 환경으로 내보내기 및 가져오기

별도의 프로젝트 또는 스테이징 애플리케이션에서 모델 변경사항을 테스트하려면 에이전트 애플리케이션을 내보내고 테스트 환경으로 가져옵니다.

CX Agent Studio 콘솔을 열고 프로젝트를 선택합니다.
에이전트 애플리케이션 목록에서 애플리케이션 메뉴를 열고 내보내기를 선택합니다.
샌드박스 환경에서 데이터 스토어나 서비스 엔드포인트와 같은 다른 외부 종속 항목을 사용하는 경우 다운로드한 보관 파일을 추출하고 environment.json 파일을 업데이트한 후 디렉터리를 ZIP 파일로 압축합니다. 자세한 내용은 환경 파일을 참조하세요.
샌드박스 프로젝트 또는 테스트 애플리케이션에서 애플리케이션 메뉴를 열고 가져오기를 선택한 후 보관 파일을 업로드합니다.
선택사항: 소스 애플리케이션에서 평가 테스트 사례를 내보내고 샌드박스 애플리케이션으로 가져와 회귀 테스트를 실행할 수 있습니다.

2단계: 모델 설정 업데이트

지원되는 모델 목록을 검토하여 에이전트의 형식(텍스트 또는 음성)과 일치하는 대상 Gemini 모델을 선택합니다. 콘솔, 내보낸 구성 파일 또는 REST API를 사용하여 모델 설정을 업데이트할 수 있습니다.

콘솔을 사용하여 모델 업데이트

콘솔에서 에이전트 애플리케이션을 마이그레이션할 때는 전역 애플리케이션 모델, 개별 에이전트 재정의, 데이터 스토어 도구 모델, 대체 설정을 확인하세요.

전역 모델 변경:
1. 에이전트 빌더에서 설정을 열어 에이전트 애플리케이션 설정을 확인합니다.
2. 기본 > 상호작용에서 전역 모델 필드의 대상 모델을 선택합니다. 이 모델은 재정의를 지정하지 않는 애플리케이션의 모든 에이전트에 대한 기본값으로 사용됩니다.
루트 및 하위 에이전트 모델 재정의 확인:
1. 에이전트 빌더에서 루트 에이전트의 제목 표시줄에 있는 메뉴를 연 다음 구성 수정을 선택하여 에이전트 설정을 확인합니다.
2. 모델 필드를 확인합니다. 에이전트가 전역 모델을 재정의하는 경우 대상 모델을 선택하거나 재정의를 지워 에이전트가 전역 모델을 상속하도록 합니다.
3. 에이전트 계층 구조의 모든 하위 에이전트에 대해 이 확인을 반복합니다.
데이터 스토어 도구 모델 확인:
1. 애플리케이션에서 데이터 스토어 도구를 사용하는 경우 도구 패널을 열고 각 데이터 스토어 도구를 선택합니다.
2. 고급 > 모달리티를 펼치고 텍스트 및 음성 구성 모두에 대해 Rewriter 모델 및 요약 모델 선택을 확인합니다.
재시도 및 대체 설정 검토:
1. 에이전트 애플리케이션의 설정을 열고 기본 > 동작 > 대체 동작으로 이동합니다.
2. 모델 생성 중 오류 처리를 위해 재시도, 에이전트 응답, 대체가 적절하게 구성되어 있는지 확인합니다.

내보낸 구성 파일을 사용하여 모델 업데이트

버전 제어 또는 CI/CD 파이프라인을 통해 에이전트 애플리케이션을 관리하는 경우 내보낸 보관 파일에서 모델 설정을 업데이트하고 패키지를 다시 가져올 수 있습니다.

내보낸 에이전트 애플리케이션 ZIP 파일의 압축을 풉니다.
agents/<var>AGENT_NAME</var>/ 아래의 각 에이전트 디렉터리에 대해 agents/<var>AGENT_NAME</var>/<var>AGENT_NAME</var>.yaml 파일을 열고 modelSettings.model 필드를 대상 모델 ID로 업데이트합니다.
```
displayName: "AGENT_NAME"
modelSettings:
  model: "MODEL_ID"
instruction: "agents/AGENT_NAME/instruction.txt"
```
다음을 바꿉니다.
- <var>AGENT_NAME</var>: 에이전트의 표시 이름입니다.
- <var>MODEL_ID</var>: 대상 모델의 식별자입니다(예: gemini-3.5-flash 또는 gemini-composite-v2).
루트 디렉터리를 ZIP 파일로 압축하고 업데이트된 파일을 CX Agent Studio로 가져옵니다.

REST API를 사용하여 모델 업데이트

CX Agent Studio REST API를 사용하여 에이전트 애플리케이션과 개별 에이전트에서 프로그래매틱 방식으로 ModelSettings를 업데이트할 수 있습니다.

API를 호출하기 전에 다음 값을 수집합니다.

<var>PROJECT_ID</var>: Google Cloud 프로젝트 ID입니다.
<var>LOCATION_ID</var>: 에이전트 애플리케이션의 리전(예: us 또는 eu)
<var>APP_ID</var>: 에이전트 애플리케이션의 리소스 ID입니다.
<var>AGENT_ID</var>: 특정 루트 에이전트 또는 하위 에이전트의 리소스 ID입니다.
<var>MODEL_ID</var>: 대상 모델 식별자입니다(예: gemini-3.5-flash).

에이전트 애플리케이션의 기본 전역 모델을 업데이트하려면 updateMask=modelSettings를 사용하여 projects.locations.apps.patch 메서드에 PATCH 요청을 보냅니다.

curl -X PATCH \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://ces.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/apps/APP_ID?updateMask=modelSettings" \
  -d '{
    "modelSettings": {
      "model": "MODEL_ID"
    }
  }'

개별 루트 에이전트 또는 하위 에이전트에서 모델 재정의를 업데이트하려면 updateMask=modelSettings를 사용하여 PATCH 요청을 projects.locations.apps.agents.patch 메서드에 전송합니다.

curl -X PATCH \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://ces.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/apps/APP_ID/agents/AGENT_ID?updateMask=modelSettings" \
  -d '{
    "modelSettings": {
      "model": "MODEL_ID"
    }
  }'

3단계: 에이전트 성능 평가 및 미세 조정

파운데이션 모델은 추론 스타일, 요청 사항 준수, 상세 출력, 도구 호출 동작이 다를 수 있습니다. 모델을 전환한 후에는 업데이트된 구성으로 실시간 고객 트래픽을 라우팅하기 전에 에이전트를 테스트하고 요청 사항을 미세 조정하세요.

시뮬레이터에서 대화형으로 테스트

에이전트 미리보기 시뮬레이터에서 초기 상태 검사를 실행합니다.

에이전트 빌더에서 시뮬레이터를 열고 새 대화 시작을 클릭합니다.
대표적인 텍스트 또는 오디오 상호작용을 테스트하고 에이전트가 안내를 따르고, 유효한 인수로 도구를 호출하고, 하위 에이전트 간에 예상대로 전환되는지 확인합니다.
각 차례의 trace 세부정보를 펼쳐 단계 지연 시간, 도구 입력 및 출력, 원시 JSON 대답을 검사합니다.
선택사항: 회귀 모음에 대화를 추가하려면 시뮬레이터 메뉴를 열고 골든으로 저장을 선택합니다.

AI로 평가 실행 및 문제 진단

평가를 사용하여 골든, 시나리오, 시뮬레이션 테스트 사례 전반의 성능을 측정하고 결과를 기준 버전과 비교합니다.

에이전트 빌더 상단에서 평가를 클릭합니다.
중요한 사용자 여정과 에이전트 변형을 다루는 테스트 사례를 선택한 다음 선택한 항목 실행을 클릭합니다.
실행 대화상자에서 AI로 문제 찾기를 선택하고 최적의 AI 분석을 위해 실행 횟수를 3회 이상으로 설정한 후 실행을 시작합니다. 자세한 내용은 AI를 사용하여 테스트 사례 개선을 참조하세요.
실행이 완료되면 도구 정확성, 시맨틱 일치, 사용자 목표 만족도, 목표 달성, 할루시네이션, 작업 완료를 포함한 평가 측정항목을 검토하고 실패한 대화 또는 완료되지 않은 목표를 검사합니다.
결과 페이지에서 Gemini에게 물어보기를 클릭하여 생성된 loss_report를 검토하고, 실패한 실행의 근본 원인을 요약하고, 추천 안내 또는 구성 수정사항을 확인합니다.

AI Co-Builder를 사용한 언덕 오르기 안내: Arc

평가 결과에 대상 모델에서 회귀 또는 동작 변경사항이 표시되면 AI Co-Builder: Arc 및 평가 도우미를 사용하여 프롬프트를 반복적으로 미세 조정합니다.

에이전트 빌더 상단에서 Arc를 클릭하여 AI Co-Builder를 엽니다.
컨텍스트 선택을 클릭하고 조정이 필요한 특정 에이전트 또는 요청 사항을 선택하거나 실패한 스크립트 및 손실 보고서를 첨부합니다.
다른 테스트 사례에서 동작을 유지하면서 관찰된 실패를 해결하도록 안내 또는 도구 설명을 업데이트하라는 프롬프트를 Arc에 입력합니다. 요청 사항 재구성 기능을 사용하여 요청 사항을 구조화된 형식으로 구성할 수도 있습니다.
수정사항을 적용한 후 평가 도구 모음을 다시 실행하고 모든 테스트 사례가 통과 기준을 충족할 때까지 반복합니다. 추가 안내는 평가 및 힐클라이밍 권장사항을 참고하세요.

4단계: 트래픽 분할을 사용하여 단계별로 배포

업데이트된 에이전트가 평가를 통과하면 버전 및 배포 트래픽 분할을 사용하여 점진적으로 출시합니다.

마이그레이션된 에이전트의 버전 만들기

검증된 구성의 변경할 수 없는 스냅샷을 저장합니다.

별도의 샌드박스 애플리케이션에서 변경사항을 테스트한 경우 검증된 애플리케이션 패키지를 내보내고 프로덕션 애플리케이션으로 가져옵니다.
프로덕션 애플리케이션에서 버전 창을 열고 + 버전 만들기를 클릭합니다.
대상 모델을 식별하는 이름과 설명(예: v2-gemini-3-5-flash)을 입력한 후 만들기를 클릭합니다.

실시간 트래픽을 점진적으로 전환

트래픽 분할을 사용하여 실시간 대화의 일부를 이전된 버전으로 라우팅한 후 트래픽의 100% 로 승격합니다.

에이전트 빌더 상단에서 배포 탭을 클릭하고 배포 채널을 선택합니다.
에이전트 버전에서 버전 추가를 클릭하고 기준 프로덕션 버전과 마이그레이션된 후보 버전을 모두 포함합니다.
후보 버전에 작은 초기 트래픽 비율을 할당한 다음(예: 기준 버전의 경우 90%, 후보 버전의 경우 10%, 총 100%) 채널 구성을 저장합니다. REST API를 사용하여 프로그래매틱 방식으로 experimentConfig.versionRelease.trafficAllocations를 구성할 수도 있습니다.
여러 버전의 실시간 성능 모니터링:
- 모니터링 대시보드에서 세션 볼륨, 지연 시간, 에스컬레이션 비율을 확인합니다.
- 대화 기록에서 실시간 스크립트를 검사합니다.
- BigQuery에서 app_version_id별로 내보낸 상호작용 로그를 쿼리하여 버전 간 도구 실행 및 결과 비율을 비교합니다. SQL 쿼리 예시는 BigQuery에서 버전 성능 분석을 참조하세요.
안정성과 품질을 확인하면서 실시간 트래픽의 100% 를 처리할 때까지 마이그레이션된 버전의 트래픽 비율을 단계적으로 늘립니다. 출시 중에 예기치 않은 문제가 감지되면 트래픽의 100% 를 기준 버전으로 다시 라우팅하거나 버전 창에서 이전 버전을 복원합니다.