Interactions API

Interactions API는 Gemini 모델과 에이전트로 빌드하는 가장 좋은 방법이에요. 2026년 6월부터 GA(Generally Available)이며 모든 새 프로젝트에 권장돼요. 기존 generateContent API는 이제 레거시로 간주되지만 완전히 지원돼요.

출처: 원문

본문

Interactions API는 Gemini 모델과 에이전트로 빌드하는 가장 좋은 방법이에요. 2026년 6월부터 GA이며 모든 새 프로젝트에 권장돼요. 원래 generateContent API는 이제 레거시로 간주되지만 완전히 지원돼요.

왜 Interactions API를 써야 하나요?

모든 애플리케이션을 위한 범용 인터페이스: 단일 턴 텍스트 생성, 멀티모달 이해, 구조화 출력, 도구 오케스트레이션, 에이전트 워크플로를 포함한 모든 사용 사례의 표준 인터페이스로 설계됐어요.
모델과 에이전트를 위한 단일 API: 표준 Gemini 모델과 특수 에이전트(Deep Research, 커스텀 managed agents 등)를 직접 호출하는 하나의 통합 엔드포인트와 패턴.
즉시 사용 가능한 새 기능: previous_interaction_id를 사용한 선택적 서버 측 대화 상태, 디버깅과 UI 렌더링을 위한 관찰 가능한 실행 단계, background=true를 사용한 장기 작업용 백그라운드 실행 같은 기능.
더 높은 캐시 적중률로 낮은 비용: 다중 턴 대화에서 선택적 서버 측 상태 관리를 사용하면 턴 간 컨텍스트 캐싱을 더 효율적으로 해 토큰 비용을 줄여요.
새 기능이 출시되는 곳: 앞으로 모든 새 모델, 멀티모달 기능, 도구, 에이전트 기능이 Interactions API에서 출시돼요.

기본적으로 Interactions API는 요청을 저장해서 previous_interaction_id로 서버 측 상태 관리 기능을 활용할 수 있게 해요. store=false를 설정하면 무상태(stateless) 동작을 선택할 수 있어요. 자세한 내용은 데이터 보존 섹션을 참고하세요.

시작하기

코딩 에이전트 설정: Gemini Docs MCP에 연결하고 gemini-api-dev 스킬을 설치해 어시스턴트에게 최신 개발자 문서와 모범 사례에 대한 직접 접근을 주세요. 자세한 단계는 코딩 에이전트 설정 가이드를 참고하세요.
generateContent에서 마이그레이션: 기존 통합이 있다면 마이그레이션 가이드를 따라 Interactions API로 전환하세요.
시작하기: Interactions API 시작 가이드의 단계를 따르세요.

기능 가이드

다음 가이드를 통해 Interactions API의 특정 기능을 살펴보세요. 해당 페이지의 토글을 사용해 generateContent와 Interactions API 사이를 전환할 수 있어요:

Interactions API 동작 방식

Interactions API는 핵심 리소스인 Interaction을 중심으로 해요. Interaction은 대화나 작업에서 완전한 한 턴을 나타내요. 세션 기록으로 작동하며, 상호작용의 전체 기록을 **실행 단계(execution steps)**의 시간순 시퀀스로 포함해요. 이 단계에는 모델 생각, 서버 측·클라이언트 측 도구 호출과 결과(function_call, function_result 등), 최종 model_output이 포함돼요. 저장된 리소스(interactions.get으로 검색)에는 전체 컨텍스트를 위한 user_input 단계도 포함되지만, interactions.create 응답은 모델 생성 단계만 반환해요.

interactions.create를 호출하면 새 Interaction 리소스를 만들어요:

Python

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Tell me a short story about a time-traveling lighthouse."
)

print(interaction.output_text)

JavaScript

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI();

const interaction = await client.interactions.create({
  model: "gemini-3.8-flash",
  input: "Tell me a short story about a time-traveling lighthouse.",
});

console.log(interaction.output_text);

Java

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;

Client client = new Client();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.of("Tell me a short story about a time-traveling lighthouse."))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));

package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput("Tell me a short story about a time-traveling lighthouse."),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: *** \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "Tell me a short story about a time-traveling lighthouse."
  }'

서버 측 상태 관리

완료된 상호작용의 id를 previous_interaction_id 파라미터로 후속 호출에 사용해 대화를 계속할 수 있어요. 서버가 이 ID로 대화 기록을 검색하므로 전체 채팅 기록을 재전송하지 않아도 돼요:

Python

from google import genai

client = genai.Client()

# 1. First turn
turn1 = client.interactions.create(
    model="gemini-3.8-flash",
    input="Hi, my name is Phil."
)

# 2. Second turn (chained using previous_interaction_id)
turn2 = client.interactions.create(
    model="gemini-3.8-flash",
    input="What is my name?",
    previous_interaction_id=turn1.id
)

print(turn2.output_text)

JavaScript

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI();

// 1. First turn
const turn1 = await client.interactions.create({
  model: "gemini-3.8-flash",
  input: "Hi, my name is Phil.",
});

// 2. Second turn (chained using previous_interaction_id)
const turn2 = await client.interactions.create({
  model: "gemini-3.8-flash",
  input: "What is my name?",
  previous_interaction_id: turn1.id,
});

console.log(turn2.output_text);

Java

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;

Client client = new Client();

// 1. First turn
Interaction turn1 =
    client
        .interactions
        .create(
            CreateInteractionRequestBody.of(
                CreateModelInteraction.builder()
                    .model(Model.of("gemini-3.8-flash"))
                    .input(InteractionsInput.of("Hi, my name is Phil."))
                    .build()))
        .interaction()
        .get();

// 2. Second turn (chained using previousInteractionId)
Interaction turn2 =
    client
        .interactions
        .create(
            CreateInteractionRequestBody.of(
                CreateModelInteraction.builder()
                    .model(Model.of("gemini-3.8-flash"))
                    .input(InteractionsInput.of("What is my name?"))
                    .previousInteractionId(turn1.id().get())
                    .build()))
        .interaction()
        .get();

System.out.println(turn2.outputText().orElse(""));

package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    // 1. First turn
    turn1, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput("Hi, my name is Phil."),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    // 2. Second turn (chained using PreviousInteractionID)
    turn2, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model:                 interactions.Model("gemini-3.8-flash"),
            Input:                 interactions.NewInteractionsInput("What is my name?"),
            PreviousInteractionID: turn1.Interaction.ID,
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if turn2.Interaction.OutputText != nil {
        fmt.Println(*turn2.Interaction.OutputText)
    }
}

REST

# Replace PREVIOUS_INTERACTION_ID with the id returned from the first turn
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: *** \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "What is my name?",
    "previous_interaction_id": "PREVIOUS_INTERACTION_ID"
  }'

previous_interaction_id 파라미터는 previous_interaction_id를 사용해 대화 기록(입력과 출력)만 보존해요. 다른 파라미터는 상호작용 범위로, 현재 생성 중인 특정 상호작용에만 적용돼요:

tools
system_instruction
generation_config (thinking_level, temperature 등 포함)

즉, 이 파라미터들을 적용하려면 각 새 상호작용에서 다시 지정해야 해요. 이 서버 측 상태 관리는 선택 사항이며, 각 요청에 전체 대화 기록을 보내는 무상태 모드로도 동작할 수 있어요.

데이터 저장과 보존

기본적으로 API는 서버 측 상태 관리 기능(previous_interaction_id 사용), 백그라운드 실행(background=true 사용), 관찰 가능성 목적을 단순화하기 위해 모든 Interaction 객체를 저장해요 (store=true).

유료 티어: 시스템이 상호작용을 55일 동안 보관해요.
무료 티어: 시스템이 상호작용을 1일 동안 보관해요.

원하지 않으면 요청에서 store=false를 설정할 수 있어요. 이 제어는 상태 관리와 별개이며, 어떤 상호작용이든 저장을 선택 해제할 수 있어요. 다만 store=false는 백그라운드 실행과 호환되지 않고, 후속 턴에서 previous_interaction_id 사용을 막아요.

유료 티어 프로젝트에서는 AI Studio에서 보존 기간을 구성해 프로젝트 저장소에서 7, 14, 28, 55일 후에 자동으로 삭제되도록 표시할 수 있어요. 더 짧은 보존 기간은 과거 대화 검색에 영향을 줄 수 있어요.

저장된 상호작용은 인터랙션 ID가 필요한 delete 메서드로 언제든 프로그래밍 방식으로 삭제할 수 있어요. AI Studio에서 저장된 상호작용 로그를 보고 관리할 수도 있어요(프로젝트 저장소에서 삭제 포함).

보존 기간이 만료되면 데이터가 자동으로 삭제돼요.

Interaction 객체는 약관에 따라 처리돼요.

AI Studio에서 상호작용 보기

API는 유료 티어 프로젝트에 대해 store=true로 실행된 Interactions API 요청을 저장해요. Google AI Studio의 Logs 페이지에서 직접 볼 수 있어요. 자세한 내용은 Logs 가이드를 참고하세요.

모범 사례

캐시 적중률: 암시적 캐싱은 상태 저장·무상태 모드 모두에서 지원돼요 (참고: 퀵스타트). previous_interaction_id(상태 저장)로 대화를 계속하면 시스템이 대화 기록에 대한 암시적 캐싱을 더 쉽게 활용해 성능이 개선되고 비용이 줄어요.
상호작용 혼합: 대화 안에서 에이전트와 모델 상호작용을 자유롭게 섞을 수 있어요. 예를 들어 Deep Research 에이전트 같은 특수 에이전트로 초기 데이터 수집을 하고, 표준 Gemini 모델로 요약·재포맷 같은 후속 작업을 수행하며, 이 단계들을 previous_interaction_id로 연결할 수 있어요.

지원 모델·에이전트

모델 이름	유형	모델 ID
Gemini 3.8 Flash	Model	gemini-3.8-flash
Gemini 3.7 Flash	Model	gemini-3.7-flash
Gemini 3.6 Flash	Model	gemini-3.6-flash
Gemini 3.5 Flash	Model	gemini-3.5-flash
Gemini 3.1 Pro Preview	Model	gemini-3.1-pro-preview
Gemini 3.5 Flash-Lite	Model	gemini-3.5-flash-lite
Gemini 3.1 Flash-Lite	Model	gemini-3.1-flash-lite
Gemini 3 Flash Preview	Model	gemini-3-flash-preview
Gemini 2.5 Pro	Model	gemini-2.5-pro
Gemini 2.5 Flash	Model	gemini-2.5-flash
Gemini 2.5 Flash-lite	Model	gemini-2.5-flash-lite
Gemini 3 Pro Image	Model	gemini-3-pro-image
Gemini 3.1 Flash Image	Model	gemini-3.1-flash-image
Gemini 3.1 Flash TTS Preview	Model	gemini-3.1-flash-tts-preview
Gemma 4 31B IT	Model	gemma-4-31b-it
Gemma 4 26B MoE IT	Model	gemma-4-26b-a4b-it
Lyria 3.5	Model	lyria-3.5
Lyria 3 Clip Preview	Model	lyria-3-clip-preview
Lyria 3 Pro Preview	Model	lyria-3-pro-preview
Deep Research Preview	Agent	deep-research-preview-04-2026
Deep Research Preview	Agent	deep-research-max-preview-04-2026
Antigravity Preview	Agent	antigravity-preview-09-2026

SDK

Interactions API에 접근하려면 최신 버전의 Google GenAI SDK를 사용할 수 있어요.

Python에서는 google-genai 패키지 2.3.0 버전부터.
JavaScript에서는 @google/genai 패키지 2.3.0 버전부터.
Go에서는 google.golang.org/genai 패키지.
Java에서는 com.google.genai:google-genai 패키지.

SDK 설치 방법은 Libraries 페이지에서 더 알아볼 수 있어요.

제한 사항

원격 MCP: Gemini 3는 원격 MCP를 지원하지 않으며, 곧 지원 예정이에요.
다중 턴 모델 호환성: 대화에서 서로 다른 모델을 섞을 때(상태 저장·무상태 모두), 후속 모델이 이전 모델의 출력 양식을 입력으로 지원해야 해요. 예를 들어 gemini-3.1-flash-image로 이미지를 생성했다면, 이미지 입력을 받지 않는 모델(텍스트 전용 모델이나 Lyria 같은 음악 생성 모델)로 그 대화를 계속할 수 없어요.

generateContent API가 지원하지만 Interactions API에서는 아직 사용할 수 없는 기능은 다음과 같아요:

Batch API
자동 함수 호출 (Python)
명시적 캐싱: 참고로 서버 측 암시적 캐싱은 Interactions API에서 previous_interaction_id를 통해 사용할 수 있어요.
안전 설정: Interactions API에서는 커스텀 안전 설정이 지원되지 않아요.

피드백

Interactions API 개발에 여러분의 피드백이 중요해요. 의견 공유, 버그 신고, 기능 요청은 Google AI Developer Community Forum에서 해주세요.

다음으로

Interactions API 퀵스타트 노트북 사용해 보기.
Gemini Deep Research 에이전트에 대해 더 알아보기.

Interactions API

Interactions API

본문

왜 Interactions API를 써야 하나요?

시작하기

기능 가이드

Interactions API 동작 방식

서버 측 상태 관리

데이터 저장과 보존

AI Studio에서 상호작용 보기

모범 사례

지원 모델·에이전트

SDK

제한 사항

피드백

다음으로

더 알아보기 (Learn more)