Rubric Labs
interactions API에서 store=false를 설정하면 서버가 대화 이력을 보관하지 않아요. 대신 앱이 매 요청마다 전체 이력을 input에 담아 넘겨야 하고, 모델이 반환한 모든 step을 그대로 포함해야 함수 결과를 올바르게 이어받을 수 있어요.
← 실무 팁 목록
연동/통합· medium···

Gemini API interactions API 상태 비저장 모드로 함수 호출 대화 관리하기

interactions API에서 store=false를 설정하면 서버가 대화 이력을 보관하지 않아요. 대신 앱이 매 요청마다 전체 이력을 input에 담아 넘겨야 하고, 모델이 반환한 모든 step을 그대로 포함해야 함수 결과를 올바르게 이어받을 수 있어요.

상태 비저장 모드란

interactions API는 기본적으로 서버가 대화 이력을 저장하고 previous_interaction_id로 이전 턴을 참조한다. store=false를 설정하면 서버가 이력을 보관하지 않으므로, 앱이 전체 대화 흐름을 직접 관리해야 한다.

이 방식은 대화 이력을 외부 DB에 저장하거나, 서버 측 세션 없이 클라이언트가 상태를 완전히 통제해야 하는 환경에 적합하다.

이력에 포함해야 하는 항목

공식 문서에 따르면 두 번째 요청의 input에는 다음 세 가지를 순서대로 담아야 한다.

  1. 최초 user_input step
  2. 1턴에서 모델이 반환한 모든 step — thought, function_call step 포함, 받은 그대로
  3. 앱이 함수를 실행한 뒤 만든 function_result step

모델이 반환한 step을 일부만 넣거나 순서를 바꾸면 모델이 이전 맥락을 올바르게 복원하지 못할 수 있다.

Python 예시

아래는 예시 코드다.

import json
from google import genai

client = genai.Client()

history = [
    {
        "type": "user_input",
        "content": [{"type": "text", "text": "Turn the lights down to a romantic level"}]
    }
]

# 1턴: 함수 선언과 함께 요청
interaction = client.interactions.create(
    model="gemini-3.8-flash",
    store=False,
    input=history,
    tools=[set_light_values_declaration],
)

# 모델이 반환한 step 전체를 이력에 추가
for step in interaction.steps:
    history.append(step.model_dump())

# function_call step 추출 후 실행
fc_step = next(s for s in interaction.steps if s.type == "function_call")
if fc_step.name == "set_light_values":
    result = set_light_values(**fc_step.arguments)

# function_result를 이력에 추가
history.append({
    "type": "function_result",
    "name": fc_step.name,
    "call_id": fc_step.id,
    "result": [{"type": "text", "text": json.dumps(result)}],
})

# 2턴: 전체 이력을 input으로 전달
final_interaction = client.interactions.create(
    model="gemini-3.8-flash",
    store=False,
    input=history,
    tools=[set_light_values_declaration],
)
print(final_interaction.output_text)

step.model_dump()로 Pydantic 객체를 딕셔너리로 변환해 이력에 쌓는 것이 핵심이다. 객체를 그대로 리스트에 넣으면 두 번째 요청에서 직렬화 오류가 날 수 있다.

상태 저장 모드와 비교

상태 저장 모드에서는 두 번째 요청에 previous_interaction_id만 넘기면 서버가 이전 이력을 참조한다. 상태 비저장 모드는 그 역할을 앱이 직접 담당하므로 요청 페이로드가 커지지만, 서버 세션에 의존하지 않아 멀티 인스턴스 환경에서 이력 관리가 단순해진다.

확인 방법

final_interaction.output_text가 함수 실행 결과를 반영한 자연어 응답을 돌려주면 이력이 올바르게 전달된 것이다. 빈 응답이나 함수 결과를 무시한 답변이 나오면 이력 구성 순서나 call_id 일치 여부를 점검한다.

한계

store=false 상태에서 이력 크기는 모델의 컨텍스트 윈도우 한도를 따른다. 대화가 길어질수록 페이로드가 커지므로, 장기 세션에서는 이력 압축 전략을 별도로 설계해야 한다. 또한 공식 문서는 thought step도 그대로 포함하도록 명시하므로, 필터링 없이 모든 step을 이력에 추가하는 것이 안전하다.

참고 출처