Gemini Interactions API를 쓰는 팀이라면 2026년 6월 8일을 먼저 확인해야 합니다. Google AI for Developers 문서에 따르면 v1beta Interactions API의 legacy schema가 2026년 6월 8일 제거됩니다. 핵심 변경은 기존 outputs 배열이 steps 배열로 바뀌고, 출력 형식 제어가 response_format으로 통합되는 것입니다.
겉으로 보면 필드명 변경처럼 보입니다. 하지만 실제 영향은 더 큽니다. 응답 파싱, function calling, server-side tools, streaming event, 로그 저장, 테스트 fixture, 모니터링 대시보드가 모두 영향을 받을 수 있습니다. 특히 에이전트 워크플로우에서 “모델이 무엇을 했는지”를 outputs만 보고 기록하던 팀은 steps 구조에 맞춰 타임라인을 다시 저장해야 합니다.
이 글은 Gemini Interactions API 마이그레이션을 빠르게 끝내는 법이 아니라, 운영 장애 없이 안전하게 옮기는 순서를 다룹니다.
기존 outputs 배열은 모델이 생성한 결과를 평평하게 담는 구조였습니다. 텍스트 출력, 함수 호출, 검색 호출 결과 등이 outputs 안에 들어왔습니다. 간단한 챗봇에서는 이 방식도 충분했습니다. 마지막 text만 꺼내 보여주면 됐기 때문입니다.
새 steps 배열은 관점이 다릅니다. 문서에 따르면 POST /interactions는 output steps를 반환하고, GET /interactions/{id}는 초기 user_input step을 포함한 전체 step timeline을 반환합니다. 즉 단순 결과가 아니라 상호작용의 구조화된 흐름을 저장하는 방식입니다.
이 변화는 future capability인 mid-flight steering과 asynchronous tool calls를 지원하기 위한 구조로 설명됩니다. 실무적으로는 다음 질문에 답하기 쉬워집니다.
따라서 마이그레이션의 핵심은 필드명을 바꾸는 것이 아니라, 에이전트 실행 기록을 steps timeline으로 다루도록 코드와 로그를 바꾸는 것입니다.
가장 단순한 unary 호출에서는 SDK convenience property를 쓰는 편이 안전합니다. 문서는 Python과 JavaScript 예시에서 interaction.outputs[-1].text 대신 interaction.output_text 사용을 권장합니다.
이 방식은 UI에 최종 텍스트만 보여주는 서비스에 적합합니다. 하지만 운영 로그나 도구 호출 분석이 필요한 서비스라면 output_text만 저장하면 안 됩니다. steps 원본도 함께 저장해야 나중에 디버깅할 수 있습니다.
추천 기준은 다음과 같습니다.
특히 기존 코드가 outputs[-1]에 text가 있다고 가정한다면 바로 깨질 수 있습니다. function_call이나 tool result가 섞이는 경우 마지막 항목이 항상 사용자에게 보여줄 텍스트라고 보장하기 어렵기 때문입니다.
문서의 function calling 예시는 legacy outputs 순회에서 new steps 순회로 바뀝니다. 기존에는 output.type == function_call을 찾았다면, 새 구조에서는 step.type == function_call을 확인합니다.
이 변경은 작아 보이지만, 운영 코드에서는 다음 부분을 함께 점검해야 합니다.
특히 여러 도구가 섞이는 에이전트에서는 step timeline이 중요합니다. 단순히 마지막 function_call만 처리하면 중간 도구 호출, 검색 결과, 모델 출력의 순서를 잃어버립니다. 이 순서를 잃으면 장애 분석이 어려워집니다.
Google Search나 Code Execution 같은 server-side tools를 쓰는 팀은 더 주의해야 합니다. 문서는 legacy schema에서 google_search_call과 google_search_result가 outputs 안의 content type으로 반환됐지만, 새 schema에서는 steps 배열의 특정 step type으로 이동한다고 설명합니다.
예를 들어 google_search_call, google_search_result, model_output이 각각 step으로 분리됩니다. 최종 텍스트의 annotation도 url_citation 형태로 들어갈 수 있습니다.
이 구조는 출처 추적에는 유리합니다. 하지만 기존 코드가 search result를 outputs에서 직접 읽어 citations를 만들었다면 수정이 필요합니다. 검색 기반 답변을 제공하는 서비스라면 다음 항목을 테스트해야 합니다.
steps 구조는 더 정확한 감사를 가능하게 하지만, 저장 정책을 잘못 잡으면 민감한 중간 과정까지 과도하게 저장할 수 있습니다.
스트리밍을 쓰는 서비스는 이벤트 이름 변경을 반드시 점검해야 합니다. 문서에 따르면 legacy interaction.start, content.start, content.delta, content.stop, interaction.complete 등이 새 event로 대체됩니다. 새 이벤트에는 interaction.created, interaction.in_progress, interaction.requires_action, interaction.completed, step.start, step.delta, step.stop 등이 포함됩니다.
UI 스트리밍만 하는 서비스라면 content.delta를 step.delta로 바꾸는 수준일 수 있습니다. 하지만 function calling streaming을 쓰는 경우 더 복잡합니다. 문서는 streaming function calls에서 step.start가 function name을 전달하고, step.delta가 arguments_delta 형태의 partial JSON string을 스트리밍한다고 설명합니다. 즉 arguments를 누적해서 완성해야 합니다.
이 부분을 놓치면 도구 호출 인자가 깨진 상태로 실행될 수 있습니다. 특히 결제, 배포, 외부 API 쓰기 같은 도구는 streaming function call과 자동 실행을 섞지 않는 편이 안전합니다.
안전한 순서는 다음과 같습니다.
Google 문서는 Gemini Interactions API skill을 사용해 coding agent로 migration을 자동화할 수 있다고 설명합니다. 이 접근은 유용하지만, 자동 패치 후에도 테스트 fixture와 로그 스키마는 사람이 확인해야 합니다.
Gemini Interactions API 마이그레이션 전에 다음 항목을 확인하세요.
이번 변경은 귀찮은 필드명 교체가 아닙니다. Gemini Interactions API가 단순 응답 API에서 에이전트 실행 타임라인 API로 이동하는 신호입니다. 지금 점검해야 할 질문은 이것입니다. 우리 서비스는 모델의 마지막 답변만 저장하고 있나요, 아니면 도구 호출과 중간 결과까지 재현할 수 있나요?
출처: Google AI for Developers, “Interactions API: Breaking changes migration guide (May 2026)”.
