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는 요구사항에 맞는 기존 통합이 있거나 Batch API 또는 명시적 캐싱과 같이 Interactions API에서 아직 제공되지 않는 기능이 필요한 경우 사용하세요.

시작하기

  • 코딩 에이전트 설정: 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 리소스가 생성됩니다.

SDK 편의 속성으로 출력에 액세스

Interactions API는 사고, 검색어, 함수 호출과 같은 실행 단계의 구조화된 타임라인을 반환하지만 최종 모델 응답을 가져오기 위해 단계를 수동으로 탐색할 필요는 없습니다.

Google 생성형 AI SDK는 반환된 Interaction 객체에 직접 편의 속성을 제공하여 다양한 양식의 출력에 액세스합니다.

SDK 편의 속성 반환 유형 설명
interaction.output_text 문자열 모델 응답의 마지막 텍스트 블록을 반환합니다. 응답이 여러 개의 연속된 TextContent 블록으로 분할된 경우 자동으로 결합됩니다. 사고, 이미지, 오디오, 도구 호출과 같은 텍스트가 아닌 콘텐츠로 구분된 이전 텍스트 블록은 포함되지 않습니다. 복잡하거나 인터리브된 멀티모달 응답의 경우 steps를 수동으로 반복해야 합니다.
interaction.output_image ImageContent 또는 None 현재 요청에서 모델이 생성한 마지막 이미지 블록을 반환합니다.
interaction.output_audio AudioContent 또는 None 현재 요청에서 모델이 생성한 마지막 오디오 블록을 반환합니다.

중간 사고 프로세스 렌더링, 단계별 도구 호출 검사, 디버깅과 같은 고급 사용 사례의 경우 원시 interaction.steps 타임라인을 수동으로 검사하고 탐색할 수 있습니다.

서버 측 상태 관리

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

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

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

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

데이터 스토리지 및 보관

기본적으로 API는 서버 측 상태 관리 기능 (previous_interaction_id 사용), 백그라운드 실행 (background=true 사용), 모니터링 가능성 목적의 사용을 간소화하기 위해 모든 Interaction 객체 (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 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 Clip 프리뷰 모델 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는 현재 초기 베타 단계입니다. 실제 사용 및 개발자 의견을 바탕으로 API 기능, 리소스 스키마, SDK 인터페이스를 적극적으로 개발하고 개선하고 있습니다. 따라서 이전 버전과 호환되지 않는 변경사항이 발생할 수 있습니다.

기존 브레이킹 체인지:

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

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

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

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

의견

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

다음 단계