Interactions API

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

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

Interactions API를 사용해야 하는 이유

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

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

시작하기

기능 가이드

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

Interactions API 작동 방식

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

interactions.create에 대한 호출을 하면 새 Interaction 리소스가 생성됩니다.

서버 측 상태 관리

previous_interaction_id 매개변수를 사용하여 후속 호출에서 완료된 상호작용의 id를 사용하여 대화를 계속할 수 있습니다. 서버는 이 ID를 사용하여 대화 기록을 가져오므로 전체 채팅 기록을 다시 보낼 필요가 없습니다.

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

  • tools
  • system_instruction
  • generation_config (thinking_level, temperature 등 포함)

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

데이터 스토리지 및 보관

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

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

이를 원치 않는 경우 요청에서 store=false를 설정하면 됩니다. 이 컨트롤은 상태 관리와 별개이며 모든 상호작용에 대해 저장소를 선택 해제할 수 있습니다. 하지만 store=false는 background=true과 호환되지 않으며 후속 턴에 previous_interaction_id를 사용하는 것을 방지합니다.

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

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

시스템은 약관에 따라 Interaction 객체를 처리합니다.

권장사항

  • 캐시 적중률: 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 클립 미리보기 모델 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

최신 버전의 Google 생성형 AI SDK를 사용하여 Interactions API에 액세스할 수 있습니다.

  • 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 개발자 커뮤니티 포럼에서 의견을 공유하거나 버그를 신고하거나 기능을 요청하세요.

다음 단계