Interactions API

Interactions API는 Gemini로 빌드하기 위한 새로운 표준 기본 요소이며 모든 새 프로젝트에 권장됩니다. 에이전트형 워크플로, 서버 측 상태 관리, 복잡한 멀티모달, 멀티 턴 대화에 최적화되어 있습니다. 기존 generateContent API는 계속해서 완벽히 지원됩니다.

Interactions API를 사용해야 하는 이유

  • 서버 측 기록 관리: previous_interaction_id를 통해 멀티턴 흐름을 간소화합니다. 서버는 기본적으로 상태를 사용 설정하지만 (store=true) store=false를 설정하여 상태 비저장 동작을 선택할 수 있습니다.
  • 관찰 가능한 실행 단계: 유형이 지정된 단계를 사용하면 복잡한 흐름을 쉽게 디버그하고 중간 이벤트 (예: 생각 또는 검색 위젯)의 UI를 렌더링할 수 있습니다.
  • 에이전트형 워크플로를 위해 빌드됨: 유형이 지정된 실행 단계를 통해 다단계 도구 사용, 오케스트레이션, 복잡한 추론 흐름을 기본적으로 지원합니다.
  • 장기 실행 및 백그라운드 작업: background=true를 사용하여 Deep Think 및 Deep Research와 같은 시간 집약적인 작업을 백그라운드 프로세스로 오프로드하는 것을 지원합니다.
  • 새로운 모델 및 기능에 대한 액세스: 앞으로 핵심 메인라인 제품군을 넘어선 새로운 모델과 새로운 에이전트 기능 및 도구가 Interactions API에서만 출시됩니다.

새 프로젝트를 시작하거나, 에이전트 기반 애플리케이션을 빌드하거나, 서버 측 대화 관리가 필요한 경우 Interactions API를 사용하세요. generateContent 사용: 요구사항에 맞는 기존 통합이 있거나 Interactions API에서 아직 사용할 수 없는 기능(예: Batch API 또는 명시적 캐싱)이 필요한 경우 사용합니다.

시작하기

  • 코딩 에이전트 설정: Gemini Docs MCP에 연결하고 gemini-interactions-api 기능을 설치하여 어시스턴트가 최신 개발자 문서와 권장사항에 직접 액세스할 수 있도록 합니다. 코딩 에이전트 설정하기 →
  • generateContent에서 마이그레이션: 기존 통합이 있는 경우 마이그레이션 가이드에 따라 Interactions API로 전환하세요.
  • 빠른 시작 사용해 보기: 상호작용 API 빠른 시작에서 최소한의 작동 예시로 시작하세요.

기능 가이드

이 가이드를 통해 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.1 Flash-Lite 모델 gemini-3.1-flash-lite
Gemini 3.1 Flash-Lite 프리뷰 모델 gemini-3.1-flash-lite-preview
Gemini 3.1 Pro 프리뷰 모델 gemini-3.1-pro-preview
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
Lyria 3 클립 미리보기 모델 lyria-3-clip-preview
Lyria 3 Pro 미리보기 모델 lyria-3-pro-preview
Deep Research 미리보기 에이전트 deep-research-pro-preview-12-2025
Deep Research 미리보기 에이전트 deep-research-preview-04-2026
Deep Research 미리보기 에이전트 deep-research-max-preview-04-2026

SDK

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

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

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

제한사항

  • 베타 상태: Interactions API는 베타/미리보기 상태입니다. 기능과 스키마는 변경될 수 있습니다.
  • 원격 MCP: Gemini 3는 원격 MCP를 지원하지 않습니다. 곧 지원될 예정입니다.

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

브레이킹 체인지

Interactions API는 현재 초기 베타 단계입니다. Google은 실제 사용 및 개발자 의견을 기반으로 API 기능, 리소스 스키마, SDK 인터페이스를 적극적으로 개발하고 개선하고 있습니다. 따라서 브레이킹 체인지가 발생할 수 있습니다.

기존 브레이킹 체인지:

  • 단계 스키마: 새로운 단계 배열이 출력 배열을 대체하여 각 상호작용 턴의 구조화된 타임라인을 제공합니다.

최근 브레이킹 체인지에 대해 알아보고 이전 방법을 이해하려면 브레이킹 체인지 이전 가이드 (2026년 5월)를 참고하세요.

기타 잠재적인 업데이트에는 입력 및 출력 스키마, SDK 메서드 서명 및 객체 구조, 특정 기능 동작의 변경사항이 포함될 수 있습니다.

프로덕션 워크로드의 경우 표준 generateContent API를 계속 사용해야 합니다. 안정적인 배포를 위한 권장 경로로 유지되며 적극적으로 개발하고 유지할 것입니다.

의견

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

다음 단계