Gemini의 기본 API가 Interactions API로 변경, 서버가 상태를 관리하는 설계로

Gemini의 문서를 보고 코드를 복사하면, 이전과는 다른 것이 붙여넣기 되기 시작했다. 단순히 요청(Request) 형식이 바뀐 것이 아니다. 대화의 상태를 "누가 보유할 것인가"라는 전제 자체가 바뀌고 있다.

2026년 6월 22일, Google은 Interactions API를 일반 제공(GA, General Availability)하며, Gemini 모델과 에이전트(Agent)를 다루기 위한 기본 인터페이스로 격상시켰다. 2025년 12월 베타 공개 이후 반년 만의 승격으로, AI Studio와 Gemini API, 그리고 공식 문서 모두 이 새로운 API를 기본값으로 전환했다(스니펫을 구형 형식으로 되돌리는 토글은 남아 있다). 지금까지 Gemini를 호출하는 표준이었던 generateContent가 더 이상 "정답"이 아니라고 생각해도 무방하다.

무엇이 바뀌었는지는 generateContent의 사용법을 떠올려 보면 이해하기 쉽다. 그것은 완전히 스테이트리스(Stateless, 상태 비저장) 방식이었다. 대화를 이어가려면 매 턴마다 과거의 모든 주고받은 내용을 요청에 담아 다시 보내야 했다. 짧은 채팅이라면 문제가 없지만, 도구(Tool)를 여러 번 호출하며 몇 분에서 몇 시간 동안 계속 작동하는 에이전트라면, 이 "매번 전체 이력을 재전송하는" 모델은 한계에 부딪힌다. 토큰(Token)은 불어나고, 상태 관리(State Management)는 앱 측의 책임이 된다.

Interactions API는 이 부분을 반전시켰다. 대화의 상태를 서버 측에 저장하고, 대화를 이어갈 때는 직전 주고받은 내용의 ID를 전달하기만 하면 된다. 핵심은 previous_interaction_id라는 파라미터다.

from google import genai
client = genai.Client()
# 1턴째. store는 기본값이 true이므로 상태는 서버에 남는다
...

REST로 보면 엔드포인트(Endpoint)도 심플하다.

curl "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
...

은근히 효과적인 점은, previous_interaction_id로 연결하면 대화 이력의 암묵적 캐시(Implicit Cache)가 잘 작동하여 레이턴시(Latency, 지연 시간)와 비용이 낮아진다는 점이다. 상태를 다시 전달하지 않는 설계가 그대로 과금 측면의 최적화로 이어지고 있다.

두 API의 성격 차이를 비교하면 다음과 같다.

항목	generateContent (구형)	Interactions API (신형)
상태	스테이트리스 (매번 전체 이력 재전송)	서버 측에 저장, previous_interaction_id로 지속
...		background=true로 비동기 실행
유지 기간	없음 (보낸 만큼만)	유료 55일 / 무료 1일
위치 선정	당분간 지원 지속	기본값. 새로운 에이전트 기능은 이쪽으로 집약

스키마(Schema) 측면에서도 흥미로운 변경이 있었다. 기존의 user / model이라는 역할(Role)의 나열이, Interaction 안의 타입이 지정된 **스텝(Step)**의 열로 대체되었다 (Interactions API 문서 기준). 응답의 steps에는 모델의 사고, function_call (도구 호출), function_result (도구 결과), model_output과 같은 개별 동작들이 각각 독립된 스텝으로서 나열된다.

이는 UI 렌더링과 디버깅에 직접적인 도움이 된다. 에이전트가 "지금 무엇을 하고 있는지"를 스텝 단위로 관측할 수 있으므로, 사고 과정이나 도구 호출의 중간 과정을 화면에 표시하거나 어디서 실패했는지 추적하기가 쉬워진다. 출력을 하나의 텍스트로 받아 구조를 직접 파싱(Parsing)하던 시절과 비교하면, 구현의 체감 난이도가 상당히 달라진다.

GA에서 눈에 띄는 것은 Managed Agents다. 공식 블로그의 설명은 다음과 같다.

A single API call provisions a remote Linux sandbox where an agent can reason, execute code, browse the web and manage files.

즉, API를 한 번 호출하는 것만으로 원격 Linux 샌드박스 (Sandbox)가 실행되며, 그 안에서 에이전트 (Agent)가 코드를 실행하고, 웹을 탐색하며, 파일을 조작한다. 기본적으로 Antigravity 에이전트가 탑재되어 있으며, 커스텀 에이전트도 추가할 수 있다. 샌드박스의 조달이나 수명 관리를 자체 인프라에서 직접 부담하지 않아도 된다는 점은 실무에서 은근히 고마운 부분이다.

장시간 실행되는 태스크 (Task)를 위해서는 background=true 옵션이 있다. 이를 설정하여 요청을 보내면 서버 측에서 비동기 (Asynchronous)로 처리를 진행하며, 클라이언트는 나중에 interactions.get을 통해 결과를 가져온다.

job = client.interactions.create(
model="gemini-3.5-flash",
input="리포지토리 전체를 읽고 테스트 실패 원인을 조사해줘",
...

단, store=false와 background=true는 함께 사용할 수 없다. 비동기 실행은 상태 (State)를 서버에 남기는 것을 전제로 하기 때문이다. 비용 측면에서는 속도 중심의 Priority와 비용을 약 50% 절감하는 Flex의 두 단계가 마련되어 있다 (API 레퍼런스).

내 견해로는, 이것은 Google만의 이야기가 아니라 업계의 수렴점이다. 스테이트리스 (Stateless)한 단발성 호출에서, 서버가 상태를 보유하고 실행이 단계 (Step)로서 관측 가능하며, 샌드박스까지 포함하여 관리해 주는 에이전트용 인터페이스로 변화하고 있다. 다른 플랫폼에서도 동일한 방향의 변화를 목격해 온 엔지니어들이 많을 것이며, Gemini 역시 그 흐름에 맞추기 위해 합류했다고 보는 것이 자연스럽다.

실질적인 이점은 명확하다. 대화 이력 (Conversation History)을 다시 보낼 필요가 없어지고, background를 통해 장시간 태스크를 던져놓을 수 있으며, 단계 단위로 내부 내용을 확인할 수 있다. 에이전트적인 기능을 Gemini로 구축한다면, 신규 프로젝트는 이제 Interactions API로 시작하는 것이 타당하다.

우려되는 점도 솔직하게 적어둔다. 상태를 서버가 가진다는 것은 그 상태가 플랫폼에 종속된다는 의미이기도 하다. previous_interaction_id를 전제로 설계할수록 이식성 (Portability)은 떨어진다. 유료 모델이라 해도 보존 기간이 55일인 이상, 오래 참조하고 싶은 문맥 (Context)은 결국 앱 측에서도 보유해야 한다. generateContent는 당분간 지원되겠지만, Google 스스로 "프런티어 (Frontier) 에이전트 기능은 새로운 API로 집약될 것"이라고 명시했으므로, 구형 API에 머무는 선택은 기능 면에서 점차 불리해질 것이다. 당장 전면적인 전환을 강요받는 것은 아니지만, 새로 작성할 코드의 기본값을 어디에 둘지는 지금 결정해 둘 가치가 있다.