Interactions API 개요

Interactions API는 Gemini Enterprise Agent Platform에서 호스팅되는 Gemini 모델 및 에이전트를 사용하여 생성형 AI 애플리케이션 및 Agentic Workflows를 빌드하기 위한 통합된 스테이트풀(Stateful) 인터페이스를 제공합니다. 기존 generateContent API와 기능이 겹치지만 generateContent API는 계속 완전히 지원됩니다.

Interactions API를 사용하는 이유는 무엇인가요?

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

  • 모델 및 에이전트를 위한 단일 API: 표준 Gemini 모델과 특수 에이전트 (예: Gemini Deep Research 에이전트 및 커스텀 관리형 에이전트)를 직접 호출하기 위한 통합 엔드포인트 및 패턴입니다.
  • 기본 제공되는 새로운 기능: 선택적 서버 측 대화 상태를 사용하는 기능(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 리소스를 반환합니다. Python, TypeScript/JavaScript, REST 전반의 코드 샘플은 Interactions API 개발자 가이드를 참고하세요.

지원되는 모델

다음 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 자율 다단계 웹 연구 및 합성을 위해 설계된 에이전트입니다.
  • Agent Platform에 배포된 커스텀 관리형 에이전트입니다.

기능 및 사양

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

상태 관리

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

지원되는 도구 및 그라운딩

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

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

Interactions API는 Enterprise용 웹 그라운딩 및 Google 검색을 사용한 그라운딩을 지원합니다. 이러한 기능의 사용에는 서비스별 약관도 적용됩니다. 이러한 기능의 사용에는 서비스별 약관도 적용됩니다.

결제

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

중단되거나 이행되지 않은 요청의 결제는 다음과 같이 처리됩니다.

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

보안 및 규정 준수

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

  • 보안 및 규정 준수 인증: Interactions API 미리보기는 FedRAMP를 지원하지 않으며 미국 국방부(DoD) Impact Level 5 (IL5) 또는 국제 무기 거래 규정(ITAR) 요구사항을 준수하지 않습니다.
  • 고객 관리 암호화 키 (CMEK): Interactions API는 저장된 상호작용 데이터에 CMEK를 서비스 프로필을 통해 (scope이 INTERACTIONS_API로 설정됨) us 및 eu 멀티 리전에서 지원합니다.
  • VPC 서비스 제어: Interactions API 미리보기는 API 경계를 보호하기 위해 VPC 서비스 제어 (VPC-SC)를 지원합니다.
  • 데이터 레지던시: Interactions API 미리보기는 데이터 레지던시를 지원하지 않으며 세션 저장소에 대한 약속을 하지 않습니다.
  • 엔드포인트: Interactions API 미리보기는 전역 엔드포인트 (locations/global)를 지원하며 CMEK를 사용할 때 us 및 eu 멀티 리전 엔드포인트 (locations/us 및 locations/eu)를 지원합니다.

지원되는 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를 지원하지 않습니다.

다음 단계