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를 설정하여 스테이트리스 동작을 선택할 수 있습니다. 자세한 내용은 데이터 보관 섹션을 참고하세요.

시작하기

  • 코딩 에이전트 설정: Gemini Docs MCP 에 연결하고 gemini-api-dev 스킬을 설치하여 어시스턴트가 최신 개발자 문서 및 권장사항에 직접 액세스할 수 있도록 합니다. 자세한 단계는 코딩 에이전트 설정 가이드를 참고하세요.
  • 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
  • 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의 로그 페이지에서 직접 볼 수 있습니다. 자세한 내용은 로그 가이드를 참고하세요.

권장사항

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

지원되는 모델 및 에이전트

모델 이름 유형 모델 ID
Gemini 3.8 Flash 모델 gemini-3.8-flash
Gemini 3.7 Flash 모델 gemini-3.7-flash
Gemini 3.6 Flash 모델 gemini-3.6-flash
Gemini 3.5 Flash 모델 gemini-3.5-flash
Gemini 3.1 Pro 프리뷰 모델 gemini-3.1-pro-preview
Gemini 3.5 Flash-Lite 모델 gemini-3.5-flash-lite
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.5 모델 lyria-3.5
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를 지원하지 않습니다. 곧 지원될 예정입니다.
  • 멀티턴 모델 호환성: 대화에서 서로 다른 모델을 혼합할 때(스테이트풀(Stateful) 또는 스테이트리스(Stateless)) 후속 모델은 이전 모델의 출력 형식을 입력으로 지원해야 합니다. 예를 들어 gemini-3.1-flash-image를 사용하여 이미지를 생성하는 경우 이미지 입력을 허용하지 않는 모델 (예: 텍스트 전용 모델 또는 Lyria와 같은 음악 생성 모델)로 대화를 계속할 수 없습니다.

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

의견

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

다음 단계