Interactions API

Interactions API는 Gemini 모델 및 에이전트를 빌드하는 가장 간단한 방법이자 새로운 인터페이스입니다. 2026년 6월부터 정식 버전으로 제공되며 모든 신규 프로젝트에 권장되는 인터페이스입니다.

이제 기존 API로 간주되지만 원래 generateContent API 는 계속 완벽하게 지원됩니다.

Interactions API를 사용하는 이유는 무엇인가요?

  • 기본 제공되는 새로운 기능: previous_interaction_id를 사용하는 선택적 서버 측 대화 상태, 디버깅 및 UI 렌더링을 위한 관찰 가능한 실행 단계, 백그라운드 실행을 사용하는 장기 실행 작업의 백그라운드 실행background=true
  • 캐시 적중률이 높아 비용 절감: 서버 측 상태 관리 를 통해 턴 간에 더 효율적인 컨텍스트 캐싱이 가능하므로 멀티턴 대화의 토큰 비용이 절감됩니다.
  • 프런티어 모델 및 에이전트를 위해 빌드됨: 사고 모델, 다단계 도구 사용, 복잡한 추론 흐름을 위해 특별히 빌드되어 에이전트 애플리케이션의 빌드, 디버깅, 오케스트레이션 프로세스를 간소화합니다.
  • 모델 및 에이전트를 위한 단일 API: Deep Research 및 커스텀 관리형 에이전트와 같은 Gemini 모델 및 에이전트를 직접 호출하기 위한 통합 인터페이스로, 별도의 엔드포인트나 학습할 패턴이 없습니다.
  • 새로운 기능이 출시되는 곳: 향후 핵심 메인라인 제품군을 넘어서는 새로운 모델과 기능은 새로운 에이전트 기능 및 도구와 함께 Interactions API에서 출시될 예정입니다.

기본적으로 Interactions API는 요청을 저장하므로 previous_interaction_id를 사용하여 서버 측 상태 관리 기능을 활용할 수 있습니다. store=false를 설정하여 스테이트리스(Stateless) 동작을 선택할 수 있습니다. 자세한 내용은 데이터 보관 섹션을 참고하세요.

시작하기

  • 코딩 에이전트 설정: Gemini Docs MCP에 연결하고 gemini-interactions-api 스킬을 설치하여 어시스턴트가 최신 개발자 문서 및 권장사항에 직접 액세스할 수 있도록 합니다. 코딩 에이전트 설정하기 →
  • generateContent에서 이전: 기존 통합이 있는 경우 이전 가이드에 따라 Interactions API로 전환합니다.
  • 시작하기: Interactions API 시작하기 가이드에서 시작합니다.

기능 가이드

이 가이드를 통해 Interactions API의 특정 기능을 살펴보세요. 이 페이지의 전환 버튼을 사용하여 generateContent와 Interactions API 간에 전환할 수 있습니다.

Interactions API의 작동 방식

Interactions API는 핵심 리소스인 Interaction을 중심으로 합니다. Interaction은 대화 또는 작업의 완전한 턴을 나타냅니다. 실행 단계 의 시간순서대로 상호작용의 전체 기록을 포함하는 세션 기록 역할을 합니다. 이러한 단계에는 모델 생각, 서버 측 또는 클라이언트 측 도구 호출 및 결과 (function_call, function_result 등), 최종 model_output이 포함됩니다. 저장된 리소스 (interactions.get을 통해 검색됨)에는 전체 컨텍스트를 위한 user_input 단계도 포함되지만 interactions.create 응답은 모델에서 생성된 단계만 반환합니다.

interactions.create를 호출하면 새 Interaction 리소스가 생성됩니다.

서버 측 상태 관리

후속 호출에서 완료된 상호작용의 id을(를) 사용하여 대화를 계속하려면 previous_interaction_id 매개변수를 사용하면 됩니다. 서버는 이 ID를 사용하여 대화 기록을 검색하므로 전체 채팅 기록을 다시 전송할 필요가 없습니다.

previous_interaction_id 매개변수는 previous_interaction_id를 사용하여 대화 기록 (입력 및 출력)만 보존합니다. 다른 매개변수는 상호작용 범위 이며 현재 생성 중인 특정 상호작용에만 적용됩니다.

  • tools
  • system_instruction
  • thinking_level, temperature 등을 포함한 generation_config

즉, 이러한 매개변수를 적용하려면 각 새 상호작용에서 다시 지정해야 합니다. 이 서버 측 상태 관리는 선택사항입니다. 각 요청에서 전체 대화 기록을 전송하여 스테이트리스(Stateless) 모드로 작동할 수도 있습니다.

데이터 저장 및 보관

기본적으로 API는 서버 측 상태 관리 기능 (previous_interaction_id 사용), 백그라운드 실행 (background=true 사용), 모니터링 가능성 목적의 사용을 간소화하기 위해 모든 상호작용 객체 (store=true)를 저장합니다.

  • 유료 등급: 시스템은 상호작용을 55일 동안 보관합니다.
  • 무료 등급: 시스템은 상호작용을 1일 동안 보관합니다.

원하지 않는 경우 요청에서 store=false를 설정할 수 있습니다. 이 컨트롤은 상태 관리와 별개입니다. 모든 상호작용의 저장소를 선택 해제할 수 있습니다. 하지만 store=false는 백그라운드 실행과 호환되지 않으며 후속 턴에 previous_interaction_id를 사용하지 못하게 합니다.

API 참조에 있는 삭제 메서드를 사용하여 언제든지 저장된 상호작용을 삭제할 수 있습니다. 상호작용 ID를 알고 있는 경우에만 상호작용을 삭제할 수 있습니다.

보관 기간이 만료되면 데이터가 자동으로 삭제됩니다.

시스템은 약관에 따라 상호작용 객체를 처리합니다.

권장사항

  • 캐시 적중률: previous_interaction_id를 사용하여 대화를 계속하면 시스템에서 대화 기록에 암시적 캐싱을 더 쉽게 활용할 수 있으므로 성능이 개선되고 비용이 절감됩니다.
  • 상호작용 혼합: 대화 내에서 에이전트 및 모델 상호작용을 자유롭게 혼합하고 일치시킬 수 있습니다. 예를 들어 Deep Research 에이전트와 같은 전문 에이전트를 초기 데이터 수집에 사용한 다음 표준 Gemini 모델을 사용하여 요약 또는 형식 변경과 같은 후속 작업을 수행하고 이러한 단계를 previous_interaction_id로 연결할 수 있습니다.

지원되는 모델 및 에이전트

모델 이름 유형 모델 ID
Gemini 3.5 Flash 모델 gemini-3.5-flash
Gemini 3.1 Pro 프리뷰 모델 gemini-3.1-pro-preview
Gemini 3.1 Flash-Lite 모델 gemini-3.1-flash-lite
Gemini 3 Flash 프리뷰 모델 gemini-3-flash-preview
Gemini 2.5 Pro 모델 gemini-2.5-pro
Gemini 2.5 Flash 모델 gemini-2.5-flash
Gemini 2.5 Flash-lite 모델 gemini-2.5-flash-lite
Gemini 3 Pro Image 모델 gemini-3-pro-image
Gemini 3.1 Flash Image 모델 gemini-3.1-flash-image
Gemini 3.1 Flash TTS 프리뷰 모델 gemini-3.1-flash-tts-preview
Gemma 4 31B IT 모델 gemma-4-31b-it
Gemma 4 26B MoE IT 모델 gemma-4-26b-a4b-it
Lyria 3 Clip 프리뷰 모델 lyria-3-clip-preview
Lyria 3 Pro 프리뷰 모델 lyria-3-pro-preview
Deep Research 프리뷰 에이전트 deep-research-preview-04-2026
Deep Research 프리뷰 에이전트 deep-research-max-preview-04-2026
Antigravity 프리뷰 에이전트 antigravity-preview-05-2026

SDK

Interactions API에 액세스하려면 최신 버전의 Google 생성형 AI SDK를 사용하면 됩니다.

  • Python에서는 2.3.0 버전부터 google-genai 패키지입니다.
  • JavaScript에서는 2.3.0 버전부터 @google/genai 패키지입니다.

라이브러리 페이지에서 SDK를 설치하는 방법을 자세히 알아보세요.

제한사항

  • 원격 MCP: Gemini 3은 원격 MCP를 지원하지 않으며 곧 지원될 예정입니다.

다음 기능은 generateContent API에서 지원되지만 Interactions API에서는 아직 사용할 수 없습니다.

의견

여러분의 의견은 Interactions API 개발에 매우 중요합니다. Google AI 개발자 커뮤니티 포럼에서 의견을 공유하거나 버그를 신고하거나 기능을 요청하세요.

다음 단계