Vertex AI Extensions 종료 대응: Agent Platform 마이그레이션 체크리스트

요약: Google Cloud는 Vertex AI Extensions가 deprecated 되었고 2026년 11월 26일 이후 종료된다고 안내했습니다. 기존 Code Interpreter, Google Search, Custom Extension 기반 워크플로우는 Agent Platform, Grounding with Google Search, Function Calling으로 옮겨야 합니다. 이 글은 마이그레이션을 실제 작업 단위로 쪼갠 체크리스트입니다.

핵심 키워드: Vertex AI Extensions 종료, Agent Platform 마이그레이션, Gemini API CodeExecution, Grounding with Google Search, Function Calling.

문제: Extensions는 그냥 이름만 바뀌는 것이 아니다

Vertex AI Extensions를 쓰던 팀은 “나중에 endpoint만 바꾸면 되겠지”라고 생각하기 쉽습니다. 하지만 Google의 마이그레이션 문서를 보면 단순한 이름 변경이 아닙니다. 기존 확장 기능의 종류에 따라 이동 경로가 다릅니다.

Google은 세 가지 핵심 카테고리를 제시합니다.

Code Interpreter extension: Agent Platform Code Execution Sandbox 또는 Gemini API CodeExecution tool
Google Search extension: Grounding with Google Search
Custom extensions: Function Calling

즉 하나의 공통 Extension 인터페이스에서 각각 다른 실행 모델로 분리됩니다. 코드 실행은 샌드박스 리소스와 상태 관리가 중요해지고, 검색은 grounding 설정이 중요해지며, custom API는 함수 선언과 인증 처리가 중요해집니다.

마감일은 2026년 11월 26일 이후 종료입니다. 아직 시간이 있어 보이지만, 운영 서비스라면 늦지 않습니다. 특히 AI 워크플로우는 테스트가 어렵고, 결과 품질 회귀를 숫자로 잡기 힘듭니다. 기능별로 빨리 분리해서 비교 테스트를 시작해야 합니다.

1단계: 현재 Extension 사용처를 모두 찾기

먼저 해야 할 일은 코드 검색입니다. 레포에서 다음 키워드를 찾습니다.

vertexai.preview.extensions
Extension.from_hub
Extension.create
code_interpreter
google_search
operation_id
operation_params

검색 결과를 단순 파일 목록으로 끝내면 안 됩니다. 각 사용처를 워크플로우 기준으로 정리해야 합니다. 예를 들어 “매출 CSV 분석”, “고객 문의 검색 답변”, “주문 상태 API 호출”처럼 사용자 가치 기준으로 묶습니다.

정리 표에는 다음 열을 넣습니다.

워크플로우 이름
Extension 종류
입력 데이터 종류
출력 형식
인증 필요 여부
운영 중요도
실패 시 영향
현재 테스트 존재 여부

이 표가 없으면 마이그레이션 우선순위를 정할 수 없습니다.

2단계: Code Interpreter는 실행 모델을 먼저 고른다

Google은 Code Interpreter extension의 이동 경로로 Agent Platform Code Execution Sandbox를 권장하고, 대안으로 Gemini API의 code_execution tool을 제시합니다. 둘은 사용 목적이 다릅니다.

Agent Platform Code Execution Sandbox는 안전하고 격리된 상태ful 샌드박스가 필요한 경우에 맞습니다. 데이터 분석, 금융 계산, 여러 단계의 코드 실행, 파일 처리처럼 실행 상태가 중요하면 이쪽을 봐야 합니다.

반면 Gemini API CodeExecution tool은 모델이 생성 중에 간단히 코드를 쓰고 실행하는 패턴에 가깝습니다. 간단한 계산, 짧은 변환, 모델 답변 보조에는 편합니다. 하지만 운영 워크플로우에서 실행 환경, 파일, 권한, 재현성이 중요하다면 샌드박스 쪽이 안전합니다.

판단 기준은 다음과 같습니다.

파일 업로드와 결과 파일이 필요한가?
여러 셀 또는 여러 단계 실행이 필요한가?
실행 로그를 감사해야 하는가?
외부 패키지 설치가 필요한가?
사용자가 생성한 코드를 실행하는가?

위 질문에 “예”가 많으면 Agent Platform Sandbox를 우선 검토합니다.

3단계: Google Search Extension은 grounding 품질을 비교한다

Google Search extension은 Grounding with Google Search로 이동합니다. 여기서 중요한 것은 API 호출 형태보다 답변 품질입니다. 검색 결과가 어떻게 인용되고, 최신 정보가 어떻게 반영되며, 모델이 모르는 내용을 얼마나 덜 지어내는지 봐야 합니다.

마이그레이션 테스트에서는 같은 질문 세트를 만들어야 합니다.

최신성 질문: “이번 달 변경된 정책은?”
사실 확인 질문: “이 제품의 공식 가격은?”
지역 질문: “한국에서 사용 가능한가?”
비교 질문: “A와 B의 차이는?”
인용 필수 질문: “근거 링크를 포함해 설명해줘”

이 질문을 기존 Extension 방식과 새 Grounding 방식에 모두 던지고, 답변을 비교합니다. 단순히 응답이 나오는지만 보면 안 됩니다. 링크 품질, 인용 위치, 오래된 정보 포함 여부, 모호할 때의 표현을 봐야 합니다.

4단계: Custom Extension은 Function Calling 계약을 새로 설계한다

Custom Extension을 OpenAPI spec으로 등록해 쓰던 팀은 Function Calling으로 옮겨야 합니다. 이때 가장 중요한 것은 함수 이름과 파라미터 계약입니다. 기존 API 스펙을 그대로 모델에게 노출하면 너무 넓을 수 있습니다.

Function Calling용 함수는 사람이 쓰는 API가 아니라 모델이 안전하게 호출할 수 있는 작업 단위여야 합니다. 예를 들어 기존 API가 /orders/{id}/refund를 지원하더라도 모델에게 바로 refund 함수를 열어주면 위험합니다. 먼저 get_order_status, calculate_refund_preview, create_refund_request처럼 읽기, 계산, 요청 생성으로 나눠야 합니다.

권장 원칙은 다음과 같습니다.

읽기 함수와 쓰기 함수를 분리한다.
쓰기 함수는 기본적으로 실행이 아니라 요청 생성으로 만든다.
파라미터 enum을 적극 사용한다.
금액, 계정, 권한 관련 함수는 서버에서 재검증한다.
모델이 보낸 설명을 신뢰하지 말고 원본 파라미터를 검증한다.

마이그레이션은 기능 이전이 아니라 권한 재설계 기회로 봐야 합니다.

5단계: 회귀 테스트는 “정답”보다 “허용 범위”를 본다

AI 워크플로우는 전통적인 단위 테스트처럼 항상 같은 문자열을 기대하기 어렵습니다. 대신 허용 범위를 정의해야 합니다.

예를 들어 검색 답변 테스트라면 다음을 봅니다.

공식 출처 링크가 1개 이상 포함되는가?
날짜가 현재 기준과 맞는가?
모르는 내용을 단정하지 않는가?
금지된 도메인을 인용하지 않는가?

코드 실행 테스트라면 다음을 봅니다.

실행 에러가 없는가?
숫자 결과가 허용 오차 안에 있는가?
출력 파일 형식이 맞는가?
stderr가 비어 있거나 허용된 경고만 있는가?

Function Calling 테스트라면 다음을 봅니다.

올바른 함수가 선택되는가?
필수 파라미터가 빠지지 않는가?
위험 함수 호출 전에 확인 단계를 거치는가?
서버 검증 실패 시 사용자에게 재입력을 요청하는가?

바로 적용할 마이그레이션 체크리스트

결론은 분명합니다. Vertex AI Extensions 종료는 단순 SDK 변경이 아닙니다. 코드 실행, 검색 grounding, custom API 호출을 각각 더 명확한 실행 모델로 분리하는 작업입니다. 지금 할 일은 “나중에 바꾸기”가 아니라 사용처 목록, 위험도, 비교 테스트를 먼저 만드는 것입니다.

근거: Google Cloud Vertex AI release notes, “Migrate from Vertex AI Extensions to Agent Platform” 문서.