Interactions API

Interactions API는 Gemini 모델 및 에이전트를 사용하여 빌드하는 가장 간단하고 효과적인 방법입니다. 2026년 6월부터 정식 버전으로 제공되며 모든 신규 프로젝트에 권장됩니다. 이제 기존 generateContent API는 레거시로 간주되지만 계속해서 완전히 지원됩니다.

Interactions API를 사용해야 하는 이유

  • 모든 애플리케이션을 위한 범용 인터페이스: 단일 턴 텍스트 생성, 멀티모달 이해, 구조화된 출력, 도구 오케스트레이션, 에이전트형 워크플로 등 모든 사용 사례를 위한 표준 인터페이스로 설계되었습니다.
  • 모델 및 에이전트를 위한 단일 API: 표준 Gemini 모델과 전문 에이전트 (예: Deep Research, 맞춤 관리 에이전트)를 직접 호출하기 위한 통합 엔드포인트 및 패턴입니다.
  • 기본적으로 제공되는 새로운 기능: previous_interaction_id를 사용하는 선택적 서버 측 대화 상태, 디버깅 및 UI 렌더링을 위한 관찰 가능한 실행 단계, background=true를 사용하는 장기 실행 작업의 백그라운드 실행과 같은 기능
  • 높은 캐시 적중률로 비용 절감: 멀티턴 대화를 사용할 때 선택적 서버 측 상태 관리를 사용하면 턴 간에 더 효율적인 컨텍스트 캐싱이 가능해 토큰 비용이 절감됩니다.
  • 새 기능 출시 위치: 앞으로 모든 새로운 모델, 멀티모달 기능, 도구, 에이전트 기능은 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은 백그라운드 실행과 호환되지 않으며 후속 턴에 previous_interaction_id을 사용할 수 없습니다.

유료 등급 프로젝트의 경우 AI Studio에서 보관 기간을 구성하여 7일, 14일, 28일 또는 55일 후에 프로젝트 스토리지에서 삭제할 로그를 자동으로 표시할 수 있습니다. 보관 기간이 짧으면 이전 대화 검색에 영향을 미칠 수 있습니다.

상호작용 ID가 필요한 delete 메서드를 프로그래매틱 방식으로 사용하여 언제든지 저장된 상호작용을 삭제할 수 있습니다. AI Studio에서 프로젝트 스토리지에서의 삭제를 비롯한 저장된 상호작용 로그를 확인하고 관리할 수도 있습니다.

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

상호작용 객체는 약관에 따라 처리됩니다.

AI Studio에서 상호작용 보기

API는 유료 등급 프로젝트에 대해 store=true로 실행된 Interactions API 요청을 저장합니다. Google AI Studio의 로그 페이지에서 직접 확인할 수 있습니다. 자세한 내용은 로그 가이드를 참고하세요.

권장사항

  • 캐시 적중률: 암시적 캐싱은 스테이트풀 모드와 스테이트리스 모드 모두에서 지원됩니다 (빠른 시작 참고). previous_interaction_id (상태 저장)를 사용하여 대화를 계속하면 시스템에서 대화 기록에 대한 암시적 캐싱을 더 쉽게 활용할 수 있으므로 성능이 향상되고 비용이 절감됩니다.
  • 상호작용 혼합: 대화 내에서 에이전트와 모델 상호작용을 자유롭게 혼합할 수 있습니다. 예를 들어 심층 조사 에이전트와 같은 전문 에이전트를 사용하여 초기 데이터 수집을 수행한 다음 표준 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를 지원하지 않습니다. 곧 지원될 예정입니다.
  • 멀티턴 모델 호환성: 대화에서 서로 다른 모델 (상태 저장 또는 상태 비저장)을 혼합할 때 후속 모델은 이전 모델의 출력 모달리티를 입력으로 지원해야 합니다. 예를 들어 gemini-3.1-flash-image를 사용하여 이미지를 생성하는 경우 이미지 입력을 허용하지 않는 모델 (예: 텍스트 전용 모델 또는 Lyria와 같은 음악 생성 모델)과의 대화를 계속할 수 없습니다.

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

의견

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

다음 단계