Gemini Interactions API 마이그레이션: outputs에서 steps로 바뀌는 구조와 점검 순서

API 변경은 SDK 업데이트보다 로그 구조 변경이 더 위험하다

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는 결과 중심, steps는 실행 타임라인 중심이다

기존 outputs 배열은 모델이 생성한 결과를 평평하게 담는 구조였습니다. 텍스트 출력, 함수 호출, 검색 호출 결과 등이 outputs 안에 들어왔습니다. 간단한 챗봇에서는 이 방식도 충분했습니다. 마지막 text만 꺼내 보여주면 됐기 때문입니다.

새 steps 배열은 관점이 다릅니다. 문서에 따르면 POST /interactions는 output steps를 반환하고, GET /interactions/{id}는 초기 user_input step을 포함한 전체 step timeline을 반환합니다. 즉 단순 결과가 아니라 상호작용의 구조화된 흐름을 저장하는 방식입니다.

이 변화는 future capability인 mid-flight steering과 asynchronous tool calls를 지원하기 위한 구조로 설명됩니다. 실무적으로는 다음 질문에 답하기 쉬워집니다.

• 사용자의 입력은 무엇이었나?
• 모델이 어떤 중간 사고 또는 도구 호출을 만들었나?
• 어떤 server-side tool이 호출됐나?
• 최종 출력은 어떤 step에서 나왔나?
• 스트리밍 중 어떤 이벤트가 발생했나?

따라서 마이그레이션의 핵심은 필드명을 바꾸는 것이 아니라, 에이전트 실행 기록을 steps timeline으로 다루도록 코드와 로그를 바꾸는 것입니다.

변경 1: 기본 응답 파싱은 output_text로 단순화할 수 있다

가장 단순한 unary 호출에서는 SDK convenience property를 쓰는 편이 안전합니다. 문서는 Python과 JavaScript 예시에서 interaction.outputs[-1].text 대신 interaction.output_text 사용을 권장합니다.

이 방식은 UI에 최종 텍스트만 보여주는 서비스에 적합합니다. 하지만 운영 로그나 도구 호출 분석이 필요한 서비스라면 output_text만 저장하면 안 됩니다. steps 원본도 함께 저장해야 나중에 디버깅할 수 있습니다.

추천 기준은 다음과 같습니다.

• 사용자 화면: output_text 같은 convenience property 사용
• 서버 로그: steps 전체 저장
• 분석용 이벤트: step.type, tool call id, status, latency 저장
• 테스트 fixture: legacy outputs fixture와 new steps fixture를 분리

특히 기존 코드가 outputs[-1]에 text가 있다고 가정한다면 바로 깨질 수 있습니다. function_call이나 tool result가 섞이는 경우 마지막 항목이 항상 사용자에게 보여줄 텍스트라고 보장하기 어렵기 때문입니다.

변경 2: function calling은 step type 기준으로 읽어야 한다

문서의 function calling 예시는 legacy outputs 순회에서 new steps 순회로 바뀝니다. 기존에는 output.type == function_call을 찾았다면, 새 구조에서는 step.type == function_call을 확인합니다.

이 변경은 작아 보이지만, 운영 코드에서는 다음 부분을 함께 점검해야 합니다.

1. function call id를 어디에 저장하는가?
2. arguments를 JSON 문자열로 받는가, 객체로 받는가?
3. tool result와 function call을 어떻게 매칭하는가?
4. requires_action 상태를 어떤 큐에 넣는가?
5. 실패한 도구 호출을 재시도할 때 같은 interaction id를 유지하는가?

특히 여러 도구가 섞이는 에이전트에서는 step timeline이 중요합니다. 단순히 마지막 function_call만 처리하면 중간 도구 호출, 검색 결과, 모델 출력의 순서를 잃어버립니다. 이 순서를 잃으면 장애 분석이 어려워집니다.

변경 3: server-side tools는 content가 아니라 step으로 다뤄진다

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를 만들었다면 수정이 필요합니다. 검색 기반 답변을 제공하는 서비스라면 다음 항목을 테스트해야 합니다.

• 검색 query가 로그에 남는가?
• 검색 result와 최종 답변 annotation이 연결되는가?
• citation URL과 title이 UI에 표시되는가?
• 검색 실패 시 model_output만 남는 케이스를 처리하는가?
• 개인정보나 민감 검색어가 로그에 과도하게 저장되지 않는가?

steps 구조는 더 정확한 감사를 가능하게 하지만, 저장 정책을 잘못 잡으면 민감한 중간 과정까지 과도하게 저장할 수 있습니다.

변경 4: streaming event 이름이 바뀐다

스트리밍을 쓰는 서비스는 이벤트 이름 변경을 반드시 점검해야 합니다. 문서에 따르면 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과 자동 실행을 섞지 않는 편이 안전합니다.

마이그레이션 순서

안전한 순서는 다음과 같습니다.

1. 현재 코드에서 outputs, response_mime_type, content.delta를 검색합니다.
2. 응답 파싱 코드를 화면 표시용과 로그 저장용으로 나눕니다.
3. Api-Revision: 2026-05-20 헤더로 새 schema를 테스트 환경에서 먼저 켭니다.
4. unary, function calling, server-side tools, streaming 케이스별 fixture를 새로 만듭니다.
5. steps 원본을 저장하되 민감한 tool arguments는 마스킹합니다.
6. 6월 8일 legacy schema 제거 전에 production shadow test를 수행합니다.

Google 문서는 Gemini Interactions API skill을 사용해 coding agent로 migration을 자동화할 수 있다고 설명합니다. 이 접근은 유용하지만, 자동 패치 후에도 테스트 fixture와 로그 스키마는 사람이 확인해야 합니다.

실행 체크리스트

Gemini Interactions API 마이그레이션 전에 다음 항목을 확인하세요.

1. outputs를 직접 참조하는 코드를 모두 찾았습니다.
2. 최종 텍스트 표시는 output_text 또는 model_output content 기준으로 바꿨습니다.
3. function_call은 step.type 기준으로 처리합니다.
4. server-side tool call과 result를 steps timeline으로 저장합니다.
5. streaming event는 step.delta 중심으로 교체했습니다.
6. function call streaming의 arguments_delta 누적 로직을 테스트했습니다.
7. 2026년 6월 8일 제거 일정 전에 production rollout 계획을 잡았습니다.

이번 변경은 귀찮은 필드명 교체가 아닙니다. Gemini Interactions API가 단순 응답 API에서 에이전트 실행 타임라인 API로 이동하는 신호입니다. 지금 점검해야 할 질문은 이것입니다. 우리 서비스는 모델의 마지막 답변만 저장하고 있나요, 아니면 도구 호출과 중간 결과까지 재현할 수 있나요?

출처: Google AI for Developers, “Interactions API: Breaking changes migration guide (May 2026)”.