Gemini Interactions API 변경: steps 스키마 전환 체크리스트
outputs 의존 코드가 오늘 깨질 수 있는 지점을 빠르게 점검합니다
Gemini Interactions API 변경: 오늘 바뀐 핵심
2026년 5월 26일부터 Gemini v1beta Interactions API의 REST 응답은 legacy outputs 배열보다 steps 타임라인 스키마가 기본입니다. 2026년 6월 8일에는 legacy schema 제거가 예정되어 있어 응답 파싱, streaming event, 테스트 fixture를 오늘 바로 확인해야 합니다.
Gemini Interactions API steps outputs May 26 2026 이슈는 릴리스 노트 한 줄로 넘기기 어렵습니다. Interactions API를 REST로 호출하거나 SDK 응답을 직접 파싱하는 프로젝트라면, API 호출은 성공했는데 앱 안의 JSON path, UI 렌더러, SSE 핸들러, golden fixture가 실패하는 식으로 문제가 드러납니다.
제가 보기에는 이번 변경의 중심은 “응답 결과가 어디에 들어 있느냐”보다 “모델 실행 과정을 어떤 구조로 관찰하느냐”에 가깝습니다. legacy outputs는 결과 배열을 읽는 방식에 가까웠고, steps는 사용자 입력, 모델 출력, 도구 호출, 도구 결과를 순서 있는 타임라인으로 다룹니다.
Google 공식 문서의 날짜와 범위를 기준으로 보면, 오늘 확인할 곳은 의외로 좁습니다. `outputs`를 직접 읽는 코드, legacy streaming event 이름, `response_mime_type` fixture, 그리고 2026-06-08 이후에도 남을 수 있는 legacy opt-out 의존입니다.
일정 정리: 5월 26일 기본 전환, 6월 8일 제거
이번 변경은 2026년 5월 6일 release note에서 예고된 Interactions API schema migration입니다. 핵심 날짜는 2026-05-26 default flip과 2026-06-08 legacy removal입니다.
2026년 5월 7일부터는 새 스키마를 미리 적용할 수 있는 opt-in 단계가 있었고, 2026년 5월 26일부터 REST에서는 steps 스키마가 기본값입니다. legacy outputs 응답이 꼭 필요하면 2026년 6월 8일 전까지 `Api-Revision: 2026-05-07` 헤더로 임시 회피가 가능하지만, 이 선택지는 오래가는 rollback 전략이 아닙니다.
| 날짜 | 의미 | 실무 조치 |
|---|---|---|
| 2026-05-06 | release note에서 breaking change 예고 | 영향 범위를 Interactions API로 한정해 확인 |
| 2026-05-26 | REST 기본 응답이 steps 중심으로 전환 | outputs fixture와 parser smoke test 실행 |
| 2026-06-08 | legacy schema 제거 예정 | legacy opt-out 의존 제거 |
한국 사용자 입장에서는 “오늘부터 모든 Gemini API가 깨진다”가 아니라 “v1beta Interactions API를 쓰는 코드 중 legacy 응답 구조에 기대는 부분을 고쳐야 한다”가 더 정확한 해석입니다. 날짜를 이렇게 놓고 보면, 오늘의 목표는 새 기능 탐색이 아니라 깨질 수 있는 경로를 줄이는 쪽입니다.
outputs와 steps는 무엇이 다른가
legacy outputs는 결과 배열 중심이고, 새 steps는 interaction turn을 순서 있는 실행 타임라인으로 표현합니다. POST /interactions와 GET /interactions/{id}의 반환 범위도 달라 단순 필드명 교체로 끝내기 어렵습니다.
Gemini API outputs steps 변경에서 가장 눈에 띄는 차이는 최상위 응답 shape입니다. 예전 코드는 `interaction.outputs`처럼 결과 묶음을 직접 찾아 들어가는 경우가 많았습니다. 새 구조에서는 `steps`를 순회하면서 `type`에 따라 output, function_call, google_search_call, google_search_result 같은 단계를 구분합니다.
POST `/interactions` 응답은 output step 중심으로 돌아오지만, GET `/interactions/{id}`는 user_input까지 포함한 전체 step timeline을 보여줍니다. 그래서 “응답 텍스트만 보여주는 UI”와 “도구 호출 과정을 보여주는 agent UI”의 수정 범위가 다릅니다.
> steps는 결과 하나를 꺼내는 배열이라기보다, Interactions API 실행 과정을 재생 가능한 기록으로 보는 구조입니다.
단순 텍스트만 쓰는 SDK 앱이라면 `output_text` convenience property로 영향이 작습니다. 반대로 도구 호출, 검색 결과, 장기 실행 workflow를 화면에 보여주는 앱은 renderer와 로그 구조까지 같이 봐야 합니다.
깨질 가능성이 높은 코드: 파서, 스트리밍, 도구 호출
가장 위험한 지점은 interaction.outputs 직접 접근, legacy SSE event 이름, outputs 내부 function_call 탐색, response_mime_type 기반 structured output fixture입니다. 이 코드는 steps 순회와 새 response_format 구조를 기준으로 바꿔야 합니다.
실제로 확인할 부분은 코드 검색으로 빨리 좁힐 수 있습니다. `outputs`, `interaction.outputs`, `content.delta`, `content.start`, `response_mime_type`, `generation_config.image_config` 같은 문자열을 찾으면 영향 범위가 꽤 선명해집니다. Gemini Interactions API steps outputs May 26 2026 변경은 문서상 field 이름 변화처럼 보이지만, 테스트에서는 parser miss와 빈 렌더링으로 나타날 가능성이 큽니다.
streaming chat UI는 이벤트 이름 변경이 중요합니다. legacy `interaction.start`, `content.start`, `content.delta`, `content.stop`, `interaction.complete`에 맞춘 SSE handler는 새 `interaction.created`, `step.start`, `step.delta`, `step.stop`, `interaction.completed` 계열을 처리해야 합니다.
function calling도 같은 맥락입니다. 예전처럼 outputs 안의 content type을 뒤져 function_call을 찾는 대신, steps 안의 function_call step을 찾고 function_result 입력 재전송 흐름을 테스트해야 합니다. Google Search 같은 server-side tool 결과도 output content가 아니라 `google_search_call`, `google_search_result` 같은 step type으로 이동합니다.
structured output을 쓰는 프로젝트는 `response_mime_type` 제거와 `response_format.mime_type` 구조를 fixture에 반영해야 합니다. image generation 설정도 `generation_config.image_config`가 아니라 `response_format`의 image 항목 쪽을 확인합니다.
오늘 바로 할 마이그레이션 체크리스트
최소 점검은 같은 Interactions API 호출을 새 스키마로 실행해 steps 응답을 확인하고, 기존 golden fixture가 outputs만 기대하는지 보는 일입니다. SDK 사용자는 패키지 업데이트와 별개로 output_text 또는 steps 접근 코드를 고쳐야 합니다.
오늘 할 일은 작게 시작하는 편이 낫습니다. 실제 서비스와 같은 모델, 같은 endpoint, 같은 tool 설정으로 `/v1beta/interactions` 호출을 한 번 실행하고 최상위 `steps`가 오는지 확인합니다. 그다음 기존 테스트 fixture가 `outputs`만 기대하는지, UI renderer가 step type을 무시하는지 봅니다.
- REST wrapper: `Api-Revision` 헤더를 어디서 넣는지 확인하고, 2026-06-08 이후 legacy opt-out이 남지 않게 제거 계획을 잡습니다.
- Python SDK: 공식 설치 경로는 `pip install google-genai`이며, Python 2.0.0 이상 사용 여부와 `interaction.output_text` 또는 `interaction.steps` 접근을 확인합니다.
- JavaScript/TypeScript SDK: 공식 설치 경로는 `npm install @google/genai`이며, JavaScript 2.0.0 이상 사용 여부와 TypeScript type guard를 점검합니다.
- streaming UI: `step.delta` smoke test를 추가하고, 빈 답변 렌더링을 애플리케이션 오류로 집계합니다.
- structured output: `response_format` fixture를 새 구조로 갱신하고 JSON schema wrapper를 확인합니다.
다만 여기서 조심할 점은 SDK 업데이트만으로 마이그레이션이 끝났다고 보면 안 된다는 점입니다. SDK가 새 schema에 맞춰도, 우리 코드가 여전히 legacy `outputs` 경로만 읽고 있으면 화면과 테스트는 실패합니다.
도입 시뮬레이션: 테스트에서 운영까지
Python은 google-genai, JavaScript/TypeScript는 @google/genai 경로를 확인한 뒤 Interactions API 호출, streaming smoke test, response_format fixture를 순서대로 검증합니다. generateContent만 쓰는 프로젝트나 beta Interactions API 변경을 감당하기 어려운 production workload는 직접 대상이 아닐 가능성이 큽니다.
작은 팀이라면 세 단계로 나눠 보는 쪽을 권합니다. 1단계는 REST wrapper 또는 SDK adapter에서 응답을 한 번 정규화하는 작업입니다. `steps`를 그대로 모든 화면에 흘려보내기 전에, 텍스트 출력, 도구 호출, 도구 결과, 에러 상태를 내부 타입으로 나누면 이후 변경 대응이 쉬워집니다.
2단계는 fixture 교체입니다. Gemini Interactions API 마이그레이션에서 golden response는 단순 참고 자료가 아니라 회귀 테스트의 기준입니다. 기존 fixture가 `outputs[0].content` 같은 경로만 검증한다면, 새 fixture는 `steps` 배열과 step type을 함께 검증해야 합니다.
3단계는 운영 관측입니다. 2026년 5월 26일 이후에는 HTTP 200이어도 앱이 실패할 수 있으므로, JSON path miss, null `output_text`, empty rendered answer, streaming parser error를 별도 metric으로 잡는 편이 좋습니다. function calling orchestration을 쓰는 경우 `requires_action`, `function_call` step, function result 재전송 흐름도 로그에 남겨야 합니다.
개인적으로는 REST opt-out 헤더를 “시간 벌기”로만 보는 쪽이 안전하다고 봅니다. 2026년 6월 8일 이후에도 legacy outputs에 남아 있을 계획이라면, 지금은 새 기능 도입보다 기존 의존 제거가 먼저입니다.
왜 개발자가 오늘 확인해야 하나
2026년 5월 26일 이후에는 REST 기본 응답 shape가 바뀌기 때문에 API 호출 자체가 성공해도 앱 내부 JSON path, UI renderer, SSE handler, fixture 비교가 실패할 여지가 큽니다. 2026년 6월 8일 이후에는 legacy opt-out으로 미루는 선택지도 사라질 예정입니다.
이번 Gemini API May 26 2026 breaking change는 장애 대응보다 배포 리스크 관리에 가깝습니다. API status가 정상이어도, 내부 테스트가 예전 응답 shape를 기준으로 굳어 있으면 배포 후 화면이 비거나 도구 호출 로그가 사라질 수 있습니다.
특히 한국에서 소규모 자동화 서버나 개인 SaaS를 운영하는 경우, Gemini API wrapper를 한 번 만들어 여러 봇이나 백오피스 기능에서 공유하는 일이 많습니다. 이때 wrapper 하나가 `outputs`에 강하게 묶여 있으면 영향 범위가 생각보다 커집니다.
실제로 확인할 순서는 REST wrapper와 SDK adapter, streaming chat UI, function calling orchestration, Google Search 또는 Code Execution 같은 server-side tool renderer, structured JSON output parser, image output configuration입니다. 전부 한 번에 고치기 어렵다면 wrapper와 fixture부터 잡는 편이 현실적입니다.
오해하면 안 되는 범위와 리스크
이번 변경은 Gemini API 전체나 generateContent API 전체의 중단이 아니라 v1beta Interactions API의 breaking change입니다. SDK 업데이트만으로 모든 응답 파싱 문제가 자동 해결된다고 단정해서도 안 됩니다.
Gemini Interactions API steps outputs May 26 2026 변경을 읽을 때 가장 피해야 할 오해는 범위 확대입니다. 공식 문서의 대상은 v1beta Interactions API입니다. generateContent API만 안정적으로 쓰는 프로젝트라면 이번 체크리스트가 직접 수정 항목이 아닐 가능성이 큽니다.
반대로 Interactions API를 쓰고 있다면 영향이 작다고 단정하기도 어렵습니다. 단순 텍스트 응답만 `output_text`로 읽는 앱은 수정 범위가 작을 수 있지만, 도구 호출, 검색 결과, structured output, image output, streaming을 함께 쓰면 테스트해야 할 표면이 넓어집니다.
또 하나의 리스크는 beta API를 production 핵심 경로에 넣었을 때의 변경 관리입니다. Google 문서도 Interactions API의 beta 성격과 stable path 선택지를 함께 안내합니다. 운영 안정성이 최우선인 팀은 Interactions API를 계속 쓸지, generateContent 기반 경로를 유지할지 분리해서 판단하는 편이 맞습니다.
자주 묻는 질문
Q. Gemini Interactions API steps 스키마는 outputs와 무엇이 다른가?
A. outputs는 결과 배열 중심이고, steps는 interaction turn의 실행 과정을 순서 있는 step timeline으로 표현합니다. function_call, google_search_result 같은 항목도 step type으로 다뤄야 하므로 parser와 renderer를 함께 확인해야 합니다.
Q. 2026년 5월 26일부터 REST 호출에서 실제로 바뀌는 기본값은 무엇인가?
A. Gemini v1beta Interactions API REST 요청에서 새 steps 스키마가 기본 응답 구조가 됩니다. 기존 테스트가 outputs 최상위 필드만 기대한다면 같은 호출이 성공해도 fixture 비교가 실패할 수 있습니다.
Q. legacy outputs 응답을 며칠 더 유지하려면 어떤 헤더를 써야 하나?
A. 2026년 6월 8일 전까지 REST에서는 `Api-Revision: 2026-05-07` 헤더로 legacy schema에 임시 opt-out이 가능합니다. 다만 이 헤더는 장기 rollback이 아니라 마이그레이션 시간을 버는 용도에 가깝습니다.
Q. SDK 사용자는 버전만 올리면 끝인가?
A. 아닙니다. Python 2.0.0 이상 또는 JavaScript 2.0.0 이상 SDK는 새 스키마에 자동 opt-in되지만, 애플리케이션 코드가 여전히 `interaction.outputs`를 읽는다면 수정이 필요합니다. `output_text` convenience property 또는 `steps` 순회 방식으로 테스트를 갱신해야 합니다.
Q. streaming 이벤트를 쓰는 앱은 무엇을 먼저 바꿔야 하나?
A. legacy `content.delta` 중심 handler를 `step.delta` 중심 handler로 바꾸는 smoke test부터 추가하는 것이 좋습니다. 함께 `interaction.created`, `step.start`, `step.stop`, `interaction.completed` 이벤트를 처리하는지 확인해야 합니다.
Q. generateContent만 쓰는 프로젝트도 바로 수정해야 하나?
A. 공식 변경 범위는 v1beta Interactions API입니다. generateContent만 쓰고 Interactions API 호출이 없다면 직접 수정 대상이 아닐 수 있지만, 내부 wrapper가 두 API를 함께 감싸고 있다면 의존 코드를 검색해 확인하는 편이 안전합니다.
함께 읽으면 좋은 글
참조 링크
- Interactions API: Breaking changes migration guide (May 2026) — 2026-05-26 default flip, 2026-06-08 legacy schema removal, Api-Revision 헤더, steps migration, streaming event, response_format 변경의 핵심 원문입니다.
- Gemini API Release notes — 2026-05-06 release note에서 Interactions API outputs to steps 및 response_format 변경 예고 흐름을 확인하는 보조 근거입니다.
- Interactions API — Interactions API의 beta status, steps timeline 의미, server-side state, production workload 주의점을 확인하는 배경 문서입니다.
- Gemini API libraries — Python google-genai 및 JavaScript/TypeScript @google/genai 공식 설치 경로를 확인하는 문서입니다.