Interactions API Gemini 모델 및 에이전트: 완전한 GA 가이드

원래 twarx.com에서 게시되었습니다 - 전체 대화형 버전은 그곳에서 읽어보세요.

최종 업데이트: 2026년 6월 24일

Gemini 모델 및 에이전트를 위한 Interactions API는 LangGraph, CrewAI, 그리고 모든 무상태(stateless) Generate Content API 호출을 구조적으로 구식으로 만들었습니다. 그리고 현재 Gemini를 기반으로 구축 중인 대부분의 엔지니어링 팀은 마이그레이션 마감 기한이 이미 지났다는 사실을 아직 깨닫지 못하고 있습니다.

2026년 6월 23일에 Gemini 모델 및 에이전트를 위한 Interactions API가 일반 가용성(General Availability, GA)에 도달한 것은 단순한 제품 업데이트가 아닙니다. 이는 프롬프트(prompt)부터 지속적인 상태(persistent state), 그리고 프로덕션 배포(production deployment)에 이르기까지 전체 에이전트 스택(agentic stack)을 소유하기 위한 전투의 첫 번째 움직임입니다. 추론(Inference), 에이전트(agents), 서버 측 상태(server-side state), 백그라운드 실행(background execution), 그리고 멀티모달 생성(multimodal generation): 단 하나의 엔드포인트(endpoint). 그것이 전부입니다.

이 글을 마칠 때쯤 여러분은 무엇이 변했는지, 어떻게 마이그레이션해야 하는지, 비용은 얼마인지, 그리고 여러분의 오케스트레이션 프레임워크(orchestration framework)가 존재 이유를 상실했는지 여부를 정확히 알게 될 것입니다.

Google의 Interactions API 일반 가용성(General Availability) 도달에 대한 공식 발표 — Gemini 모델 및 에이전트를 위한 단일 통합 엔드포인트. 출처

Coined Framework

오케스트레이션 붕괴 계층 (The Orchestration Collapse Layer) — 클라우드 네이티브 AI API가 충분한 미들웨어(middleware) 기능을 흡수하여 독립적인 오케스트레이션 프레임워크가 주요 가치 제안을 상실하고, 모든 엔지니어링 팀이 플랫폼 충성도 결정을 강요받게 되는 구조적 순간

이는 상태 관리 (state management), 도구 실행 (tool execution), 그리고 백그라운드 실행 (background runs)이 여러분의 코드베이스에서 제공업체의 클라우드로 이동하는 정확한 시점을 지칭합니다. 일단 그런 일이 발생하면, 질문은 '어떤 프레임워크를 쓸 것인가?'에서 '우리 회사의 운명을 누구의 플랫폼에 걸 것인가?'로 바뀝니다.

Google의 발표 내용: Interactions API 정식 출시 (General Availability)

공식 발표 세부 사항 및 정확한 GA 날짜

2026년 6월 23일, Google은 the Keyword 블로그를 통해 Interactions API가 정식 출시(General Availability, GA)되었으며, 이제 Gemini 모델 및 에이전트와 상호작용하기 위한 주요 API가 되었다고 발표했습니다. 이 게시물은 Google DeepMind의 그룹 제품 매니저(Group Product Manager)인 Ali Çevik과 Google DeepMind의 개발자 관계 엔지니어(Developer Relations Engineer)인 Philipp Schmid가 작성했습니다. 홍보팀이 아닌, 실제로 제품을 출시하는 두 사람이 작성했다는 점은 신호를 정확하게 읽는 데 있어 매우 중요합니다.

이 API는 2025년 12월에 퍼블릭 베타(public beta)로 처음 출시되었습니다. Google은 이것이 'Gemini를 사용하여 애플리케이션을 구축하는 개발자들에게 빠르게 가장 선호되는 방식이 되었다'고 말합니다. 이제 모든 Google 문서의 기본값은 Interactions API로 설정되어 있으며, Google은 서드파티 SDK 및 라이브러리 전반에 걸쳐 이를 기본 인터페이스로 만들기 위해 생태계 파트너들과 적극적으로 협력하고 있습니다. 마지막 이 부분이 바로 제가 주목하고 있는 대목입니다.

프리뷰(preview)에서 정식 출시(general availability)로 변경된 사항

가장 결정적인 변화는 바로 **안정적인 스키마 (stable schema)**의 제공입니다. 2025년 12월 프리뷰(preview) 기간 동안, 스키마의 불안정성은 개발자들이 가장 많이 언급한 불만 사항이었습니다. 응답 구조(response structure)의 변경으로 인해 프로덕션 환경에서 지속적인 장애가 발생했기 때문입니다. 저는 이 문제 때문에 베타(beta) 단계를 아예 건너뛰는 팀들을 보기도 했습니다. GA(General Availability)는 요청/응답 계약(request/response contract)을 고정하며, 이는 새벽 2시에 조용한 역직렬화(deserialization) 실패를 디버깅하며 밤을 지새워보기 전까지는 지루하게 들릴 수도 있습니다. 안정적인 스키마와 더불어, Google은 개발자들이 요구해 온 기능들을 출시했습니다: Managed Agents (관리형 에이전트), 백그라운드 실행 (background execution), Gemini Omni (곧 출시 예정), 그리고 의미 있는 도구(tool) 개선 사항들입니다.

공식 출처 및 개발자 문서 링크

표준 참조 문서는 official blog.google announcement입니다. API는 Google AI Studio와 Vertex AI를 통해 액세스할 수 있습니다. Antigravity 에이전트가 기본 Managed Agent로 제공되며, 지침(instructions), 기술(skills), 데이터 소스(data sources)를 사용하여 커스텀 에이전트를 정의할 수 있습니다. 이 기능이 전체 맥락에서 어디에 위치하는지에 대한 더 넓은 정보는 our 2026 agentic AI stack overview를 참조하세요.

안정적인 스키마는 단순한 기능이 아닙니다. 그것은 매주 화요일마다 클라이언트를 다시 작성하는 일을 멈출 수 있게 해주는 계약입니다. GA 노트에 적힌 이 한 줄이, 이 변화가 그 어떤 새로운 모델 출시보다 더 중요한 이유입니다.

Dec 2025
Interactions API public beta launch
[Google, 2026](https://blog.google/innovation-and-ai/technology/developers-tools/interactions-api-general-availability/)
...

Interactions API란 무엇이며 어떻게 작동하는가

이 글을 읽고 계신 소상공인분들을 위해 설명하자면, Interactions API는 소프트웨어가 Google의 Gemini AI와 대화하는 새로운 방식입니다. 이전에는 다단계(multi-step) 작업을 구축하려면 세 가지 서로 다른 도구를 하나로 엮어야 했고, 모든 대화 기록을 직접 저장해야 했습니다. 이제는 문맥(context)을 기억하고, 백그라운드에서 긴 작업을 실행하며, 단일 메시지로 텍스트, 이미지, 오디오, 비디오 및 문서를 모두 수용하는 하나의 연결로 통합되었습니다. 이것이 아주 쉽게 설명한 버전입니다.

핵심 아키텍처 설계: 단일 통합 엔드포인트(single unified endpoint) 설명

Interactions API는 기존에 Generate Content, Function Calling, Streaming이라는 세 가지 별도의 API 인터페이스(API surfaces)로 나뉘어 있던 것을 일관된 요청/응답 스키마(request/response schema)를 가진 하나의 통합 엔드포인트로 압축합니다. 모델을 호출하든 에이전트(agent)를 실행하든, 단 몇 줄이면 충분합니다. 추론(inference)을 위해 model ID를 전달하고, 자율 작업(autonomous tasks)을 위해 agent ID를 설정하며, 오래 걸리는 작업에는 background=True를 설정하면 됩니다. 정말 그게 전부입니다. 이러한 통합은 단순히 겉모습만 바뀐 것이 아닙니다. 이는 하나의 인증 경로(auth path), 버전 고정(version-pin)을 위한 하나의 스키마, 그리고 변경 사항이 생겼을 때 업데이트해야 할 하나의 SDK 모듈을 의미합니다.

서버 측 상태 관리(Server-side state management) 대 클라이언트 측 세션 처리(client-side session handling)

이것은 아키텍처 측면에서의 지각 변동이며, 이것이 무엇을 의미하는지 직설적으로 말씀드리고 싶습니다. **서버 측 상태(Server-side state)**란 대화 기록, 도구 호출(tool call) 결과, 그리고 에이전트 메모리(agent memory)가 턴(turn) 사이의 간격 동안 Google의 인프라에 의해 유지됨을 의미합니다. 이제 세션 연속성만을 위해 컨텍스트 윈도우(context windows)를 수동으로 관리하거나 외부 벡터 데이터베이스(vector database)를 유지 관리할 필요가 없습니다. 대부분의 팀이 LangGraph 상태 머신(LangGraph state machines)으로 구축하는 스택의 해당 계층 전체가 제공업체의 클라우드로 이동합니다. 편리하죠. 또한 이는 해자(moat)이기도 합니다. 이 부분은 나중에 다시 다루겠습니다.

백그라운드 실행 모델(Background execution model) 및 비동기 에이전트 실행(async agent runs)

어떤 호출에서든 background=True를 설정하면 서버가 상호작용(interaction)을 비동기적으로 실행합니다. 완료 시 폴링(Poll)하거나 웹훅(webhook)을 수신하세요. 이는 OpenAI의 Responses API 백그라운드 모드와 아키텍처 측면에서 직접적으로 유사합니다. 즉, 실행 시간이 긴 에이전트 작업(agent tasks)을 위해 더 이상 HTTP 연결을 유지하거나 자체적인 작업 큐(job queue)를 구축할 필요가 없습니다. 다단계 에이전트 실행(multi-step agent runs)을 지원하기 위해 Redis 기반의 작업 큐를 유지 관리해 본 사람이라면, 이 기능이 얼마나 많은 수고(toil)를 덜어주는지 정확히 알 것입니다.

단일 API 호출 내의 멀티모달 입력 파이프라인 (Multimodal input pipeline)

텍스트, 이미지, 오디오, 비디오, 문서가 모두 하나의 요청 객체(request object)로 전달됩니다. 이전의 Generate Content API에서 요구되었던 별도의 미디어 업로드 전처리 단계가 사라졌습니다. 하나의 요청으로 모든 모달리티(modality)를 처리하며, 스키마(schema)가 내부적으로 라우팅을 처리합니다.

단일 Interactions API 호출이 Google 스택을 통해 흐르는 방식

  1

    **클라이언트 요청 (Client request)**

하나의 요청 객체를 전송합니다: 모델 ID(model ID) 또는 에이전트 ID(agent ID), 멀티모달 입력(텍스트/이미지/오디오/비디오/문서), 선택 사항인 session_id, 선택 사항인 background=True.

↓

  2
...

통합 엔드포인트(unified endpoint)가 순수 추론(pure inference, 모델 ID 사용)인지 자율 실행(autonomous run, 에이전트 ID 사용)인지 결정합니다. session_id가 있는 경우 서버 측 세션(server-side session)에서 상태(state)를 로드합니다.

↓

  3
...

원격 Linux 샌드박스(sandbox)가 실행되어 에이전트가 추론하고, 코드를 실행하며, Search Grounding을 통해 웹을 탐색하고, 파일을 관리합니다. 개발자의 컴퓨팅 자원은 전혀 소모되지 않습니다.

↓

  4
...

내장 도구(Search Grounding, Code Execution)가 외부 MCP 도구 서버(tool servers)와 결합됩니다. 별도의 커스텀 함수 호출(function-calling) 래퍼(wrapper)가 필요하지 않습니다.

↓

  5
...

업데이트된 메모리(memory)와 도구 결과가 session_id 아래 서버 측에 저장됩니다. 동기식 응답(Sync responses)은 스트리밍되며, 백그라운드 실행(background runs)은 폴링/웹훅을 위한 핸들(handle)을 반환합니다.

이 시퀀스가 중요한 이유는 기존에는 3~5단계가 여러분의 코드베이스에 존재했기 때문입니다. 이것이 바로 작동 중인 오케스트레이션 붕괴 계층(Orchestration Collapse Layer)입니다.

오케스트레이션 붕괴 계층(Orchestration Collapse Layer)의 전/후 비교: 한때 여러분의 LangGraph 또는 AutoGen 코드베이스에 존재했던 미들웨어(middleware)가 이제 Google의 관리형 클라우드 내부에서 실행됩니다.

서버 측 세션 ID(session_id)를 채택하는 순간, 대화 메모리(conversation memory)는 더 이상 이식 가능하지 않게 됩니다. 이것은 버그가 아니라, 전환 비용(switching-cost)이라는 해자(moat)입니다. 세션 상태(session state)의 소유권을 개발자의 편의가 아닌, 이사회 수준의 아키텍처 결정으로 취급하십시오.

전체 기능 상세 분석: Interactions API의 모든 기능

관리형 에이전트(Managed Agents): 클라우드 샌드박스 실행 및 Antigravity 에이전트

단 한 번의 API 호출로 에이전트가 추론(reasoning)하고, 코드를 실행하며, 웹을 탐색하고, 파일을 관리할 수 있는 **원격 리눅스 샌드박스(remote Linux sandbox)**를 프로비저닝합니다. Antigravity가 기본값으로 제공되며, 지침(instructions), 기술(skills), 데이터 소스(data sources)를 갖춘 커스텀 에이전트를 정의할 수 있습니다. 개발자가 관리하는 컴퓨팅 인프라는 필요하지 않습니다. 에이전트 실행 — 도구 호출(tool calls), 웹 검색, 코드 실행 — 은 전적으로 서버 측(server-side)에서 이루어집니다. 만약 비동기 에이전트 작업을 지원하기 위해 Celery 워커 풀(worker pool)을 유지 관리해 본 적이 있다면, 여기서 '인프라 제로(zero infrastructure)'가 실제로 무엇을 의미하는지 이해할 것입니다. 바로 적용 가능한 기성 패턴을 확인하려면 저희의 AI 에이전트 라이브러리를 찾아보세요.

도구 결합(Tool combination): 네이티브 검색 그라운딩(Search Grounding), 코드 실행(Code Execution) 및 MCP 통합

Interactions API는 Model Context Protocol (MCP)를 네이티브로 지원하여, 커스텀 함수 호출 (function-calling) 래퍼를 작성할 필요 없이 MCP 표준을 따르는 외부 도구 서버를 연결할 수 있습니다. **검색 그라운딩 (Search Grounding)**은 일급 도구 (first-class tool)로 제공됩니다. 이는 인용구가 포함된 실시간 웹 검색을 제공하여, Gemini 3 모델의 2025년 1월 지식 컷오프 (knowledge cutoff) 문제를 직접적으로 해결합니다. 내장된 도구들은 단일 호출 내에서 MCP 서버와 자유롭게 혼합되어 사용될 수 있습니다. 이러한 상호 운용성 (interoperability)은 단순히 기능 비교표의 체크박스를 채우기 위한 것이 아니라, 진정으로 유용한 기능입니다.

상태 유지형 멀티턴 상호작용 및 컨텍스트 지속성 (Stateful multi-turn interactions and context persistence)

서버 측 상태 (Server-side state)는 대화 기록, 도구 결과, 그리고 에이전트 메모리 (agent memory)를 턴(turn) 전반에 걸쳐 유지합니다. RAG 파이프라인 (RAG pipelines)을 구축하는 팀의 경우, 세션 수준의 검색 증강 (retrieval augmentation)을 별도의 벡터 데이터베이스 (vector database) 쿼리 루프를 가진 독립적인 오케스트레이션 서비스로 유지하는 대신 API 계층으로 오프로드 (offload)할 수 있습니다. 이러한 트레이드오프 (trade-off)가 가치가 있는지는 데이터 레지던시 (data residency) 요구 사항에 따라 달라지며, 이에 대한 자세한 내용은 아래에서 다룹니다.

스트리밍 응답 및 실시간 출력 처리 (Streaming responses and real-time output handling)

이전에는 별도의 API 인터페이스였던 스트리밍 (Streaming) 기능이 통합 엔드포인트 (unified endpoint)에 내장되었습니다. 실시간 토큰 출력과 백그라운드 비동기 실행 (background async runs)이 하나의 스키마 (schema) 아래에서 공존합니다. 통합 방식이 아닌 호출별로 전달 모델을 선택할 수 있습니다. 사소한 부분 같지만, 기존 방식보다 진정으로 덜 번거롭습니다.

RAG 통합 및 벡터 데이터베이스 호환성 (RAG integration and vector database compatibility)