Interactions API 개요

Interactions API는 Gemini Enterprise Agent Platform에서 호스팅되는 Gemini 모델과 에이전트를 사용하여 생성형 AI 애플리케이션과 에이전트형 워크플로를 빌드하기 위한 통합된 상태 저장 인터페이스를 제공합니다. 기존 generateContent API와 기능이 중복되지만 generateContent API는 계속 완전히 지원됩니다.

Interactions API를 사용해야 하는 이유

Interactions API는 생성형 AI 애플리케이션과 에이전트형 워크플로를 빌드할 때 다음과 같은 여러 주요 이점을 제공합니다.

  • 모델 및 에이전트용 단일 API: 표준 Gemini 모델과 전문 에이전트 (예: Gemini Deep Research Agent 및 맞춤 관리 에이전트)를 직접 호출하기 위한 통합 엔드포인트 및 패턴입니다.
  • 기본적으로 제공되는 새로운 기능: previous_interaction_id를 사용하는 선택적 서버 측 대화 상태, 디버깅 및 UI 렌더링을 위한 관찰 가능한 실행 단계, background=true를 사용하는 장기 실행 작업의 백그라운드 실행과 같은 기능
  • 새 기능 출시 위치: 앞으로 모든 새로운 모델, 멀티모달 기능, 도구, 에이전트 기능은 Interactions API에서 지원됩니다.

Interactions API 작동 방식

Interactions API는 Interaction 리소스를 중심으로 합니다. Interaction는 대화 또는 작업의 완전한 턴을 나타내며 실행 steps의 시간순 시퀀스를 포함하는 세션 레코드 역할을 합니다.

  • user_input: 턴에 제공된 입력 메시지, 멀티모달 파일 또는 도구 결과입니다. interactions.get로 검색된 저장된 상호작용에는 전체 컨텍스트를 위한 user_input 단계가 포함되지만 interactions.create 응답은 해당 턴에 생성된 단계만 반환합니다.
  • thought: 모델 또는 에이전트가 대답을 계획할 때 생성하는 중간 추론 요약입니다.
  • 도구 호출 및 결과 단계: 클라이언트 측 또는 서버 측 도구 호출 및 출력 (예: function_call 및 function_result)
  • model_output: 모델 또는 에이전트가 생성한 최종 텍스트, 구조화된 JSON 또는 멀티모달 콘텐츠입니다.

interactions.create를 호출하면 Agent Platform에서 입력을 처리하고, 구성된 서버 측 도구나 에이전트 루프를 실행하고, 결과 Interaction 리소스를 반환합니다.

지원되는 모델

다음 Gemini 모델은 Interactions API를 지원합니다.

클릭하여 지원되는 모델 펼치기

위의 모델 외에도 Interactions API는 다음과 같은 특수 멀티모달 및 오디오 생성 모델을 지원합니다.

  • gemini-omni-flash-preview: 대화형 동영상 생성, 편집, 영화 같은 제어를 위한 고성능 멀티모달 모델입니다.
  • lyria-3-clip-preview 및 lyria-3-pro-preview: 충실도 높은 오디오 클립 및 전체 음악작품 작곡을 위한 생성형 음악 모델(store=false를 사용한 스테이트리스(Stateless) 상호작용에서만 지원됨)

고객 지원 담당자

model 대신 agent 파라미터를 지정하여 Interactions API를 통해 다음 에이전트를 호출할 수 있습니다.

  • antigravity-preview-05-2026: 다단계 추론, 코딩, 파일 작업, 도구 사용을 위해 설계된 범용 자율 에이전트입니다.
  • deep-research-preview-04-2026: 자율적이고 다단계 웹 연구 및 종합을 위해 설계된 Gemini Deep Research 에이전트
  • Agent Platform에 배포된 맞춤 관리형 에이전트

기능 및 사양

다음 섹션에서는 Interactions API의 핵심 기능, 기술 사양, 운영 고려사항을 설명합니다.

상태 관리

기본적으로 Interactions API는 previous_interaction_id를 사용하여 서버 측 상태 관리 기능을 활용할 수 있도록 요청을 저장합니다. store=false를 설정하여 상태 비저장 동작을 선택할 수 있습니다.

지원되는 도구 및 그라운딩

Interactions API의 Gemini 3 모델에서는 다음과 같은 기본 제공 도구, 그라운딩 제공업체, 검색 기능이 지원됩니다.

  • Google 검색을 사용한 그라운딩 및 엔터프라이즈용 웹 그라운딩: Google 검색 또는 엔터프라이즈용 웹 그라운딩의 실시간 웹 정보를 사용하여 모델 대답을 그라운딩합니다.
  • Gemini Enterprise Agent Platform의 Agent Search 및 RAG 엔진: Agent Search 및 RAG 엔진을 사용하여 비공개 엔터프라이즈 데이터 저장소 및 문서 저장소를 기준으로 모델 응답을 그라운딩합니다.
  • xAI 검색: 모델을 실시간 소셜 검색 및 지식 그라운딩에 연결합니다.
  • Parallel Search: Parallel Web Systems의 검색 API에서 제공하는 실시간 공개 웹 데이터로 모델 대답을 그라운딩합니다.
  • 코드 실행: 모델이 안전한 샌드박스 환경에서 Python 코드를 생성하고 실행할 수 있습니다.
  • 함수 호출: 모델이 구조화된 함수 인수를 반환하여 외부 도구, API, 데이터베이스에 연결할 수 있습니다.

Interactions API는 엔터프라이즈용 웹 그라운딩과 Google 검색을 사용한 그라운딩을 지원합니다. 이러한 기능을 사용하는 경우 서비스별 약관도 적용됩니다.

결제

Interactions API 사용량은 토큰 소비를 기준으로 청구됩니다.

중단되거나 이행되지 않은 요청에 대한 청구는 다음과 같이 처리됩니다.

  • 수동 취소: 완료되기 전에 상호작용이 취소되는 경우 (예: 취소 요청을 전송하는 경우) 취소 시점까지 사용된 토큰에 대해 요금이 청구됩니다.
  • 실패한 요청: 내부 시스템 오류 또는 백엔드 오류로 인해 상호작용 요청이 실패하면 실패한 요청에 대한 요금이 청구되지 않습니다.

보안 및 규정 준수

미리보기 기간 동안 Interactions API에는 다음과 같은 보안, 규정 준수, 데이터 레지던시 고려사항이 있습니다.

  • 보안 및 규정 준수 인증: Interactions API 미리보기는 FedRAMP 또는 고객 관리 암호화 키 (CMEK)를 지원하지 않으며 미국 국방부 (DoD) 영향 수준 5 (IL5) 또는 국제 무기 거래 규정 (ITAR) 요구사항을 준수하지 않습니다.
  • VPC 서비스 제어: Interactions API 미리보기는 API 경계를 보호하기 위해 VPC 서비스 제어 (VPC-SC)를 지원합니다.
  • 데이터 레지던시: Interactions API 미리보기는 데이터 레지던시를 지원하지 않으며 세션 저장에 대한 약속을 하지 않습니다.
  • 엔드포인트: Interactions API 미리보기는 전역 엔드포인트(locations/global)만 지원합니다.

지원되는 SDK

통합 Google 생성형 AI SDK 또는 직접 REST 호출을 사용하여 Interactions API에 액세스할 수 있습니다.

  • Python: google-genai 버전 2.3.0 이상
  • TypeScript / JavaScript: @google/genai 버전 2.3.0 이상
  • Go: google.golang.org/genai
  • Java: com.google.genai:google-genai

기존 SDK (google-cloud-aiplatform, @google-cloud/vertexai, google-generativeai)는 Interactions API를 지원하지 않습니다.

다음 단계