Gemini 3.1 Pro로 AI 에이전트 만들기 — 실무자가 바로 쓰는 자동화 워크플로우 가이드

2026년 2월 19일, 구글이 Gemini 3.1 Pro를 퍼블릭 프리뷰로 조용히 공개했습니다. 발표 자체는 조용했지만, 실제 스펙을 뜯어보면 LLM 에이전트 개발 패러다임이 또 한 번 뒤집힐 수준입니다. 100만 토큰 컨텍스트에 thinking_level 파라미터, 그리고 멀티턴 추론 상태를 유지하는 thoughtSignature까지 — 단순 챗봇 수준을 넘어 자율 에이전트 설계가 본격적으로 가능해졌다는 신호입니다. 지금 당장 실무에 적용할 수 있는 AI 에이전트 구현 가이드를 정리해봤습니다.

📌 이 글의 핵심 3줄

• thinking_level 파라미터로 추론 깊이를 제어 — CoT 프롬프트 엔지니어링 시대 종료
• 멀티턴 에이전트 안정성의 핵심은 thoughtSignature 상태 관리
• Temperature는 반드시 1.0 유지 — 낮추면 오히려 추론 성능 저하

왜 Gemini 3.1 Pro인가 — LLM 활용의 새로운 기준점

기존 LLM 활용 방식은 프롬프트 엔지니어링에 과도하게 의존했습니다. "Step 1: 먼저 문제를 분석해라, Step 2: 서브태스크로 나눠라..." 같은 Chain-of-Thought(CoT) 지시를 개발자가 직접 설계해야 했죠. 모델이 멍청한 게 아니라, 추론 과정을 프롬프트로 억지로 끌어내야 했던 구조적 한계였습니다.

Gemini 3.1 Pro는 이 구조를 뒤집습니다. 모델 자체가 추론 깊이를 조절하는 메커니즘을 내장했고, 개발자는 파라미터 하나로 그 강도를 제어하면 됩니다. git에서 커밋 메시지 쓰듯 간단하게, 그런데 결과는 훨씬 정교하게.

thinking_level 파라미터 — 추론 강도를 코드로 제어하기

thinking_level은 low / medium / high 세 단계로 설정합니다. 간단한 데이터 추출엔 low, 멀티스텝 계획 수립이나 복잡한 코드 리팩토링엔 high를 씁니다. 비용도 추론 깊이에 비례하니 태스크 유형별로 분리하는 게 실무 최적화의 첫 번째 포인트입니다.

import google.generativeai as genai

genai.configure(api_key="YOUR_API_KEY")

# 복잡한 자동화 워크플로우 → thinking_level: high
model = genai.GenerativeModel(
    model_name="gemini-3.1-pro",
    generation_config={
        "temperature": 1.0,       # 반드시 1.0 유지
        "thinking_level": "high", # low | medium | high
    }
)

response = model.generate_content(
    "다음 Python 레거시 코드를 분석하고, "
    "테스트 커버리지를 80% 이상 확보할 수 있도록 "
    "리팩토링 계획을 수립한 뒤 실행하라.\n\n"
    + legacy_code
)

print(response.text)

실무에서 느낀 건 — high 설정에서는 같은 프롬프트라도 응답 품질 차이가 확연합니다. 엣지 케이스를 스스로 잡아내고, 예외 처리까지 제안합니다. 반면 단순 번역이나 요약 태스크에 high를 쓰면 비용만 올라가고 속도만 느려지니 태스크 라우팅 로직을 별도로 두는 걸 권장합니다.

thoughtSignature로 Stateful 에이전트 설계하기

AI 에이전트 개발에서 가장 흔한 실패 원인은 맥락 소실입니다. 에이전트가 외부 도구(API 호출, DB 조회 등)를 실행하고 돌아오면, 이전에 "왜 이 도구를 호출했는지"를 잊어버리는 현상이죠. Docker 컨테이너로 치면 볼륨 마운트 없이 재시작하는 것과 같습니다 — 상태가 날아갑니다.

Gemini 3.1 Pro는 이를 thoughtSignature로 해결합니다. 추론 과정을 암호화된 토큰으로 직렬화해서, 다음 턴 요청 시 다시 주입하면 에이전트가 중단 지점부터 정확히 이어갑니다. 멀티턴 자동화 워크플로우의 안정성이 이 메커니즘에 달려 있습니다.

def run_agent_turn(user_message: str, thought_signature: str = None):
    contents = []

    # 이전 사고 서명이 있으면 컨텍스트에 포함
    if thought_signature:
        contents.append({
            "role": "model",
            "parts": [{"thought_signature": thought_signature}]
        })

    contents.append({
        "role": "user",
        "parts": [{"text": user_message}]
    })

    response = model.generate_content(contents)

    # 다음 턴을 위해 thoughtSignature 저장
    next_signature = None
    for part in response.candidates[0].content.parts:
        if hasattr(part, "thought_signature"):
            next_signature = part.thought_signature

    return response.text, next_signature

# 에이전트 루프
signature = None
for step in workflow_steps:
    result, signature = run_agent_turn(step, signature)
    print(f"[Step] {result}")

⚠️ 실무 주의사항

thoughtSignature를 누락하면 에이전트는 도구 실행 결과를 받아도 "내가 왜 이걸 요청했지?"를 모릅니다. 특히 LangGraph나 CrewAI와 통합할 때 상태 저장소(State Store)에 시그니처를 반드시 포함시켜야 합니다. 이걸 빼먹으면 디버깅 지옥이 시작됩니다.

자동화 워크플로우 실전 적용 — 에이전트 아키텍처 설계

실무에서 Gemini 3.1 Pro 기반 에이전트를 설계할 때 검증된 패턴은 다음과 같습니다.

• 태스크 라우터: 요청 복잡도를 분류해 thinking_level을 동적으로 할당. 단순 조회는 low, 다단계 실행 계획은 high.
• Tool Registry: Function Calling으로 등록한 도구 목록을 에이전트가 스스로 선택하도록 위임. 개발자는 도구만 만들고, 호출 순서는 모델이 결정.
• Signature Store: Redis 또는 인메모리 딕셔너리로 세션별 thoughtSignature 관리. 에이전트 재시작 시에도 맥락 복원 가능.
• Fallback 레이어: 에이전트가 3회 이상 동일 도구를 반복 호출하면 인간 승인 단계로 에스컬레이션. 무한 루프 방어.

이 구조에서 LangGraph와 Gemini 3.1 Pro를 결합하면, 그래프 노드 단위로 thoughtSignature를 전달하는 Stateful 에이전트를 비교적 적은 코드로 구현할 수 있습니다. 개인적으로는 CrewAI보다 LangGraph 조합이 Gemini의 추론 상태 관리와 더 자연스럽게 맞는다고 느꼈습니다.

전망 — 프롬프트 엔지니어가 아닌 에이전트 엔지니어의 시대

Gemini 3.1 Pro가 보여주는 방향은 명확합니다. 모델이 똑똑해질수록, 개발자의 역할은 "어떻게 생각하라"에서 "무엇을 할 수 있나"를 설계하는 쪽으로 이동합니다. 세밀한 CoT 프롬프트를 짜는 능력보다, 도구를 잘 설계하고 에이전트의 상태를 안정적으로 관리하는 능력이 더 중요해지고 있습니다.

멀티모달 측면에서도 텍스트-코드-이미지-비디오를 동시에 처리하는 에이전트가 영상 분석 자동화, 복합 데이터 파이프라인 등에서 빠르게 상용화될 것입니다. 지금 Gemini 3.1 Pro 기반 에이전트를 실험해두는 것, 내년 경쟁력 차이를 만드는 투자입니다.

한 줄 요약

Gemini 3.1 Pro 에이전트 개발의 핵심은 세 가지 — thinking_level로 추론 제어, thoughtSignature로 상태 유지, Temperature 1.0 고정. 프롬프트를 복잡하게 짜는 시대는 끝났습니다.

...