제미나이 새 API, 켜는 순간 대화가 서버에 남는다

Gemini API로 서비스를 운영하는 개발자는 권장이라는 말만 보면 코드부터 옮긴다.

엔드포인트 이름이 바뀐 줄 알았다가, 옮기고 나서 다른 조건을 만난다.

권장 API로 전환하면 요청과 대화 데이터는 실제 어떻게 보관되는가.

GA에 도달했다는 사실부터

Google이 Interactions API를 일반 공개로 전환했다.

공개 베타를 거쳐 GA 버전은 안정된 스키마를 갖췄다.

Managed Agents와 background execution이 추가됐다.

Gemini Omni 지원은 개발 중이다.

Google은 제미나이 API를 신규 프로젝트의 기본으로 권장한다.

generateContent는 여전히 완전히 지원된다.

당분간 신규 주력 모델을 계속 받는다고 Google은 말한다.

기존 API가 곧 종료된다는 발표는 없다.

저장은 기본값이다

제품 문서는 Interaction을 시간순 실행 단계를 담은 저장된 세션 기록으로 정의한다.

제미나이 API는 store=true를 기본값으로 요청을 저장한다.

이후 요청은 previous_interaction_id로 이전 대화를 이어간다.

유료 티어 프로젝트는 보존기간을 선택할 수 있다.

저장된 interaction은 나중에 삭제할 수 있다.

파라미터는 매번 다시 지정한다

tools, system_instruction, generation_config는 interaction 단위로 스코프된다.

thinking_level과 temperature도 마찬가지다.

새 interaction을 만들 때마다 이 값을 다시 지정해야 한다.

이전 요청에서 넘긴 설정이 자동으로 이어지지 않는다.

마이그레이션 가이드는 generateContent의 직접 응답과 Interaction의 steps 타임라인을 구분한다.

output_text는 단순한 응답을 받을 때 쓴다.

복잡하거나 interleaved multimodal 응답은 steps를 직접 순회해야 한다.

백그라운드로 돌리면 기다려야 한다

background=true로 요청하면 interaction ID가 즉시 돌아온다.

이는 제미나이 API 백그라운드 실행 문서에 나와 있다.

클라이언트는 상태를 폴링해야 한다.

진행을 스트리밍하거나 끊긴 스트림에 재연결할 수도 있다.

종료 상태는 completed, failed, cancelled로 나뉜다.

in_progress 상태인 interaction에는 후속 interaction을 체이닝할 없다.

completed가 될 때까지 기다려야 한다.

권장이 실제로 요구하는 것

store=false는 저장을 옵트아웃한다.

동시에 background execution과 양립하지 않는다.

이후 previous_interaction_id 사용도 막힌다.

저장을 켜 두면 대화가 서버에 쌓인다.

저장을 끄면 백그라운드 실행과 이어쓰기가 함께 꺼진다.

두 조건이 묶여 있다.

이 부분이 권장이라는 단어가 감추고 있는 계약이다.

권장 API로 가면 더 쉬워질 것이라는 기대는 지켜야 할 조건이 늘어나는 쪽으로 뒤집힌다.

파라미터가 interaction 단위로 스코프된다는 사실도 같은 방향을 가리킨다.

기존 멀티턴 호출 코드가 그대로 옮겨지지 않는다.

호출부마다 재지정 로직을 더해야 한다는 뜻이다.

generateContent가 당분간 계속 지원된다는 표현도 완전한 동등 유지는 아니다.

이관 시점이 아직 정해지지 않은 유예 기간에 가깝다.

옮기기 전에 확인할 순서

먼저 지금 쓰는 프로젝트의 store 기본값을 확인한다.

기본값을 그대로 두면 대화가 쌓인다는 전제부터 세운다.

유료 티어라면 보존기간을 정한다.

그다음 tools와 system_instruction을 다시 지정해야 하는 호출부가 몇 군데인지 센다.

generation_config, thinking_level, temperature도 확인한다.

background execution을 쓸 계획이라면 in_progress 상태에서 체이닝이 막힌다는 조건을 코드에 반영한다.

GA 발표, 제품 문서, 마이그레이션·백그라운드 가이드를 순서대로 확인하면 이 조건이 전부 나온다.

확정된 것과 남는 것

제미나이 API의 GA 도달과 store=true 기본값은 문서에 명시돼 있다.

store=false의 비양립 조건도 마찬가지다.

제미나이 API 이관은 엔드포인트를 바꾸는 것과 다르다.

저장과 보존과 기능 가운데 무엇을 선택할지 정하는 일에 가깝다.

Google은 장기 실행 모델과 에이전트의 최신 기능이 점점 더 Interactions API에만 실릴 것으로 예상한다.

이건 아직 구글의 예측 진술이다.

비용과 지연이 store=true와 store=false 경로에서 얼마나 차이 나는지는 문서에 없다.

store=false 상태에서 background execution을 호출했을 때 실제 에러 메시지도 마찬가지다.

보존기간 선택이 요금제 비용에 미치는 차이는 공개되지 않았다.

실제 이관에 드는 코드 변경량도 문서가 값을 주지 않는다.

이 넷은 각자 써보고 측정해야 아는 영역으로 남는다.