Interactions API 개요

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

Interactions API를 사용해야 하는 이유

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

  • 모델 및 에이전트를 위한 단일 API: 표준 Gemini 모델은 물론 Gemini Deep Research 에이전트 및 커스텀 관리형 에이전트와 같은 특수 에이전트를 직접 호출하기 위한 하나의 통합 엔드포인트 및 패턴입니다.
  • 기본 제공되는 새로운 기능: previous_interaction_id를 사용하는 선택적 서버 측 대화 상태, 디버깅 및 UI 렌더링을 위한 관찰 가능한 실행 단계, background=true를 사용하는 장기 실행 태스크의 백그라운드 실행과 같은 기능이 있습니다.

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를 호출하면 에이전트 플랫폼이 입력을 처리하고 구성된 서버 측 도구 또는 에이전트 루프를 실행하고 결과 Interaction 리소스를 반환합니다. Python, TypeScript/JavaScript, REST의 코드 샘플은 Interactions API 개발자 가이드를 참고하세요.

지원되는 모델

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

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

Interactions API는 앞의 목록에 있는 Gemini 모델 외에도 다음과 같은 생성형 음악 모델을 지원합니다. * 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를 사용하여 멀티턴 대화를 연결하고 비동기 백그라운드 작업(background=true)을 실행할 수 있도록 서버(store=true)에 상호작용을 7일 동안 저장합니다. 스테이트리스(Stateless) 실행을 선택하고 데이터 보관 없음(ZDR) 워크플로를 지원하려면 store=false를 설정하세요. 자세한 내용은 세션 스토리지 및 대화 상태 관리를 참조하세요.

요청 및 멀티모달 한도

Interactions API는 다음과 같은 요청 페이로드 및 멀티모달 입력 한도를 적용합니다.

  • 요청 페이로드 한도: 압축된 HTTP 요청 페이로드는 동기식 및 스트리밍 interactions.create 요청의 경우 256MiB를 초과할 수 없습니다. service_tier가 deferred로 설정된 경우(background 및 store가 모두 true여야 함) 압축되지 않은 요청은 9.75MiB를 초과할 수 없습니다.
  • Cloud Storage 파일의 URI 한도: 표준 Gemini 모델 상호작용 요청은 previous_interaction_id를 통해 이전 대화 차례에서 전달된 URI를 포함하여 요청당 최대 100개의 고유한 Cloud Storage(gs://) URI를 지원합니다. 관리형 에이전트 상호작용, Gemini Omni 모델, Lyria 3 모델은 이 100개 URI 한도에서 제외됩니다. 권한 및 멀티턴 URI 처리는 업로드된 Cloud Storage 파일 액세스를 참조하세요.
  • 멀티모달 항목 및 토큰 한도: 표준 Gemini 모델은 generateContent와 동일한 모달리티별 항목 수(이미지 및 PDF 최대 3,000개, 오디오 파일 1,000개, 동영상 10개, 일반 텍스트 파일을 포함한 멀티모달 파일 최대 6,500개)를 허용하며, 모델의 1,048,576 토큰 컨텍스트 윈도우로 제한됩니다. 개별 Cloud Storage 파일은 2GiB에서 500KiB를 뺀 값을 초과할 수 없으며 공개 HTTP 또는 HTTPS URL은 15MiB를 초과할 수 없습니다. 단일 요청으로 100개 이상의 파일을 전송하려면 요청 페이로드 한도 내에서 추가 첨부파일을 인라인으로 전달하거나 generateContent를 호출합니다.

지원되는 도구 및 그라운딩

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

  • Google 검색을 사용한 그라운딩 및 엔터프라이즈용 웹 그라운딩: Google 검색 또는 엔터프라이즈용 웹 그라운딩의 실시간 웹 정보를 사용하여 모델 대답을 그라운딩합니다.
  • Gemini Enterprise Agent Platform의 Agent Search 및 RAG Engine: Agent Search 및 RAG Engine을 사용하여 비공개 엔터프라이즈 데이터 스토어 및 문서 저장소를 기준으로 모델 응답을 그라운딩합니다.
  • Exa 웹 검색: Exa의 검색 API에서 가져온 웹 검색 결과를 사용하여 모델 대답을 그라운딩합니다.
  • Parallel Web Search: Parallel Web Systems의 검색 API에서 제공하는 실시간 공개 웹 데이터로 모델 응답을 그라운딩합니다.
  • URL 컨텍스트: 프롬프트에 포함된 공개 웹 URL에서 콘텐츠를 검색하고 분석합니다.
  • 코드 실행: 모델이 안전한 샌드박스 환경에서 Python 코드를 생성하고 실행할 수 있습니다.
  • 컴퓨터 사용: 브라우저 및 사용자 인터페이스 자동화 워크플로를 사용 설정합니다.
  • 함수 호출: 모델이 구조화된 함수 인수를 반환하여 외부 도구, API, 데이터베이스에 연결할 수 있습니다.

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

결제

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

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

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

보안 및 규정 준수

Interactions API는 다음 보안 제어, 규정 준수 인증, 엔드포인트 구성을 지원합니다.

  • 엔드포인트: Interactions API는 전역 엔드포인트(aiplatform.googleapis.com의 locations/global)와 us 및 eu 멀티 리전 엔드포인트(aiplatform.us.rep.googleapis.com의 locations/us 및 aiplatform.eu.rep.googleapis.com의 locations/eu)를 지원합니다. 단일 리전 엔드포인트(예: us-central1 또는 europe-west1)는 지원되지 않습니다.
  • 데이터 레지던시: Interactions API는 us 및 eu 멀티 리전 엔드포인트(locations/us 및 locations/eu)를 사용할 때 ML 처리(사용 중)와 저장된 상호작용 데이터(store=true) 모두에 대해 데이터 레지던시를 지원합니다. global 엔드포인트로 전송된 요청은 데이터 레지던시를 보장하지 않습니다.
  • 고객 관리 암호화 키(CMEK): Interactions API는 us 및 eu 멀티 리전에서 서빙 프로필(scope가 INTERACTIONS_API로 설정됨)을 통해 저장된 상호작용 데이터에 대한 CMEK를 지원합니다. global 엔드포인트는 CMEK에 지원되지 않습니다.
  • VPC 서비스 제어(VPC-SC): Interactions API는 VPC-SC를 지원하여 API 경계를 보호하고 데이터 무단 반출 위험을 완화합니다.
  • 액세스 투명성(AXT): Interactions API는 Google 직원이 저장된 상호작용 콘텐츠에 액세스할 때 거의 실시간으로 가시성을 제공하는 AXT 로그를 지원합니다.
  • 보안 및 규정 준수 인증: Interactions API는 Google Cloud FedRAMP High 승인 경계 내에서 FedRAMP High 요구사항을 충족합니다. Interactions API는 미국 국방부(DoD) 영향 수준 5(IL5) 또는 국제 무기 거래 규정(ITAR) 요구사항을 준수하지 않습니다.

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

다음 단계