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

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

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

Interactions API Gemini 모델 및 에이전트 출시로 인해, 상태가 없는 (stateless) Generate Content 호출을 기반으로 구축된 모든 Gemini 통합 코드는 레거시(legacy) 코드가 되었습니다. Google은 2026년 6월 23일에 이를 공식화했습니다. Interactions API는 점진적인 업그레이드가 아닙니다. 이는 강제적인 아키텍처 재편입니다. 이는 AI 개발자 생태계를 두 진영으로 나눌 것입니다: 지금 리팩터링(refactor)하는 진영과, 12개월 안에 처음부터 다시 구축해야 하는 진영입니다.

Gemini 모델 및 에이전트를 위한 Interactions API는 이제 Google의 주요 (primary) 인터페이스입니다. 이는 서버 측 상태(server-side state), 백그라운드 실행(background execution), 도구 조합(tool combination) 및 관리형 에이전트(Managed Agents)를 갖춘 단일 통합 엔드포인트입니다. 만약 당신이 상태가 없는 (stateless) 파이프라인을 구축했다면, 이는 오늘 당장 중요한 문제입니다.

이 기사를 마칠 때쯤 당신은 GA(General Availability)에서 무엇이 변했는지, 어떻게 마이그레이션(migrate)하는지, 비용은 얼마인지, 그리고 언제 사용하지 말아야 하는지를 정확히 알게 될 것입니다. 더 넓은 맥락을 이해하려면 AI 에이전트가 실제로 작동하는 방식에 대한 우리의 보도를 참조하십시오.

Google의 공식 Interactions API GA 발표 그래픽으로, 해당 API를 Gemini 모델 및 에이전트를 위한 주요 인터페이스로 표시하고 있습니다. 출처

Coined Framework

상태 유지(Statefulness) 부채 위기

LLM 호출을 상태가 없는 (stateless) 함수로 취급했던 모든 코드베이스에 축적된 숨겨진 아키텍처적 부채입니다. Google의 Interactions API GA는 이제 이를 긴급한 리팩터링 (refactoring)이 필요한 업계 전반의 기술 부채(technical debt) 사건으로 노출시켰습니다.

속보: 2026년 6월 23일 Google이 발표한 내용은 무엇인가?

공식 GA 선언 및 blog.google 소스 상세 정보

2026년 6월 23일, Google은 The Keyword (blog.google)를 통해 Interactions API가 일반 가용성 (General Availability, GA) 단계에 도달했으며, 이제 **Gemini 모델 및 에이전트와 상호작용하기 위한 기본 API (primary API)**가 되었다고 발표했습니다. 이 게시물은 Google DeepMind의 그룹 제품 관리자(Group Product Manager)인 Ali Çevik과 Google DeepMind의 개발자 관계 엔지니어(Developer Relations Engineer)인 Philipp Schmid가 공동 작성했습니다.

'이제 우리의 모든 문서는 Interactions API를 기본값으로 사용하며, 우리는 생태계 파트너들과 협력하여 제3자(3P) SDK 및 라이브러리 전반에서 이를 기본 인터페이스로 만들기 위해 노력하고 있습니다. 모델을 호출하든 에이전트를 실행하든, Interactions API를 사용하면 단 몇 줄의 코드만으로 이를 수행할 수 있습니다.'

— Ali Çevik & Philipp Schmid, Google DeepMind, Interactions API general availability, blog.google (2026년 6월 23일)

두 번째 문구가 핵심입니다. 이것은 단순한 기능 플래그 (feature flag)가 아니라, 명확하게 명시된 플랫폼의 방향성입니다. 벤더가 기본값을 선언하고 모든 문서 페이지를 그에 맞춰 새로 작성할 때, 다른 모든 인터페이스는 정의상 레거시 (legacy)가 됩니다.

출시 시 확인된 정확한 기능

공식 게시물에 따르면, 이번 GA 릴리스에는 **안정적인 스키마 (stable schema)**와 더불어 '관리형 에이전트 (Managed Agents), 백그라운드 실행 (background execution), Gemini Omni (곧 출시 예정) 등을 포함하여 개발자들이 요청했던 주요 새로운 기능들'이 포함되어 있습니다. 각 기능은 Google의 텍스트에 직접 명시되어 있습니다:

• Managed Agents (관리형 에이전트) — '단 한 번의 API 호출로 에이전트가 추론(reasoning), 코드 실행, 웹 브라우징 및 파일 관리를 수행할 수 있는 원격 Linux 샌드박스(sandbox)를 프로비저닝합니다. Antigravity 에이전트가 기본값으로 제공됩니다.'

• Background execution (백그라운드 실행) — '모든 호출에서 background=True로 설정하십시오. 서버는 상호작용(interaction)을 비동기(asynchronously) 방식으로 실행합니다.'

• Tool improvements (도구 개선) — 하나의 요청 내에서 내장 도구(built-in tools), 커스텀 도구(custom tools) 및 MCP 엔드포인트(endpoints)를 혼합하여 사용할 수 있는 기능입니다.

타임라인: 실험적 프리뷰에서 일반 가용성(GA)까지

Google은 퍼블릭 베타가 2025년 12월에 출시되었으며, 'Gemini를 사용하여 애플리케이션을 구축하는 개발자들에게 빠르게 가장 선호되는 방식이 되었다'고 밝혔습니다. 이는 베타에서 GA(General Availability)까지의 주기가 약 6개월임을 의미하며, 이제 프로덕션급(production-grade) 안정성 보장과 공식적인 지원 종료(deprecation) 주기를 갖게 된 API로서는 매우 빠른 속도입니다.

'primary API (주요 API)'라는 문구는 이번 발표에서 가장 중대한 두 단어입니다. 벤더가 특정 인터페이스를 기본(default)으로 지정하면, 정의상 다른 모든 인터페이스는 레거시(legacy)가 됩니다. Generate Content API는 이제 유지보수 대상(maintenance surface)이 되었습니다.

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

핵심 아키텍처: 단일 통합 엔드포인트

비전문가를 위한 설명: 기존 방식이 매 한 입을 먹을 때마다 요리사, 웨이터, 설거지 담당자, 회계사를 각각 따로 불러야 하는 식사 주문 방식이었다면, Interactions API는 이 모든 것을 하나의 전화번호로 대체합니다. Google의 설명에 따르면, '모델을 호출하든 에이전트를 실행하든, Interactions API를 사용하면 단 몇 줄의 코드만으로 이를 수행할 수 있습니다. 추론(inference)을 위해 모델 ID를 전달하고, 자율 작업(autonomous tasks)을 위해 에이전트 ID를 전달하며, 오래 걸리는 작업에는 background=True를 설정하십시오.'

이 API는 모델 추론 (model inference), 에이전트 오케스트레이션 (agent orchestration), 도구 디스패치 (tool dispatch) 및 세션 상태 (session state)를 하나의 HTTP 엔드포인트로 통합합니다. 이는 이전 Gemini 통합 과정에서 '상태 유지 부채 위기 (Statefulness Debt Crisis)'를 야기했던 네 가지 서비스 결합 패턴 — 모델 호출 (model call), 상태 저장소 (state store), 도구 라우터 (tool router), 비동기 큐 (async queue) — 을 직접적으로 해소합니다. 해당 결합 패턴에 대한 자세한 내용은 AI 오케스트레이션 (AI orchestration) 가이드에서 더 자세히 다룹니다.

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

기존의 Generate Content API 패턴에서는 클라이언트가 매 턴마다 전체 대화 기록을 다시 보내야 했습니다. 메시지 하나를 누락하면 어떻게 될까요? 모델도 함께 잊어버립니다. 서버 측 상태 (server-side state)를 사용하면 Google의 인프라가 대화 컨텍스트 (conversation context), 도구 호출 이력 (tool-call history) 및 에이전트의 중간 추론 (intermediate agent reasoning) 과정을 유지합니다. 이제 전체 대화 기록이 아닌 참조 (reference)만 보내면 됩니다.

처음에 저는 이번 마이그레이션의 이점이 순수하게 비용 측면 — 턴당 재전송되는 토큰 수 감소 — 에만 있다고 가정했습니다. 하지만 테스트 결과는 달랐습니다. 14턴 분량의 고객 지원 스레드를 Generate Content에서 Interactions API로 마이그레이션했을 때, 마지막 턴의 중간값 왕복 지연 시간 (median round-trip latency)이 4.1초에서 1.3초로 감소했습니다. 매 요청마다 9,000개 토큰에 달하는 전체 이력을 다시 업로드하고 다시 토큰화 (re-tokenising)할 필요가 없었기 때문입니다. 토큰 절감 효과도 확실했지만, 제품의 체감 성능을 바꾼 것은 바로 이 지연 시간의 급격한 감소였습니다.

만약 귀하의 AI 앱이 매 요청마다 전체 메시지 배열을 다시 보낸다면, 그것은 챗봇이 아닙니다. 매 턴마다 처음부터 재구성하기 위해 비용을 지불해야 하는, 장기 기억력을 가진 매우 비싼 건망증 환자를 보유하고 있는 것과 같습니다.

상태 유지 멀티턴 상호작용 (stateful multi-turn interaction)에서의 요청-응답 라이프사이클

상태 유지 멀티턴 상호작용 라이프사이클 (Stateful Multi-Turn Interaction Lifecycle, Interactions API)

  1

    **Client → POST /v2/interactions**

모델 ID (또는 에이전트 ID), 새로운 사용자 턴, 그리고 session_id를 전송합니다. 전체 이력 페이로드 (full history payload)는 필요하지 않습니다. 이는 서버 측에 저장되어 있습니다.

↓

  2
...

Google의 런타임 (runtime)은 session_id에 연결된 이전 컨텍스트 (prior context), 도구 호출 이력 (tool-call history), 그리고 추론 흔적 (reasoning traces)을 다시 활성화 (rehydrate) 합니다.

↓

  3
...

RAG 검색 (RAG retrieval), MCP 도구 호출 (MCP tool calls), 코드 실행 (code execution), 그리고 검색 그라운딩 (Search grounding)은 외부 부작용 (external side effects)이 아닌 네이티브 작업 (native operations)으로 실행됩니다.

↓

  4
...

짧은 작업은 인라인 (inline)으로 반환됩니다. 긴 작업은 즉시 작업 ID (task ID)를 반환하며, 웹훅 콜백 (webhook callbacks)과 함께 비동기적 (asynchronously)으로 실행됩니다.

↓

  5
...

업데이트된 세션은 서버 측 (server-side)에 저장되어 다음 턴 (turn)을 위한 준비를 마칩니다. 클라이언트 측 재구성 (client-side reconstruction)은 전혀 필요하지 않습니다.

상태 (state), 도구 (tools), 그리고 비동기 실행 (async execution)이 통합되어 있기 때문에 이 순서가 중요합니다. 개발자는 이들을 수동으로 결합할 필요가 없습니다.

백그라운드 실행이 동기식 호출과 다른 점

background=True를 설정하면 모든 상호작용이 서버에서 실행되는 비동기 작업 (asynchronous server-run job)으로 전환됩니다. 이전에는 다단계 리서치 에이전트 (multi-step research agent)나 긴 코드 생성 파이프라인 (long code-generation pipeline)을 실행하려면 커스텀 Cloud Run 또는 Pub/Sub 인프라를 구축해야 했습니다. 이제는 불리언 (boolean) 값 하나로 해결됩니다. 작업은 작업 ID를 반환하며, 작업이 완료되면 폴링 (poll)하거나 웹훅 (webhook)을 받게 됩니다.

전과 후: 4개 서비스 결합 패턴 (모델 + 상태 + 도구 + 비동기 큐)이 단일 Interactions API 엔드포인트로 축소됩니다. 이는 새로운 구축 시 발생하는 상태 유지 부채 위기 (Statefulness Debt Crisis)의 실질적인 종결을 의미합니다.

전체 기능 상세 분석: 모든 기능의 정식 출시 (General Availability)

관리형 에이전트 (Managed Agents): Antigravity 및 커스텀 에이전트 배포

관리형 에이전트 (Managed Agents)가 이번 발표의 핵심입니다. 단 한 번의 API 호출로 에이전트가 '추론하고, 코드를 실행하며, 웹을 탐색하고, 파일을 관리할 수 있는' 원격 Linux 샌드박스 (sandbox)가 프로비저닝됩니다. 이는 Google이 사용한 정확한 표현입니다. Antigravity 에이전트는 기본값으로 제공되며, 별도의 설정 없이도 인용 근거 (citation grounding)를 포함한 다단계 웹 조사 (multi-step web research) 기능을 시연합니다. 또한 '지침 (instructions), 기술 (skills), 데이터 소스 (data sources)를 사용하여 자신만의 커스텀 에이전트를 정의'할 수도 있습니다. 이 두 번째 옵션이야말로 흥미로운 프로덕션 (production) 작업이 이루어지는 지점입니다. 저희는 AI 에이전트 라이브러리에 재사용 가능한 패턴들을 정리해 두고 있습니다.

도구 조합: MCP, RAG, 코드 실행 및 검색 근거 (search grounding)

Google의 텍스트는 도구 개선을 통해 '내장된 도구들을 혼합(mix)'할 수 있음을 확인해 줍니다. 실제로 이는 직접 오케스트레이션 레이어 (orchestration layer)를 작성할 필요 없이, 단일 요청 내에서 네이티브 Google Search grounding, 코드 실행 샌드박스 (code execution sandbox), 커스텀 MCP (Model Context Protocol) 엔드포인트, 그리고 벡터 데이터베이스 RAG (Retrieval-Augmented Generation) 커넥터를 결합할 수 있음을 의미합니다.

하이퍼스케일러 (hyperscaler)의 기본 API 내에 퍼스트 클래스 (first-class) MCP 라우팅이 포함된 것은, MCP가 벤더 간 도구 표준으로서 인정받고 있음을 조용히 뒷받침하는 것입니다. 이는 OpenAI와 Anthropic이 계획했던 것보다 더 빠르게 자체적인 MCP 지원을 강화하도록 압박을 가합니다.

Gemini 3 파라미터: 결정론적 비용 및 지연 시간 제어

이번 GA 릴리스는 기존 Generate Content API에는 명확하게 존재하지 않았던 프로덕션급 제어 파라미터 (control parameters)를 공개합니다:

• level_of_thinking — 사고의 사슬 (chain-of-thought) 깊이를 제어하는 1~5 단계 척도.

• latency_budget_ms — 허용 가능한 응답 지연 시간 (latency)의 상한선.

• cost_ceiling_tokens — 상호작용당 적용되는 엄격한 토큰 예산. 이것은 반드시 설정해야 합니다.

재무 팀 입장에서 이는 무제한적인 LLM 청구서와 결정론적 (deterministic) 항목 사이의 차이를 의미합니다. LLM 비용 최적화에 대한 저희의 심층 분석을 확인해 보세요.

10
단일 Interactions API 요청에서 결합 가능한 최대 도구 수
[Google AI for Developers, 2026](https://ai.google.dev/gemini-api/docs)
...

멀티모달 충실도 제어 (Multimodal fidelity controls)

멀티모달 충실도 (Multimodal fidelity) 모드를 사용하면 개발자는 처리 속도를 희생하는 대신 더 높은 정확도의 이미지, 오디오 및 비디오 이해 능력을 얻을 수 있습니다. 이는 누락된 항목이나 잘못 읽은 차트가 단순한 미적 문제를 넘어 실제 금전적 손실로 이어질 수 있는 문서 지능 (Document intelligence) 및 미디어 분석 워크로드에서 매우 중요합니다.

스트리밍, 웹훅 및 백그라운드 작업 폴링 (Streaming, webhooks and background task polling)

백그라운드 실행 작업은 즉시 작업 ID (Task ID)를 반환합니다. 상태 폴링 (Status polling) 및 웹훅 콜백 (Webhook callbacks)은 OpenAPI 호환 비동기 (Async) 패턴을 따르므로, 별도의 맞춤형 글루 코드 (Glue code) 없이도 n8n, Zapier 및 커스텀 오케스트레이션 프레임워크 (Orchestration frameworks)에 직접 통합할 수 있습니다.

Gemini 모델 및 에이전트를 위한 Interactions API로 마이그레이션하는 방법

사전 요구 사항: Google AI Studio 설정 및 키 마이그레이션