Gemini 3.5 Flash는 일반적으로 사용 가능(GA)하며, 안정적이고 대규모 프로덕션 사용을 위한 준비가 되어 있습니다. 우리의 가장 지능적인 Flash 모델로서, 에이전트 실행(agentic execution), 코딩(coding), 그리고 대규모 장기 과제(long-horizon tasks)에서 지속적인 프런티어 성능(frontier performance)을 제공합니다. 이 가이드에는 Gemini 3.5 Flash의 개선 사항, API 변경 사항 및 마이그레이션 가이드에 대한 개요가 포함되어 있습니다.

새로운 모델

Gemini 3.5 Flash는 1M 토큰 컨텍스트 윈도우(context window), 65k 최대 출력 토큰(max output tokens), 사고(thinking), 그리고 Gemini 3 Flash와 동일한 도구 및 플랫폼 기능 세트를 지원합니다. 현재 컴퓨터 사용(Computer Use)은 지원되지 않습니다. 전체 사양은 모델 개요를 참조하십시오. 가격 정보는 가격 페이지를 참조하십시오.

빠른 시작 (Quickstart)

최신 Google Gen AI SDK를 설치하십시오:
pip install -U google-genai

이 가이드의 모든 코드 예제는 Interactions API를 사용합니다. Interactions API는 Gemini를 사용하여 구축하기 위한 새로운 표준 프리미티브(primitive)이며, 모든 신규 프로젝트에 권장됩니다. 이는 에이전트 워크플로(agentic workflows), 서버 측 상태 관리(server-side state management), 그리고 복잡한 멀티모달(multi-modal) 및 멀티턴(multi-turn) 대화에 최적화되어 있습니다. GenerateContent API도 지원되며, 동일한 구성 옵션과 권장 사항이 적용됩니다.

Interactions API

from google import genai
client = genai.Client()
interaction = client.interactions.create(
    model="gemini-3.5-flash",
    input="Explain how parallel agentic execution works in three sentences."
)
print(interaction.output_text)

GenerateContent API

from google import genai
client = genai.Client()
response = client.models.generate_content(
    model="gemini-3.5-flash",
    contents="How does AI work?",
)
print(response.text)

새로운 기능 (What's new)

• 지속적인 프런티어 성능(Sustained frontier performance): 대규모 에이전트 및 코딩 작업에 최적화된 우리의 가장 지능적인 Flash 모델입니다.
• 에이전트 실행(Agentic execution): 대규모 하위 에이전트 배포(Sub-agent deployment), 문제 해결, 그리고 신속한 에이전트 루프(agentic loops)를 지원합니다.

코딩 (Coding): 반복적인 코딩 사이클 (Iterative coding cycles), 신속한 탐색, 그리고 대안 경로를 테스트하고 솔루션을 동적으로 탐색하기 위한 프로토타이핑 (prototyping)을 지원합니다. 긴 호흡 (Long horizon): 대규모 멀티스텝 워크플로 (Multi-step workflows) 및 도구 사용 (tool use)을 지원합니다. 사고 보존 (Thought preservation): 모델이 멀티턴 대화 (multi-turn conversations) 전반에 걸쳐 중간 추론 과정을 자동으로 유지합니다. 별도의 API 변경은 필요하지 않습니다. 새로운 기본 노력 수준 (New default effort level): 기본 사고 노력 (thinking effort) 수준이 high에서 medium으로 변경되었습니다. 자세한 내용은 '새로운 기본 노력 수준' 섹션을 참조하세요. 개선된 낮은 사고 수준 (Improved low thinking): 단계가 적게 필요한 코딩 및 에이전트 작업 (agentic tasks)에 대해 low 수준이 크게 개선되어, 더 낮은 지연 시간 (latency)과 비용으로 강력한 품질을 제공합니다. GA 출시 (GA release): 대규모 프로덕션 사용을 위한 안정적인 모델입니다.

행동 변화 (Behavioral changes)
새로운 기본 노력 수준: medium
기본 사고 노력 수준이 Gemini 3 Flash Preview의 high에서 medium으로 변경되었습니다. medium은 더 빠르고 비용 효율적이면서도 광범위한 작업에서 매우 좋은 결과를 제공합니다. 복잡한 문제의 경우, high는 모델이 더 깊이 생각하도록 유도합니다.

노력 수준 (Effort level)

• minimal 사용 시기: 응답 속도에 최적화되었습니다. 채팅 스타일의 사용 사례, 빠른 사실 답변, 더 단순한 도구 호출에 적합합니다.
• low: 더 낮은 지연 시간과 적은 단계가 필요한 코딩 및 에이전트 작업 (agentic tasks)에 적합합니다. 또한 어느 정도의 사고가 필요한 분석 및 작문 작업에도 잘 작동합니다.
• medium (기본값): 대부분의 작업에서 최상의 품질을 제공합니다. 복잡한 코딩 및 에이전트 사용 사례에 권장됩니다.
• high: 모델의 사고 및 도구 사용 능력을 극대화합니다. 복잡한 추론, 어려운 수학, 그리고 가장 난이도가 높은 코드 또는 에이전트 작업에 가장 적합합니다. 확장된 사고와 함수 호출 (function calls)을 허용합니다.

기본값을 재정의하려면 설정(config)에서 thinking_level을 설정하세요:

from google import genai
client = genai.Client()
interaction = client.interactions.create(
    model="gemini-3.5-flash",
    input="Prove that the square root of 2 is irrational.",
    generation_config={
        "thinking_level": "high"
    },
)
print(interaction.output_text)

팁: medium으로 시작하세요. 대다수의 작업에 대해 가장 좋은 품질을 제공합니다.

강력한 품질과 함께 더 빠르고 저렴한 경험을 원한다면 low를 사용해 보세요. 복잡한 추론 (reasoning), 어려운 수학, 또는 까다로운 코딩 과제에는 high로 전환하세요. 단순한 쿼리에서 속도를 최적화하려면 minimal을 사용하세요.

사고 보존 (Thought preservation)
모델은 다회차 대화 (multi-turn conversations) 전반에 걸쳐 중간 추론 과정을 자동으로 유지합니다. 대화 기록에 존재할 경우, 추론 컨텍스트 (reasoning context)가 전달되어 반복적인 디버깅 (debugging) 및 코드 리팩토링 (code refactoring)과 같은 복잡한 다단계 작업의 성능을 향상시킵니다.

API 변경 사항 없음:
Interactions API: 사고 (Thoughts)는 이미 자동으로 보존됩니다. 동작의 변경이 없습니다.
GenerateContent API: Gemini 3.5 Flash부터, 대화 기록에 사고 시그니처 (thought signatures)가 있는 경우 모델은 모든 이전 턴의 추론 컨텍스트를 사용합니다. 이를 활성화하려면 수정되지 않은 전체 대화 기록 (사고 시그니처 포함)을 contents에 전달하세요. SDK는 이를 자동으로 처리합니다.

Gemini 3.x의 파라미터 업데이트 및 권장 사항
다음 사항은 Gemini 3.5 Flash를 포함한 모든 Gemini 3.x 모델에 적용됩니다.
temperature, top_p, top_k: 기본값을 변경하지 않는 것을 강력히 권장합니다. Gemini 3의 추론 능력은 기본 설정에 최적화되어 있습니다.
thinking_budget 대신 thinking_level을 사용하세요.
함수 호출 (Function calling) 응답 매칭: id, name, 그리고 응답 횟수 (response count)는 이전 호출과 일치해야 합니다.
멀티모달 (Multimodal) 함수 응답: 멀티모달 콘텐츠를 함수 응답 외부가 아닌 내부에 포함하세요.
함수 응답 내 인라인 지침 (Inline instructions): 함수 응답 텍스트에 추가해야 하며, 별도의 부분으로 분리하지 마세요.
불필요한 도구 호출 (tool calls) 감소: 에이전트 워크플로 (agentic workflows)에서 도구 호출을 줄이려면 더 낮은 사고 레벨 (thinking levels)을 사용하거나 시스템 지침 (system instructions)을 실험해 보세요.
코드를 업데이트하는 방법은 아래 섹션을 참조하세요.

샘플링 파라미터 (더 이상 권장되지 않음)
temperature, top_p, top_k는 모든 Gemini 3.x 모델에 대해 더 이상 권장되지 않습니다. Gemini 3의 추론 능력은 기본 설정에 최적화되어 있습니다. 모든 요청에서 이 파라미터들을 제거하세요.

⚠️ 이 파라미터들을 제거하세요 (권장되지 않음)

generation_config = {
"temperature": 0.7,
"top_p": 0.9,
"top_k": 40,
}

결정론적 (determinism) 동작을 보장하려면, 특정 사용 사례에 대한 명시적인 규칙이 포함된 시스템 지침 (system instruction)을 정의하는 것을 권장합니다.

thinking_budget (더 이상 권장되지 않음)

원시 숫자 형태의 thinking_budget 파라미터는 모든 Gemini 3.x 모델에서 더 이상 권장되지 않습니다. 대신 thinking_level 문자열 열거형 (string enum)을 사용하세요.

⚠️ 이전 (권장되지 않음)

generation_config = {
"thinking": {
"thinking_budget": 7500
},
}

✅ 이후

generation_config = {
"thinking": {
"thinking_level": "medium"
},
}

사용 가능한 값: minimal, low, medium (기본값), high.

함수 호출 (Function calling): 엄격한 응답 매칭

Interactions API는 이미 일치하지 않는 함수 응답에 대해 에러를 발생시킵니다. GenerateContent API는 아직 에러를 발생시키지 않지만, 일치하지 않는 응답은 대부분의 경우 모델이 finish_reason: STOP과 함께 빈 응답을 반환하게 만듭니다. 항상 다음 관례를 따르세요:

✅ function_result에 일치하는 call_id와 name을 포함하세요

final_interaction = client.interactions.create(
model="gemini-3.5-flash",
previous_interaction_id=interaction.id,
tools=[my_tool],
input=[{
"type": "function_result",
"name": fc_step.name,
"call_id": fc_step.id,
"result": [{
"type": "text",
"text": json.dumps(result)
}],
}],
)

멀티모달 (Multimodal) 함수 응답

클라이언트가 함수 응답 외부에 이미지를 제공하는 경우를 자주 보게 됩니다. 이는 예상치 못한 모델 동작(예: 사고 유출 (thought leakage))을 초래할 수 있으며 결과적으로 출력 품질을 저하시킬 수 있습니다. 대신 Multimodal Function Responses API 문서의 권장 사항을 따르고, 모델에 보내는 함수 응답 파트 (function response parts) 내에 멀티모달 콘텐츠를 포함하세요.

모델은 다음 턴(turn)에서 이 멀티모달 (multimodal) 콘텐츠를 처리하여 더 정보가 풍부한 응답을 생성할 수 있습니다. # ✅ 함수 응답에 멀티모달 콘텐츠 포함

final_interaction = client.interactions.create(
model="gemini-3.5-flash",
previous_interaction_id=interaction.id,
input=[
{
"type": "function_result",
"name": tool_call.name,
"call_id": tool_call.id,
"result": [
{"type": "text", "text": "instrument.jpg"},
{
"type": "image",
"mime_type": "image/jpeg",
"data": base64_image_data,
},
],
}
],
)

함수 응답 내 인라인 지침 (Inline instructions)
클라이언트가 함수 응답과 함께 추가 지침을 후속 파트 (Parts)로 제공하는 경우를 자주 보게 됩니다. 이는 예상치 못한 모델 동작 (예: 사고 유출 (thought leakage))을 유발할 수 있으며 결과적으로 출력 품질을 저하시킬 수 있습니다. 대신, 두 개의 줄바꿈으로 구분하여 함수 응답 텍스트의 끝에 모든 추가 지침을 추가하세요. # ✅ 두 개의 줄바꿈으로 구분하여 함수 응답 끝에 인라인 지침 추가

result_text = f"{json.dumps(result)}\n\n<your inline instructions>"

final_interaction = client.interactions.create(
model="gemini-3.5-flash",
previous_interaction_id=interaction.id,
tools=[my_tool],
input=[
{
"type": "function_result",
"name": fc_step.name,
"call_id": fc_step.id,
"result": [{"type": "text", "text": result_text}],
}
],
)

불필요한 도구 호출 (tool calls) 줄이기
도구 호출이 과도하게 발생하는 경우, 다음 두 가지 기술이 이를 최소화하는 데 도움이 됩니다:

1. 사고 수준 (thinking level)을 낮추는 것부터 시작하세요 (medium, low, 또는 minimal): 사고 수준이 높을수록 모델이 탐색 및 검증을 위해 더 많은 도구를 사용하도록 권장하므로, 수준을 낮추면 도구 호출을 줄일 수 있습니다.
2. 시스템 지침 (system instruction) 추가: 사고 수준을 조정한 후에도 과도한 사용이 지속된다면, 도구 사용을 제한하는 프롬프트를 고려하세요. 예: "당신에게는 <n>번의 도구 호출이라는 제한된 액션 예산이 있습니다. 이를 효율적으로 사용하세요."

마이그레이션 체크리스트

참고: 코딩 에이전트(coding agent)를 사용하여 이 마이그레이션을 자동화하세요. 기술(skills)을 지원하는 코딩 에이전트(예: Antigravity)를 사용하는 경우, Gemini Interactions API 기술을 설치하고 다음을 실행하세요: /gemini-interactions-api migrate my app to Gemini 3.5 Flash

google-genai SDK v2.0.0 이상으로 업데이트할 것을 강력히 권장합니다. 이 버전은 Interactions API에 파괴적 변경 사항(breaking changes)을 도입합니다. 자세한 내용은 파괴적 변경 사항 마이그레이션 가이드를 참조하세요.

Gemini 3 Flash Preview에서 마이그레이션

• 모델 이름 업데이트: gemini-3-flash-preview → gemini-3.5-flash
• 가격 검토: Gemini 3.5 Flash는 Gemini 3 Flash Preview보다 더 비쌉니다. 자세한 내용은 가격 페이지를 참조하세요.
• 설정(config)에서 temperature, top_p, top_k를 제거하세요 (더 이상 권장되지 않음).
• thinking_budget을 thinking_level로 교체하세요.
• 모든 FunctionResponse 파트에 id와 matching name을 추가하세요.
• 프롬프트를 테스트하세요. 기본 노력(effort) 수준이 high에서 medium으로 변경되었습니다. 품질, 속도 및 비용을 확인하세요.
• 사고 보존(Thought preservation) 기능이 이제 기본적으로 활성화됩니다. 추론 컨텍스트(Reasoning context)가 턴(turn) 간에 유지되어 성능은 향상되지만 토큰 사용량이 증가할 수 있습니다.
• 불필요한 도구 호출(tool calls)을 줄이세요: 우선 thinking_level을 medium, low 또는 minimal로 낮추는 것부터 시작하세요. 과도한 사용이 지속되면 도구 사용을 제한하는 시스템 지침(system instruction)을 추가하세요.
• Gemini 3.5 Flash는 현재 Computer Use를 지원하지 않습니다. Computer Use 워크로드의 경우 Gemini 3 Flash Preview를 계속 사용하세요.

Gemini 2.5에서 마이그레이션
위의 모든 사항에 더해 다음을 수행하세요:

• 프롬프트 단순화: 추론을 강제하기 위해 생각의 사슬(chain-of-thought) 프롬프트 엔지니어링을 사용했다면, 대신 더 단순한 프롬프트와 함께 thinking_level: "medium" 또는 "high"를 시도해 보세요.
• PDF 및 미디어 워크로드 테스트: 밀집된 문서 파싱(parsing)을 위해 특정 동작에 의존했다면, 정확도가 유지되는지 확인하기 위해 media_resolution_high 설정을 테스트하세요. Gemini 3 기본값으로 마이그레이션하면 PDF의 토큰 사용량은 증가할 수 있지만 비디오의 사용량은 감소할 수 있습니다. 요청이 컨텍스트 창(context window)을 초과하는 경우 media_resolution을 명시적으로 줄이세요. 자세한 내용은 미디어 해상도 문서를 참조하세요.
• 결합된 도구 사용(combined tool use)을 활용하세요.

Google Search, URL context, code execution (코드 실행), 그리고 custom functions (사용자 정의 함수)를 동일한 요청 내에서 사용할 수 있습니다. 멀티모달 함수 응답(multimodal function responses)을 사용하는 경우, 멀티모달 콘텐츠를 함수 응답과 나란히 두지 말고 함수 응답 파트(function response parts) 내부로 이동시키세요. 함수 응답과 함께 인라인 지침(inline instructions)을 사용하는 경우, 이를 별도의 파트로 만들지 말고 두 개의 줄바꿈으로 구분하여 함수 응답 텍스트 끝에 추가하세요. Gemini 3.x에서는 이미지 세그멘테이션(Image segmentation)을 지원하지 않습니다. 세그멘테이션 워크로드의 경우, thinking 기능을 끈 상태의 Gemini 2.5 Flash 또는 Gemini Robotics-ER 1.6을 계속 사용하세요. Gemini 3 제품군(family)의 특징은 Gemini 3.5 Flash가 Computer Use를 제외한 Gemini 3 제품군의 모든 기능을 상속받는다는 점입니다. Gemini 3에서 도입되어 계승된 기능들은 다음과 같습니다.