Gemini 3.1 Pro Customtools란 무엇인가요? 5분 만에 이해하는 사용자 정의 도구 우선 모델 사용법

많은 개발자분들이 gemini-3.1-pro-preview-customtools라는 모델명을 보고 당황하시곤 합니다. customtools는 무슨 뜻일까요? 표준 모델인 gemini-3.1-pro-preview와는 무엇이 다를까요? 이번 글에서 5분 만에 완벽하게 정리해 드릴게요.

핵심 가치: 이 글을 읽고 나면 표준 버전과 customtools 버전 중 언제 무엇을 사용해야 하는지, 그리고 에이전트(Agent) 개발 시 어떤 모델을 선택하는 것이 올바른지 명확히 알게 되실 겁니다.

Gemini 3.1 Pro Customtools란 무엇인가요?

한 줄 요약

gemini-3.1-pro-preview-customtools는 구글이 2026년 2월 19일 표준 버전인 Gemini 3.1 Pro와 함께 출시한 전용 변체(Variant) 모델입니다. 표준 버전과의 핵심적인 차이점은 딱 하나입니다. 바로 기본 bash 명령을 실행하는 대신, 사용자가 등록한 '사용자 정의 도구(Custom Tools)'를 우선적으로 사용하도록 설계되었다는 점이죠.

구글 공식 변경 로그(Changelog)에서는 다음과 같이 설명하고 있습니다.

bash와 도구를 혼합하여 사용하는 사용자를 위해, 사용자 정의 도구의 우선순위를 더 잘 지정하는 별도의 엔드포인트 gemini-3.1-pro-preview-customtools를 출시했습니다.

왜 이런 변체 모델이 필요한가요?

에이전트(Agent) 개발 시, 개발자는 보통 모델에게 두 가지 유형의 능력을 부여합니다.

1. Bash/코드 실행: 모델이 직접 쉘(shell) 명령을 실행하도록 함
2. 사용자 정의 도구 (Custom Tools): 개발자가 정의한 구조화된 함수 (예: view_file, search_code, create_pr 등)

여기서 어떤 문제가 발생할까요? 표준 버전의 Gemini 3.1 Pro는 가끔 '편한 길'을 택하려 합니다. 개발자가 정성껏 설계한 사용자 정의 도구를 건너뛰고, 그냥 bash 명령으로 작업을 끝내버리는 것이죠. 예를 들어, view_file이라는 도구를 등록해 뒀는데도 모델이 도구를 호출하는 대신 cat filename.py를 직접 실행해서 도구를 우회해 버리는 식입니다.

이는 다음과 같은 상황에서 문제가 될 수 있습니다.

• 사용자 정의 도구에 권한 제어나 로그 기록 기능이 포함된 경우
• 사용자 정의 도구의 반환 형식이 구조화되어 있어 후속 처리가 용이한 경우
• 사용자 정의 도구가 외부 시스템(데이터베이스, API 등)과 연결되어 있는 경우

customtools 변체 모델은 바로 이 문제를 해결하기 위해 탄생했습니다. 모델이 개발자가 등록한 도구를 최우선으로 선택하도록 강제하는 것이죠.

Gemini 3.1 Pro 표준 버전 vs Customtools 버전 핵심 차이점

🎯 핵심 요약: 두 모델의 '지능 수준'은 완전히 동일합니다. 차이점은 'bash를 쓸 것인가, 아니면 내가 등록한 도구를 쓸 것인가'라는 선택의 기로에서, Customtools 버전이 여러분이 만든 사용자 정의 도구를 더 우선적으로 선택한다는 점입니다.

어떤 상황에서 Gemini 3.1 Pro Customtools가 필요할까요?

Customtools가 필요한 상황

Customtools가 필요 없는 상황

구글의 공식 권장 사항

구글은 Gemini 3 개발자 가이드의 FAQ에서 다음과 같이 명확하게 밝히고 있습니다.

If you are using gemini-3.1-pro-preview and the model ignores your custom tools in favor of bash commands, try the gemini-3.1-pro-preview-customtools model instead.

번역: 만약 gemini-3.1-pro-preview를 사용 중인데 모델이 여러분의 사용자 정의 도구를 무시하고 bash 명령어를 우선적으로 사용한다면, 대신 gemini-3.1-pro-preview-customtools 모델을 사용해 보세요.

Gemini 3.1 Pro Customtools API 호출 방법

기본 호출: 표준 버전과 완전히 동일해요

import openai

client = openai.OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1"  # APIYI 통합 인터페이스
)

# 모델 이름만 바꾸면 되고, 나머지 코드는 완전히 똑같아요
response = client.chat.completions.create(
    model="gemini-3.1-pro-preview-customtools",
    messages=[
        {"role": "user", "content": "帮我查看项目中的 main.py 文件内容"}
    ]
)
print(response.choices[0].message.content)

사용자 정의 도구를 포함한 에이전트 호출

customtools 버전의 진정한 위력은 function calling과 함께 사용할 때 발휘돼요.

import openai
import json

client = openai.OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1"  # APIYI 통합 인터페이스
)

# 사용자 정의 도구 정의
tools = [
    {
        "type": "function",
        "function": {
            "name": "view_file",
            "description": "查看指定文件的内容",
            "parameters": {
                "type": "object",
                "properties": {
                    "file_path": {
                        "type": "string",
                        "description": "文件路径"
                    }
                },
                "required": ["file_path"]
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "search_code",
            "description": "在代码库中搜索关键词",
            "parameters": {
                "type": "object",
                "properties": {
                    "query": {
                        "type": "string",
                        "description": "搜索关键词"
                    },
                    "file_pattern": {
                        "type": "string",
                        "description": "文件匹配模式,如 *.py"
                    }
                },
                "required": ["query"]
            }
        }
    }
]

# customtools 버전은 위에서 정의한 도구를 우선적으로 사용해요
response = client.chat.completions.create(
    model="gemini-3.1-pro-preview-customtools",
    messages=[
        {"role": "user", "content": "帮我在项目中找到所有包含 TODO 的 Python 文件"}
    ],
    tools=tools
)

# 모델이 직접 grep을 실행하는 대신 search_code 도구를 호출하게 됩니다
tool_call = response.choices[0].message.tool_calls[0]
print(f"工具: {tool_call.function.name}")
print(f"参数: {tool_call.function.arguments}")

import openai
import json

client = openai.OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1"
)

tools = [
    {
        "type": "function",
        "function": {
            "name": "view_file",
            "description": "查看指定文件的内容",
            "parameters": {
                "type": "object",
                "properties": {
                    "file_path": {"type": "string", "description": "文件路径"}
                },
                "required": ["file_path"]
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "search_code",
            "description": "在代码库中搜索关键词",
            "parameters": {
                "type": "object",
                "properties": {
                    "query": {"type": "string", "description": "搜索关键词"},
                    "file_pattern": {"type": "string", "description": "文件匹配模式"}
                },
                "required": ["query"]
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "edit_file",
            "description": "编辑文件中的指定内容",
            "parameters": {
                "type": "object",
                "properties": {
                    "file_path": {"type": "string", "description": "文件路径"},
                    "old_content": {"type": "string", "description": "要替换的旧内容"},
                    "new_content": {"type": "string", "description": "新内容"}
                },
                "required": ["file_path", "old_content", "new_content"]
            }
        }
    }
]

# 模拟工具执行
def execute_tool(name, args):
    """实际项目中替换为真实的工具实现"""
    if name == "view_file":
        return f"文件内容: {args['file_path']} (模拟)"
    elif name == "search_code":
        return f"搜索 '{args['query']}' 的结果: 找到 3 处匹配 (模拟)"
    elif name == "edit_file":
        return f"已将 {args['file_path']} 中的内容替换 (模拟)"
    return "未知工具"

# Agent 主循环
messages = [{"role": "user", "content": "找到项目中所有 TODO 注释并修复它们"}]
max_turns = 5

for turn in range(max_turns):
    response = client.chat.completions.create(
        model="gemini-3.1-pro-preview-customtools",
        messages=messages,
        tools=tools
    )

    msg = response.choices[0].message
    messages.append(msg)

    if msg.tool_calls:
        for tc in msg.tool_calls:
            args = json.loads(tc.function.arguments)
            result = execute_tool(tc.function.name, args)
            messages.append({
                "role": "tool",
                "tool_call_id": tc.id,
                "content": result
            })
            print(f"[Turn {turn+1}] 调用: {tc.function.name}({args})")
    else:
        print(f"[完成] {msg.content[:200]}")
        break

🚀 빠른 시작: APIYI(apiyi.com) 플랫폼을 통해 표준 버전과 customtools 버전 모두 동일한 API 키를 사용할 수 있어요. 모델 파라미터만 수정하면 바로 전환할 수 있어, 어떤 버전이 여러분의 에이전트에 더 적합한지 A/B 테스트하기에 아주 좋습니다.

Gemini 3.1 Pro Customtools와 에이전트 프레임워크의 관계

주요 에이전트 프레임워크 적합성

customtools 버전은 다음과 같은 에이전트 개발 시나리오에서 특히 가치가 높아요.

Gemini 3.1 Pro Customtools와 표준 버전의 동작 비교

차이점을 더 직관적으로 이해하기 위해 구체적인 예를 살펴볼까요?

동일한 요청에 대한 두 모델의 서로 다른 반응

사용자 요청: "src/main.py 파일의 내용을 확인해 줘"

등록된 도구: view_file(file_path: string)

두 방식 모두 파일 내용을 가져올 수는 있지만, 커스텀 도구 호출을 통하면 다음과 같은 장점이 있습니다.

1. 권한 제어: view_file 도구에서 경로가 화이트리스트 내에 있는지 확인할 수 있습니다.
2. 포맷팅된 출력: 도구가 가공되지 않은 텍스트가 아닌 구조화된 JSON을 반환할 수 있습니다.
3. 로그 감사: 도구 호출 내역이 프레임워크에 의해 자동으로 기록됩니다.
4. 오류 처리: bash 오류 메시지 대신 도구에서 친절한 오류 메시지를 제공할 수 있습니다.

구글 Gemini 도구 호출 모델의 진화

Customtools는 구글이 도구 호출을 위해 처음으로 제공하는 전용 모델 변체입니다. 다음은 구글 Gemini 도구 관련 모델의 전체 맵입니다.

이는 구글이 하나의 범용 모델로 모든 시나리오를 커버하는 대신, 모델을 사용 시나리오에 따라 세분화하고 있음을 보여줍니다. 앞으로 더 많은 전용 변체가 등장할 것으로 보입니다.

자주 묻는 질문(FAQ)

요약: Gemini 3.1 Pro Customtools 퀵 가이드

한 줄 요약: gemini-3.1-pro-preview-customtools는 Gemini 3.1 Pro의 '에이전트 전용 모드'입니다. 모델이 직접 bash를 실행하기보다 여러분이 등록한 도구를 더 잘 따르도록 만듭니다. 가격과 지능은 그대로이면서 도구 선택 전략만 에이전트 개발에 더 적합하게 맞춘 것이죠.

APIYI(apiyi.com) 플랫폼을 통해 두 버전을 동시에 연동하여 실제 프로젝트에서 A/B 테스트를 거친 후 가장 적합한 것을 선택하시길 추천합니다. 에이전트 개발자에게는 customtools 버전이 거의 항상 더 나은 선택이 될 것입니다.

참고 자료

1. Google AI 문서: Gemini 3.1 Pro Preview 모델 페이지

   • 링크: ai.google.dev/gemini-api/docs/models/gemini-3.1-pro-preview
   • 설명: 표준 버전과 customtools 버전의 비교 설명 포함

2. Gemini API Changelog: 2026년 2월 19일 업데이트

   • 링크: ai.google.dev/gemini-api/docs/changelog
   • 설명: customtools 변형 모델의 최초 출시 기록

3. Gemini 3 개발자 가이드: FAQ의 도구 선택 제안

   • 링크: ai.google.dev/gemini-api/docs/gemini-3
   • 설명: 표준 버전에서 customtools 버전으로 전환해야 하는 시기

4. Google AI 문서: Function Calling 가이드

   • 링크: ai.google.dev/gemini-api/docs/function-calling
   • 설명: Gemini 모델의 함수 호출(Function Calling) API 상세 설명

📝 작성자: APIYI Team | 기술 교류는 APIYI apiyi.com을 방문해 주세요.
📅 업데이트 날짜: 2026년 2월 20일
🏷️ 키워드: gemini-3.1-pro-preview-customtools, 사용자 정의 도구, Agent 개발, function calling, 도구 호출, API 호출