Google ADK Python 2.14.0 업그레이드: Enum·스킬 실행·Firestore 롤백 점검

도구 인수·스크립트 실행·세션 저장·기능 제어의 업그레이드 점검을 표현한 생성형 이미지. 실제 ADK 화면이나 구현 구조도는 아니다.

에이전트 프레임워크를 올린 뒤 도구 함수는 정상 실행되는데 분기 결과가 바뀌거나, 장애가 나서 패키지를 내렸더니 대화를 읽지 못할 수 있다. Google ADK Python 2.14.0은 새 기능뿐 아니라 이런 입력 형식과 저장 형식의 호환성을 함께 확인해야 하는 업데이트다.

공식 릴리스는 GitHub 공개 표시가 11월 7일이며, 본문 변경 기록의 날짜는 2026년 11월 4일이다. 두 날짜를 구분해서 읽어야 한다. 이 글은 2026년 11월 9일 한국 시간 기준으로 릴리스와 연결된 공식 코드·테스트를 확인한 운영 점검 가이드다.

1. Enum 인수: 도구 함수와 승인 콜백의 계약이 다르다

FunctionTool의 Enum, Optional[Enum], list[Enum] 인수는 유효한 값에 대해 Enum 멤버로 변환된다. 일반 Enum을 문자열과 비교하거나 문자열 키 사전을 조회하던 코드는 결과가 달라질 수 있다. 외부 JSON을 만들 때는 필요한 값의 .value를 명시하고, 내부 분기는 Enum 멤버와 비교하는 편이 분명하다. Enum 변환 코드와 테스트

다음은 애플리케이션 경계에서 입력을 명시적으로 정규화하는 작은 예다. ADK의 변환 로직을 재구현한 코드는 아니다.

잘못된 값의 거부도 별도 문제다. 기본 인수 검증이 꺼진 경로에서는 알 수 없는 Enum 값이 경고와 함께 그대로 전달되는 테스트가 있다. 타입 표기만으로 입력 검증이 끝났다고 가정하지 말고, 유효하지 않은 값과 누락·None을 직접 시험한다. 위 예제는 알 수 없는 문자열에 ValueError를 발생시킨다.

callable require_confirmation은 별도로 확인한다. FUNCTION_TOOL_ARG_VALIDATION이 꺼져 있으면 원시 값으로, 켜져 있으면 변환된 멤버로 전달되는 경로가 유지된다. 도구 본문만 바꾸고 승인 조건의 문자열 비교를 일괄 변경하면 승인 판단이 달라질 수 있다. 승인 콜백 후속 수정과 테스트

2. 스킬 실행: 자유형 command를 넘기던 호출을 찾아야 한다

environment를 사용하는 RunSkillScriptTool은 자유형 셸 command 대신 args, short_options, positional_args 형태의 인수를 받는다. 실행 기준 디렉터리도 환경의 작업 디렉터리에서 스킬 디렉터리로 바뀐다. 기존 command 호출은 INVALID_ARGUMENTS, 지원하지 않는 스크립트 형식은 UNSUPPORTED_SCRIPT_TYPE으로 끝난다. 지원 확장자는 .py, .sh, .bash다. 공식 변경 코드·문서

점검 대상은 Python 호출부에만 있지 않다.

시스템 프롬프트와 SKILL.md의 호출 예시에서 command를 검색한다.

저장된 평가 데이터와 도구 호출 재생 자료가 새 인자 구조를 쓰는지 확인한다.

상대 경로로 읽는 설정·입력 파일이 스킬 디렉터리 기준에서도 맞는지 확인한다.

스킬 스크립트와 의존 파일을 검토하고 실행 백엔드의 파일·네트워크 권한을 제한한다.

이 수정은 모델이 검증된 스킬을 벗어난 임의 셸 명령을 직접 넘기는 경로를 줄인다. 셸 실행 자체가 사라진 것은 아니며, 스크립트는 여전히 선택한 백엔드의 권한으로 실행된다. 로컬 실행을 자동으로 안전한 샌드박스라고 볼 수 없다.

3. Firestore: 패키지 다운그레이드만으로 되돌릴 수 없다

FirestoreSessionService는 새 이벤트 payload를 JSON 문자열로 기록하고, app·user state의 중첩 배열은 별도 맵 형태로 감싼다. 2.14.0의 읽기 코드는 기존 이벤트 딕셔너리와 새 문자열을 모두 처리한다. 따라서 기존 세션을 읽고 이어 쓰는 방향은 지원한다. 반대로 2.14.0이 기록한 새 형식은 2.13.0 이하가 읽지 못한다. 직렬화 변경과 읽기 분기

배포 계획에 다음 세 검사를 넣는 편이 좋다.

운영 데이터와 분리한 복제본에서 기존 세션을 새 버전으로 읽고 이벤트를 추가한다.

새 기록이 포함된 복제본을 이전 버전으로 읽는 검사를 별도로 수행한다. 실패 가능성을 배포 전에 드러내는 검사다.

쓰기 중단 시점, 백업 복원 또는 데이터 변환 방법, 복구 중 발생한 새 대화의 처리 기준을 정한다.

이는 권장 운영 절차이지 ADK가 제공하는 자동 역마이그레이션 기능이 아니다. 같은 저장소를 구·신 버전이 동시에 사용하는 롤링 배포도 확인 대상이다. 특히 app·user state를 공유한다면 세션 ID만 나누었다고 저장 형식까지 격리됐다고 판단하면 안 된다.

4. 안정화된 기능: 실험 플래그를 보안 정책으로 쓰지 않기

이번에 안정화된 16개 도구·통합 기능에서는 기존 @experimental 게이트가 제거됐다. GCS 도구, Computer Use, Daytona·E2B 환경, MCP agent server 등이 포함된다. 해당 ADK_DISABLE_*나 --disable_features 설정만으로 기능 사용을 막던 배포는 실제 도구 등록과 접근권한을 다시 점검해야 한다. 안정화·게이트 제거 변경

다만 전체 플래그 시스템이 폐지된 것은 아니다. 태그의 is_feature_enabled()는 여전히 override와 환경변수를 읽는다. 게이트가 제거된 기능의 차단 효과와 플래그 조회 함수의 반환값을 혼동하지 말아야 한다. 필요한 도구만 등록하고, 실행 계정·자격 증명·백엔드 권한으로 허용 범위를 정한다. 안정화가 도구의 자동 실행을 뜻하지도 않는다. v2.14.0의 실제 플래그 코드

배포 전에 남길 확인 기록

새 버전은 반복·병렬 평가도 지원한다. 같은 평가를 여러 번 실행해 통과율 변동을 보는 것은 도움이 되지만, 호출 횟수와 외부 모델 비용도 늘 수 있다. 평가 횟수·동시성·비용 한도를 정한 뒤 사용한다. 반복 평가를 포함한 공식 릴리스

실제 배포 이미지와 lockfile에서 ADK 버전 및 추가 의존성을 확인한다.

Enum의 정상·비정상 값, 승인 필요·불필요 분기를 함께 검사한다.

스킬 인자·지원 확장자·상대 경로가 새 계약에 맞는지 검사한다.

Firestore는 전진 읽기·쓰기와 이전 버전 복구를 따로 검증한다.

제한하려던 도구가 등록되지 않는지, 실제 권한이 필요한 범위만 허용하는지 확인한다.

이 글의 Python 예제는 표준 라이브러리만으로 문자열·멤버 정규화, JSON 출력, 잘못된 값 거부 등 6개 로컬 검사를 통과했다. ADK 설치·실제 에이전트 실행·Firestore 접속·스킬 실행·유료 모델 평가는 수행하지 않았다. 공식 코드 검토와 작은 언어 동작 검사는 실제 서비스의 업그레이드 성공을 보증하지 않는다.

핵심은 버전 번호보다 네 가지 계약을 확인하는 것이다. 도구가 받는 값, 스킬을 실행하는 입력, 세션이 저장되는 형식, 기능을 허용하는 권한을 배포 전후로 비교하면 장애와 복구 위험을 더 일찍 발견할 수 있다.