Interactions API Gemini 모델 및 에이전트: 2026년 마이그레이션 가이드

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

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

Interactions API Gemini 모델 및 에이전트 출시의 의미는, 당신이 2024년에 배우느라 시간을 보낸 모든 오케스트레이션 프레임워크(orchestration framework) — LangGraph, AutoGen, CrewAI — 가 Google이 방금 네이티브로 출시한 누락된 기본 요소(primitive)를 대신하기 위한 임시방편(workaround)이었다는 것입니다. Interactions API는 당신의 에이전트 스택(agent stack)과 경쟁하는 것이 아니라, 당신이 스택을 구축해야 했던 이유 자체를 무효화합니다.

Interactions API는 이제 Gemini 모델 및 에이전트를 위한 Google의 주요(primary) 인터페이스로서 일반적으로 사용 가능(Generally Available)해졌습니다. 이는 서버 측 상태(server-side state), 백그라운드 실행(background execution), 관리형 에이전트(Managed Agents) 및 도구 조합(tool combination)을 갖춘 하나의 통합된 엔드포인트(endpoint)입니다. 이는 당신이 파이프라인을 구축할 때 사용했던 파편화된 GenerativeModel 및 GenerateContent 인터페이스를 대체합니다.

이 글을 읽고 나면 Gemini 모델 및 에이전트를 위한 Interactions API에서 정확히 무엇이 바뀌었는지, 어떻게 마이그레이션(migrate)하는지, 비용은 얼마인지, 그리고 지금 즉시 운영 중인 에이전트를 옮길지 아니면 기다릴지에 대해 알게 될 것입니다. 미리 준비하고 싶다면, 우리의 AI 에이전트 라이브러리에는 이미 이 엔드포인트에 최적화된 패턴이 포함되어 있습니다.

Interactions API가 Gemini 모델 및 에이전트를 위한 주요 인터페이스로서 일반 사용 가능(general availability) 단계에 도달했음을 알리는 Google의 공식 발표 그래픽. 출처

Coined Framework

상태 유지형 중력 이동 (The Stateful Gravity Shift) — 클라우드 AI 제공업체가 오케스트레이션 계층 (orchestration layer)을 자체 관리형 인프라로 흡수하여, 멀티 턴 상태 (multi-turn state), 도구 라우팅 (tool routing), 백그라운드 작업 실행 (background task execution)을 부가적인 기능이 아닌 일급 기본 요소 (first-class primitive)로 만듦으로써 개발자들을 LangGraph, AutoGen, CrewAI와 같은 제3자 프레임워크로부터 끌어당기는 순간

이는 당신이 직접 조립하기 위해 사용했던 배관 (plumbing) 작업이 관리형 클라우드 기능이 되는 구조적 순간을 일컫습니다. 일단 상태 (state), 도구 라우팅 (tool routing), 비동기 실행 (async execution)이 단일 엔드포인트 (endpoint) 뒤에서 작동하게 되면, 플랫폼의 중력은 제3자 오케스트레이션 (orchestration)을 필수 요소가 아닌 선택 사항으로 만듭니다.

Google의 발표 내용: Interactions API 공식 출시

이 기사는 blog.google의 중대한 발표로 인해 작성되었습니다. 미사여구 없이 정확한 사실만을 전달합니다.

정확한 발표 날짜, 출처 및 GA 상태

발표 당일, Google은 Interactions API가 일반 가용성 (general availability, GA) 단계에 도달했으며, 이제 Gemini 모델 및 에이전트와 상호작용하기 위한 주요 API라고 선언했습니다. 공식 게시물에 따르면: '오늘 우리는 Interactions API가 일반 가용성 (general availability) 단계에 도달했으며, 이제 Gemini 모델 및 에이전트와 상호작용하기 위한 우리의 주요 API임을 발표합니다.' 퍼블릭 베타 (public beta)는 2025년 12월에 시작되었으며, Google에 따르면 이는 'Gemini를 사용하여 애플리케이션을 구축하는 개발자들에게 빠르게 가장 선호되는 방식이 되었습니다.'

저자들은 다음과 같이 명시되어 있습니다: Google DeepMind의 그룹 제품 매니저 (Group Product Manager)인 Ali Çevik, 그리고 Google DeepMind의 개발자 관계 엔지니어 (Developer Relations Engineer)인 Philipp Schmid.

이전 Gemini API 인터페이스에서 변경된 점

GA 출시와 함께 다음 세 가지 사항이 동시에 실현되었으며, 이는 모두 출처 텍스트에서 확인되었습니다:

• 이제 API에 **안정적인 스키마 (stable schema)**가 도입되었습니다. 이는 Google이 이 인터페이스에 대해 처음으로 약속한 스키마 보장입니다. 베타 버전에서 문서화되지 않은 객체 형태 (object-shape)의 변동으로 인해 어려움을 겪었던 초기 도입자들은 이 문장이 왜 중요한지 정확히 알고 있습니다.

• 이와 함께 주요 새로운 기능들이 출시되었습니다: Managed Agents (관리형 에이전트), 백그라운드 실행 (background execution), 그리고 **Gemini Omni (곧 출시 예정)**입니다.

• '이제 우리의 모든 문서는 Interactions API를 기본값으로 합니다'라고 명시되어 있으며, Google은 '제3자(3P) SDK 및 라이브러리 전반에서 이를 기본 인터페이스로 만들기 위해 생태계 파트너들과 협력하고 있습니다.'

Google DeepMind의 공식 인용구 및 포지셔닝

Google의 포지셔닝은 직설적입니다: '모델을 호출하든 에이전트를 실행하든, Interactions API를 사용하면 단 몇 줄의 코드로 이를 수행할 수 있습니다. 추론(inference)을 위해서는 모델 ID를, 자율적인 작업을 위해서는 에이전트 ID를 전달하고, 오래 걸리는 모든 작업에는 background=True를 설정하십시오.' 이것은 마케팅 문구가 아닙니다. 이는 아키텍처에 대한 선언입니다. 이것이 어디에 위치하는지에 대한 더 넓은 맥락을 보려면, Gemini 3 개발자 생태계에 대한 개요를 참조하십시오.

전체 발표 내용 중 가장 중대한 단 한 줄은 마케팅이 아닌 운영 측면의 내용입니다: 오래 걸리는 모든 작업에는 background=True를 설정하십시오. 이 단 하나의 불리언(boolean) 값이 수천 개의 팀이 에이전트 워크로드(agentic workloads)를 위해 직접 구축했던 지속 연결(persistent-connection) 배관 작업을 대체합니다.

2025년 12월
Interactions API 퍼블릭 베타 출시
[Google, 2026](https://blog.google/innovation-and-ai/technology/developers-tools/interactions-api-general-availability/)
...

Interactions API란 무엇인가? 쉬운 언어로 정의하기

전문 용어를 걷어내고 설명하자면: 이는 Gemini로 무엇이든 하기 위해 호출하는 단일 웹 주소입니다. 간단한 질문을 던지거나, 긴 다단계 작업을 실행하거나, 자율 에이전트에게 작업을 넘길 수 있습니다. 기존 방식과의 차이점은 인터페이스가 아닙니다. 메모리(memory)가 어디에 저장되느냐의 차이입니다.

단일 통합 엔드포인트(single unified endpoint) 개념 설명

이전에는 작업에 따라 여러 가지 서로 다른 인터페이스(surfaces) 중 하나를 선택해야 했습니다. 이제는 하나로 통합되었습니다. Google에 따르면, '서버 측 상태(server-side state), 백그라운드 실행(background execution), 도구 결합(tool combination) 및 멀티모달 생성(multimodal generation) 기능을 갖춘 Gemini 모델 및 에이전트를 위한 단일 통합 엔드포인트(single unified endpoint)'가 제공됩니다. 추론(inference)을 위해 모델 ID를 전달하느냐, 자율 작업(autonomous tasks)을 위해 에이전트 ID를 전달하느냐의 차이일 뿐이며, 동일한 엔드포인트를 사용하고 파라미터만 다르게 설정하면 됩니다. 그게 전부입니다. 너무 깔끔하게 들릴 수도 있겠지만, 실제로 그렇게 출시되었습니다.

기존 GenerativeModel 및 GenerateContent API와의 차이점

기존의 GenerativeModel, ChatSession, 그리고 GenerateContent 인터페이스는 근본적으로 상태 비저장(stateless) 및 호출당 응답(response-per-call) 방식이었습니다. 귀하의 애플리케이션이 전체 대화 기록을 보유하고 매 턴마다 이를 다시 전송해야 했으며, 세션이 길어질수록 토큰 비용이 조용히 급증했습니다. Interactions API는 **서버 측 세션 상태(server-side session state)**를 도입합니다. 즉, 귀하의 앱 레이어가 아닌 Google의 클라우드가 컨텍스트(context)를 보유합니다. 이는 OpenAI가 2023년 Assistants API를 통해 이루었던 것과 동일한 아키텍처적 도약이며, 단지 시기적으로 늦게 도착했을 뿐입니다. 저희는 AI 에이전트를 위한 서버 측 상태(server-side state for AI agents) 가이드에서 이러한 트레이드오프(tradeoffs)를 자세히 분석합니다.

상태 비저장(Stateless) API는 모든 개발자가 의도치 않게 대화 기록을 위한 데이터베이스 엔지니어가 되도록 강요했습니다. 서버 측 상태는 이러한 비용(tax)을 끝내는 동시에, 조용히 플랫폼에 귀하의 컨텍스트에 대한 열쇠를 넘겨줍니다.

광범위한 Google AI 및 Vertex AI 스택에서의 위치

Interactions API는 소비자용 API인 Google AI for Developers와 기업용인 Vertex AI 모두에서 Gemini 3 Pro 및 후속 모델을 위한 관문 역할을 합니다. 이 API는 로우 모델(raw model) 위와 귀하의 애플리케이션 아래에 위치하며, 이는 정확히 LangGraph와 CrewAI가 차지하고 있던 자리입니다. 이러한 위치 선정은 우연이 아닙니다.

상태가 없는 호출당 응답 (stateless response-per-call) 모델에서 상태가 있는 서버 측 세션 (stateful server-side session)으로의 아키텍처 변화 — 이것이 바로 '상태 중심의 중력 변화 (Stateful Gravity Shift)'의 기술적 핵심입니다.

조어된 프레임워크 (Coined Framework)

상태 중심의 중력 변화 (The Stateful Gravity Shift)

클라우드 제공업체가 상태 (state)를 일급 기본 요소 (first-class primitive)로 만들 때, 오직 그 상태를 관리하기 위해서만 존재했던 오케스트레이션 라이브러리 (orchestration libraries)들은 인프라로서 존재해야 할 이유를 잃게 됩니다. 이들은 플랫폼의 중력장 (gravity well) 위에서 커스터마이징 레이어 (customization layers)로 재포지셔닝함으로써만 생존할 수 있습니다.

전체 기능 분석: Interactions API가 실제로 수행하는 작업

다음은 발표문과 광범위한 Gemini 개발자 환경을 바탕으로 이 API가 수행하는 모든 기능입니다. 세부 사항에서 문제가 될 수 있는 부분(the devil is in the details)에는 별도로 표시하겠습니다.

서버 측 상태 및 멀티 턴 세션 관리 (Server-side state and multi-turn session management)

대화 문맥 (Conversation context)이 턴 (turns)을 거쳐 Google의 서버에 유지됩니다. 이제 매 호출마다 전체 이력을 다시 보낼 필요 없이 세션 (session)을 참조하면 됩니다. 이를 통해 페이로드 크기 (payload size)를 줄이고, 지연 시간 (latency)을 단축하며, 클라이언트가 긴 이력을 보유함으로써 발생하던 조용한 토큰 비용 팽창 (token-cost bloat)을 제거할 수 있습니다. 이는 대규모 멀티 턴 애플리케이션을 운영하는 팀들이 이미 청구서에서 목격하고 있던 문제였습니다.

백그라운드 실행 및 비동기 작업 처리 (Background execution and async task handling)

Google에 따르면: '모든 호출에 대해 background=True를 설정하십시오. 서버는 상호작용을 비동기적 (asynchronously)으로 실행합니다.' 이는 실제 운영 환경의 고충을 해결해 줍니다. 실행 시간이 긴 에이전트 워크플로 (agentic workflows)는 더 이상 지속적인 클라이언트 연결을 필요로 하지 않습니다. 노트북을 닫거나, 서버리스 함수 (serverless function)가 타임아웃되거나, 모바일 앱이 백그라운드로 전환되어도 작업은 중단되지 않습니다. 저는 팀들이 정확히 이런 종류의 하트비트 인프라 (heartbeat infrastructure)를 구축하느라 2주를 허비하는 것을 보아왔습니다. 이제 이것은 하나의 파라미터 (parameter)일 뿐입니다.

관리형 에이전트 (Managed Agents): 정의 및 실행 방식

이것이 핵심적인 기능입니다. 발표 내용에 따르면: '단 한 번의 API 호출로 에이전트가 추론(reasoning), 코드 실행, 웹 브라우징 및 파일 관리를 수행할 수 있는 원격 Linux 샌드박스 (sandbox)를 프로비저닝(provisioning)합니다. Antigravity 에이전트가 기본값으로 제공되며, 지침(instructions), 기술(skills) 및 데이터 소스(data sources)를 사용하여 사용자 정의 에이전트를 직접 정의할 수 있습니다.' 만약 검증된 템플릿부터 시작하고 싶다면, 처음부터 프로비저닝하는 대신 프로덕션 준비 완료 에이전트 템플릿을 살펴보세요.

한 번의 API 호출 = 코드 실행, 웹 브라우징 및 파일 관리가 가능한 원격 Linux 샌드박스. 대부분의 팀이 Kubernetes, Docker 및 보안 검토를 통해 프로비저닝했던 인프라가 이제는 하나의 파라미터 (parameter)일 뿐입니다. 이것이 바로 '상태 유지 중력 이동 (Stateful Gravity Shift)'이 실현된 모습입니다.

도구 조합, 함수 호출 (function calling), 그리고 MCP 통합

Google에 따르면, 단일 호출 내에서 '내장된 도구 (built-in tools)를 혼합'할 수 있습니다. 함수 호출 (function calling), RAG 검색 (retrieval), 그리고 외부 API가 하나의 Interactions API 호출 내에서 오케스트레이션 (orchestration)됩니다. 별도의 외부 미들웨어 (middleware)가 필요하지 않습니다. 또한 이 API는 MCP (Model Context Protocol) 도구 호출을 지원하여, 독점적인 스키마 (schema)에 사용자를 가두는 대신 성장하는 오픈 도구 생태계에 연결됩니다. 이 MCP 지원은 들리는 것보다 더 중요합니다. 이는 도구 생태계가 성숙해짐에 따라 이 엔드포인트 (endpoint)가 구성 가능성 (composability)을 유지하는 방식이기 때문입니다. 당사의 MCP 통합 가이드에서 상세한 연결 방법을 다룹니다.

멀티모달 (Multimodal) 입력 지원: 텍스트, 이미지, 오디오, 비디오

텍스트, 이미지, 오디오 및 비디오 입력이 동일한 엔드포인트를 통해 네이티브하게 흐르며, Gemini Omni는 '곧 지원 예정'으로 표시되어 있습니다. 이는 텍스트 우선 방식인 경쟁사 API 대비 구조적인 이점이며, 단순한 마케팅 문구가 아닙니다. 아키텍처 (architecture) 자체가 기능을 나중에 덧붙이는 방식이 아니라 진정으로 이를 처리하도록 설계되었습니다.

새로운 Gemini 3 파라미터: 지연 시간 (latency), 비용, 그리고 멀티모달 충실도 (fidelity) 제어

Gemini 3는 명시적인 '사고 수준 (level of thinking)' 제어 기능을 도입했습니다. 이는 실제로 조절 가능한 지연 시간(latency)-비용(cost) 간의 직접적인 트레이드오프(tradeoff) 다이얼과 같습니다. 어려운 추론(reasoning) 작업에는 더 많은 컴퓨팅 자원을 할당하고, 사소한 작업에는 더 적게 할당할 수 있습니다. GPT-4o나 Claude 3.5 Sonnet 모두 각자의 출시 시점에 이러한 종류의 제어 기능을 공개하지 않았으므로, 다른 모델들이 따라잡기 전까지는 진정한 차별화 요소로 취급할 가치가 있습니다. 기반이 되는 추론 모델에 대한 자세한 내용은 Google DeepMind의 Gemini 문서에서 확인할 수 있습니다.

단일 Interactions API 호출이 관리형 에이전트(Managed Agent)를 실행하는 방식

  1

    **클라이언트가 Interactions 엔드포인트로 하나의 POST 요청을 보냄**

페이로드(Payload)에는 에이전트 ID (예: Antigravity), 작업 프롬프트(task prompt), 그리고 background=True가 포함됩니다. 히스토리를 다시 보낼 필요는 없습니다. 세션 ID(session ID)가 컨텍스트(context)를 전달하기 때문입니다.

↓

  2
...