Gemini Interactions API로 옮길 때는 대화 이력 연결과 장기 작업의 상태 처리를 바꿔야 합니다. Google 공식 개요는 정식 출시와 신규 프로젝트 사용을 안내하며 generateContent의 계속 지원도 명시합니다.
기준일은 2026-10-09입니다. Gemini Developer API를 대상으로 하며, 문서를 확인했지만 실제 API 호출은 실행하지 않았습니다.
> - 대화는 완료된 요청의 식별자로 이어갑니다.
> - 도구·시스템 지시·생성 설정은 매 요청 다시 보냅니다.
> - 저장을 끄면 후속 대화 연결과 백그라운드 실행에 제약이 생깁니다.
주요 용어
서버 기록과 앱이 관리할 정보를 구분하는 용어입니다.
용어이 글에서의 의미
| Interaction | 대화나 작업 한 턴의 실행 기록 |
| previous_interaction_id | 이전 완료 기록을 연결하는 식별자 |
| store | 요청·응답 기록의 서버 저장 여부 |
| background | 서버에서 비동기로 실행하는 옵션 |
| steps | 실행 과정과 출력을 담는 단계 목록 |
호출과 응답은 어떻게 바뀌나요?
JavaScript 기준으로 client.models.generateContent는 client.interactions.create로, 입력의 contents는 input으로 바뀝니다. 응답도 기존 candidates와 content.parts 중심 처리에서 steps를 읽는 방식으로 옮깁니다. Google의 Interactions 마이그레이션 가이드를 기준으로 한 대응입니다.
텍스트만 필요하면 SDK의 output_text를 사용할 수 있습니다. 다만 응답 끝의 연속된 텍스트를 모으는 편의 속성이므로, 도구·이미지 등이 섞인 결과 전체를 대신한다고 가정하면 안 됩니다.
Google의 「Interactions API: Breaking changes migration guide (May 2026)」는 옛 outputs를 steps로 바꿨다고 설명합니다. 과거 Interactions 예제를 복사할 때도 응답 구조를 확인해야 합니다. 이 변경은 generateContent 지원 종료와 별개입니다.
대화 상태는 무엇을 이어주나요?
완료된 응답의 id를 저장하고 다음 요청의 previous_interaction_id에 넣으면 입력·출력 이력이 이어집니다. tools, system_instruction, generation_config는 상속되지 않으므로 매 턴 다시 지정합니다. 근거는 Google 「Interactions API」 개요이며 확인일은 위 기준일과 같습니다.
다음은 미실행 의사코드이며 SDK 실행 예제가 아닙니다.
첫 요청 = create(input=첫 질문, 공통 설정)
첫 요청의 completed 상태 확인
앱의 사용자·대화 식별자에 첫 요청.id 저장
다음 요청 = create(input=후속 질문,
previous_interaction_id=첫 요청.id,
공통 설정)기존 contents 배열은 자동 이전되지 않습니다. 과거 이력을 새 입력 형식으로 변환하고 새 식별자를 앱의 대화 기록과 연결하는 절차를 권합니다. 이는 문서에 기반한 구현 제안입니다.
저장 기본값은 store=true입니다. store=false로 만든 기록은 후속 식별자 연결에 사용할 수 없고 백그라운드 실행과도 호환되지 않습니다. 문서상 보관 기간은 유료 55일, 무료 1일이며 유료 프로젝트는 기간을 줄일 수 있으므로, 식별자를 영구 대화 저장소처럼 취급하지 마세요.
백그라운드 작업은 어떻게 복구하나요?
background=true로 생성하면 식별자를 먼저 받고, interactions.get으로 진행 상황과 결과를 조회합니다. Google 「Background execution」은 일반 Gemini 모델과 관리형 에이전트의 지원을 안내합니다.
앱에서는 식별자를 먼저 영속 저장하고 조회 간격·재시도 상한을 정하는 편이 좋습니다. 연결이 끊겼다면 저장한 식별자로 기존 작업부터 확인하세요. 생성 요청을 다시 보내는 것만으로 중복 실행 방지가 보장되지는 않습니다.
조회 결과는 Google Interactions API 레퍼런스의 상태에 따라 나눠 처리합니다.
상태앱의 처리 방향
| queued / in_progress | 대기·실행 중으로 표시하고 제한적으로 재조회 |
| requires_action | 필요한 도구 결과 등 후속 조치를 처리 |
| completed | 결과를 저장하고 조회 종료 |
| failed / cancelled | 실패·취소를 기록하고 조회 종료 |
| incomplete | 불완전 결과로 구분하고 원인 확인 |
스트리밍을 쓴다면 마지막 event_id를 저장하고 재접속 때 last_event_id로 전달합니다. cancel은 실행 중단, delete는 저장 기록 삭제이므로 사용자 화면에서도 구분해야 합니다. 취소 상태 반영에는 지연이 있을 수 있습니다.
이전 전 무엇을 검증해야 하나요?
공식 개요는 Python·JavaScript SDK 2.3.0 이상을 안내합니다. Batch API, Python 자동 함수 호출, 명시적 캐싱, 사용자 지정 안전 설정은 미지원 목록에 있으므로 기존 앱의 의존성을 먼저 확인하세요.
조사한 문서의 REST 경로에는 v1beta와 v1beta2가 혼재하고, 일부 응답·이벤트 예시도 다릅니다. 실제 호출로 확인하지 못했으므로 적용할 SDK 버전을 고정한 뒤 해당 레퍼런스와 응답을 대조해야 합니다. 상태 저장만으로 비용·속도 개선이 보장되는 것도 아닙니다.
먼저 대화 하나와 장기 작업 하나를 시험 대상으로 잡으세요. 두 번째 턴의 문맥 유지, 설정 재전송, 앱 재시작 후 재조회, 만료된 식별자와 불완전 결과 처리까지 확인한 뒤 이전 범위를 넓히면 됩니다.
참고 링크
'AI' 카테고리의 다른 글
| Gemini Docs MCP와 API Skill 설치: 코딩 에이전트의 오래된 예제 줄이기 (0) | 2026.10.09 |
|---|---|
| Claude Managed Agents 비용 제한: max_list_cost 설정과 중단 후 재개 (0) | 2026.10.09 |
| Codex Goals 사용법: 완료 조건으로 장기 디버깅 끝내기 (0) | 2026.10.08 |
| Codex 반복 수정 루프 설계: 리뷰·수정·검증 결과를 다음 실행에 연결하기 (0) | 2026.10.06 |
| Gemini API 구조화된 출력(Structured Outputs)과 컨텍스트 캐싱 연동 실전 패턴 (0) | 2026.09.27 |
