gemini-3.1-pro-preview 和 gemini-3.1-pro-preview-customtools 是谷歌同一天发布的两个模型端点,价格相同、推理能力相同,但行为截然不同。本文从 6 个关键维度 对比两者差异,帮你在 Agent 开发中做出正确选择。
核心价值: 看完本文,你将清楚知道什么场景该用标准版、什么场景该用 customtools 版,避免在 Agent 开发中踩坑。
先说结论: 什么时候用哪个版本
如果你赶时间,直接看这个表:
| 你的场景 | 选哪个 | 原因 |
|---|---|---|
| 纯对话/问答 | 标准版 | 质量最稳定 |
| 文本翻译/分析 | 标准版 | 不涉及工具调用 |
| 代码生成 (无工具) | 标准版 | 直接输出代码 |
| 编码助手 (有 view_file 等工具) | customtools 版 | 确保工具被正确调用 |
| DevOps Agent (bash + 自定义工具) | customtools 版 | 避免模型总用 bash 绕过工具 |
| MCP 工作流 | customtools 版 | 工具优先级保障 |
| 不确定? | 先用标准版,遇到工具被跳过就换 customtools | 谷歌官方建议 |
🎯 谷歌官方原话: "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."
차이점 1: 도구 호출 우선순위 — 핵심적인 차이
이것이 두 버전 사이의 유일하고도 본질적인 차이점이에요. 모델이 'bash 실행'과 '사용자 정의 도구'라는 두 가지 능력을 동시에 가지고 있을 때, 어떤 것을 선택할까요?
표준 버전의 문제: 몰래 bash를 사용함
표준 버전에 view_file 도구를 등록해 두었더라도, 파일을 확인해달라고 요청하면 다음과 같이 동작할 수 있어요.
사용자: "src/main.py의 내용을 확인해줘"
표준 버전 동작: bash 명령어 `cat src/main.py` 실행 ← 여러분이 만든 도구를 건너뛰어 버려요!
Hacker News의 개발자 토론에서도 여러 개발자가 유사한 문제를 보고했습니다.
- "모델이 제공된 텍스트 편집 도구를 사용하는 대신 이상한 방식으로 파일을 편집하려고 합니다."
- "도구 호출 능력이 떨어지고, 자꾸 우회하려고 합니다."
- "루프에 빠져서 앞으로 나아가지 못하는 경우가 많습니다."
customtools 버전의 수정 사항: 여러분의 도구를 존중함
사용자: "src/main.py의 내용을 확인해줘"
customtools 버전 동작: view_file("src/main.py") 호출 ← 등록한 도구를 제대로 사용해요 ✓
| 시나리오 | 표준 버전 동작 | customtools 버전 동작 |
|---|---|---|
| 파일 확인 | cat src/main.py (bash) |
view_file("src/main.py") |
| 코드 검색 | grep -r "TODO" *.py (bash) |
search_code("TODO", "*.py") |
| 파일 편집 | sed -i 's/old/new/' file (bash) |
edit_file(path, old, new) |
| 파일 목록 나열 | ls -la src/ (bash) |
list_files("src/") |
| 테스트 실행 | pytest tests/ (bash) |
run_tests("tests/") |
차이점 2: 범용 품질 성능 — 표준 버전이 더 안정적임
구글은 공식 문서에서 다음과 같은 중요한 경고를 명시했습니다.
"gemini-3.1-pro-preview-customtools는 사용자 정의 도구와 bash를 사용하는 에이전트 워크플로우에 최적화되어 있지만, 이러한 도구의 이점을 얻지 못하는 일부 사용 사례에서는 품질 변동이 나타날 수 있습니다."
즉, customtools 버전은 다음과 같은 상황에서 표준 버전보다 덜 안정적일 수 있다는 뜻이에요.
| 시나리오 유형 | 표준 버전 품질 | customtools 버전 품질 | 설명 |
|---|---|---|---|
| 텍스트 전용 대화 | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | 미세한 변동 가능성 있음 |
| 긴 글 쓰기 | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | 도구를 사용하지 않는 경우 표준 버전이 더 우수함 |
| 수학적 추론 | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | 핵심 추론 능력은 동일함 |
| 코드 생성 (도구 미사용) | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | 표준 버전이 약간 더 우수함 |
| 에이전트 + 사용자 정의 도구 | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ | customtools 버전이 훨씬 더 우수함 |
| bash + 사용자 정의 도구 혼용 | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ | customtools 버전의 핵심 강점 |
핵심 포인트: customtools 버전은 '더 강력한' 모델이라기보다 '도구 호출에 더 집중하도록' 튜닝된 버전이에요. 도구를 사용하지 않는 상황에서는 오히려 표준 버전이 더 나을 수 있습니다.
💡 선택 가이드: 만약 여러분의 애플리케이션 요청 중 50% 이상이 도구 호출과 관련이 없다면, 기본적으로 표준 버전을 유지하고 에이전트 워크플로우에서만 customtools 버전으로 전환하는 것을 추천해요. APIYI(apiyi.com)를 사용하면 코드 내에서 상황에 따라 model 파라미터를 동적으로 변경할 수 있습니다.
차이점 3: 모델 파라미터 및 사양 — 완전히 동일함
두 버전은 '하드웨어 사양' 측면에서 완전히 일치합니다.
| 사양 | 표준 버전 | customtools 버전 |
|---|---|---|
| 입력 컨텍스트 | 1,048,576 tokens | 1,048,576 tokens |
| 최대 출력 | 65,536 tokens | 65,536 tokens |
| 입력 가격 (≤200K) | $2.00 / 1M tokens | $2.00 / 1M tokens |
| 입력 가격 (>200K) | $4.00 / 1M tokens | $4.00 / 1M tokens |
| 출력 가격 (≤200K) | $12.00 / 1M tokens | $12.00 / 1M tokens |
| 출력 가격 (>200K) | $18.00 / 1M tokens | $18.00 / 1M tokens |
| 컨텍스트 캐싱 | $0.20-$0.40 / 1M | $0.20-$0.40 / 1M |
| ARC-AGI-2 | 77.1% | 동일 (별도 발표되지 않음) |
| SWE-Bench | 80.6% | 동일 (별도 발표되지 않음) |
| GPQA Diamond | 94.3% | 동일 (별도 발표되지 않음) |
| 사고 시스템 | 낮음 / 중간 / 높음 | 낮음 / 중간 / 높음 |
| 멀티모달 입력 | 텍스트/이미지/오디오/비디오 | 텍스트/이미지/오디오/비디오 |
핵심: 구글은 customtools 버전에 대해 별도의 벤치마크 데이터를 발표하지 않았습니다. 기본 모델이 동일하기 때문이죠. 차이점은 오직 도구 호출(Tool Calling) 동작의 튜닝 여부에만 있습니다.
차이점 4: API 호출 방식 — model 파라미터만 다름
코드 예시: 표준 버전과 customtools 버전 간의 간편한 전환
import openai
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"]
}
}
}]
# 표준 버전: 도구를 건너뛸 수 있음
resp_standard = client.chat.completions.create(
model="gemini-3.1-pro-preview",
messages=[{"role": "user", "content": "src/main.py 확인해줘"}],
tools=tools
)
# customtools 버전: 도구 사용을 우선함
resp_custom = client.chat.completions.create(
model="gemini-3.1-pro-preview-customtools",
messages=[{"role": "user", "content": "src/main.py 확인해줘"}],
tools=tools
)
# 동작 차이 비교
print("표준 버전:", resp_standard.choices[0].message)
print("customtools:", resp_custom.choices[0].message)
차이점 5: 개발자 실제 경험 — 커뮤니티 피드백
Hacker News와 GitHub의 개발자 피드백을 통해 에이전트(Agent) 시나리오에서 표준 버전이 겪는 문제점들을 살펴볼 수 있습니다.
에이전트 시나리오에서의 표준 버전 문제점
Hacker News 토론에서 발췌한 개발자 피드백입니다:
| 문제 설명 | 원인 분석 | customtools로 해결 가능한가 |
|---|---|---|
| 「모델이 제공된 텍스트 편집 도구 대신 이상한 방식으로 파일을 수정하려고 함」 | 표준 버전은 bash를 선호하는 경향이 있음 | 해결 가능 — 사용자 정의 도구를 우선적으로 사용 |
| 「도구 호출 능력이 떨어지고 자꾸 우회함」 | 도구 우선순위가 낮음 | 해결 가능 — 도구 우선순위 향상 |
| 「루프에 빠져서 앞으로 나아가지 못함」 | 도구와 bash 사이의 전환 혼란 | 부분 해결 — 도구 경로가 더 명확해짐 |
| 「사고(Thinking) 토큰을 대량으로 소모한 뒤 엉뚱한 결과물을 내놓음」 | 모델 추론과 도구 선택의 충돌 | 부분 해결 — 도구 선택의 확실성 증가 |
| 「계속해서 '계속해' 또는 '완료해'라고 말해줘야 함」 | 에이전트 메인 루프 문제 | 해결 불가 — 이는 모델의 일반적인 문제 |
GitHub Copilot의 사례
GitHub Copilot 팀은 Gemini 3.1 Pro를 통합하면서 다음과 같이 언급했습니다:
"모델은 '편집 후 테스트(edit-then-test)' 루프에서 뛰어난 성능을 보이며, 높은 도구 정밀도를 바탕으로 더 적은 도구 호출만으로 목표를 달성합니다."
이는 올바른 도구 호출 프레임워크가 갖춰진다면 Gemini 3.1 Pro의 에이전트 능력이 매우 강력하다는 것을 보여줍니다. customtools 버전은 바로 이러한 「높은 도구 정밀도」를 더 안정적으로 끌어내기 위해 설계되었습니다.
🚀 실전 권장사항: 코딩 어시스턴트류의 제품을 개발 중이라면, 표준 버전의 도구 건너뛰기 문제를 피하기 위해 처음부터
customtools버전을 사용하는 것을 추천합니다. APIYI(apiyi.com)를 통해 빠르게 배포하고 테스트해 볼 수 있습니다.
차이점 6: 적합한 에이전트 프레임워크 및 코딩 도구
| 도구/프레임워크 | 권장 버전 | 이유 |
|---|---|---|
| 자체 개발 에이전트 (사용자 정의 도구 포함) | customtools | 도구가 정확하게 호출되도록 보장 |
| Claude Code류 제품 | customtools | view_file, edit_file 등의 도구 필요 |
| Cursor | customtools | IDE 도구 세트의 우선순위 보장 필요 |
| GitHub Copilot | 이미 내장 최적화됨 | Copilot이 자체적으로 도구 호출을 최적화함 |
| LangChain Agent | customtools | 프레임워크에 등록된 도구(tools)가 우선적으로 호출되어야 함 |
| MCP 프로토콜 에이전트 | customtools | MCP 도구의 우선순위 필요 |
| 순수 RAG 애플리케이션 | 표준 버전 | 일반적으로 bash와 도구 간의 충돌이 발생하지 않음 |
| 채팅 애플리케이션 | 표준 버전 | 도구 호출을 사용하지 않음 |
| 콘텐츠 생성 API | 표준 버전 | 순수 텍스트 출력 위주 |
표준 버전에서 customtools 버전으로 전환해야 할지 판단하는 방법
빠른 진단 체크리스트
표준 버전을 사용하면서 다음과 같은 상황을 겪고 있다면 customtools 버전으로 전환해야 합니다.
- 모델이
view_file을 호출하는 대신cat명령어를 직접 실행할 때 - 모델이
search_code를 호출하는 대신grep을 실행할 때 - 모델이
edit_file을 호출하는 대신sed를 실행할 때 - 도구 호출 로그에 bash 명령어가 빈번하게 나타날 때
- 모델의 도구 호출 성공률이 예상보다 낮을 때 (50% 미만)
- 모델이 사용 가능한 커스텀 도구가 있다는 사실을 '모르는' 것처럼 보일 때
위 항목 중 2개 이상 해당된다면 즉시 gemini-3.1-pro-preview-customtools로 전환하는 것을 권장합니다.
심화: 코드에서 두 버전을 동적으로 전환하기
가장 좋은 방법은 '둘 중 하나'를 고정하는 것이 아니라, 요청 유형에 따라 동적으로 라우팅하는 것입니다.
import openai
client = openai.OpenAI(
api_key="YOUR_API_KEY",
base_url="https://api.apiyi.com/v1" # APIYI 통합 인터페이스
)
def smart_route(messages, tools=None):
"""도구 필요 여부에 따라 모델 버전을 동적으로 선택합니다."""
if tools and len(tools) > 0:
# 커스텀 도구가 있는 경우 → 도구 호출을 보장하기 위해 customtools 버전 사용
model = "gemini-3.1-pro-preview-customtools"
else:
# 단순 대화/추론인 경우 → 안정적인 품질을 위해 표준 버전 사용
model = "gemini-3.1-pro-preview"
return client.chat.completions.create(
model=model,
messages=messages,
tools=tools
)
# 시나리오 1: 단순 추론 → 표준 버전 자동 선택
resp1 = smart_route(
messages=[{"role": "user", "content": "양자 얽힘의 원리에 대해 설명해줘"}]
)
# 시나리오 2: 에이전트 워크플로우 → customtools 버전 자동 선택
tools = [{"type": "function", "function": {
"name": "view_file",
"description": "파일 내용 보기",
"parameters": {"type": "object", "properties": {
"path": {"type": "string"}
}, "required": ["path"]}
}}]
resp2 = smart_route(
messages=[{"role": "user", "content": "config.py 파일 확인해줘"}],
tools=tools
)
💰 비용 팁: 두 버전의 가격은 완전히 동일하므로, 동적 라우팅을 사용해도 추가 비용이 발생하지 않습니다. APIYI(apiyi.com)의 통합 인터페이스를 통해 모델 이름 문자열 하나만 바꾸면 간편하게 전환할 수 있습니다.
자주 묻는 질문
Q1: customtools 버전이 더 비싼가요?
아니요. 두 버전의 가격은 완전히 동일합니다. 입력 $2.00 / 1M tokens, 출력 $12.00 / 1M tokens입니다. APIYI(apiyi.com) 플랫폼을 통해 호출하면, 하나의 API Key로 두 버전을 모두 사용할 수 있습니다.
Q2: function calling만 사용하고 bash 실행 권한은 주지 않았는데, customtools 버전이 필요한가요?
보통은 필요하지 않습니다. customtools 버전은 주로 'bash와 커스텀 도구가 공존할 때, 모델이 bash를 우선적으로 선택하는 문제'를 해결하기 위해 만들어졌습니다. 만약 여러분의 에이전트(Agent)에 bash 실행 능력이 없다면, 표준 버전의 도구 호출(tool calling)만으로도 충분히 안정적입니다.
Q3: customtools 버전의 ‘품질 변동’은 구체적으로 무엇인가요?
구글에서 구체적인 데이터를 공개하지는 않았습니다. 개발자들의 피드백에 따르면, 주로 도구를 사용하지 않는 일반 대화나 장문 생성 등의 시나리오에서 출력의 일관성이나 문체가 약간 달라질 수 있다고 합니다. 하지만 도구 사용이 빈번한 에이전트 시나리오에서는 오히려 customtools 버전의 전체적인 품질이 더 좋게 느껴집니다.
Q4: 두 버전을 동시에 사용할 수 있나요?
물론입니다. 코드 내에서 요청 유형에 따라 동적으로 라우팅하는 방식을 추천드려요. 도구 호출이 포함된 요청은 customtools 버전으로 보내고, 순수 텍스트 요청은 표준 버전으로 보내는 식이죠. APIYI(apiyi.com)의 통합 인터페이스를 사용하면 model 파라미터만 바꾸면 되므로 매우 간단합니다.
요약: 표준 버전 vs Customtools 6가지 항목 비교 체크리스트
| # | 비교 항목 | 표준 버전 | customtools 버전 | 선택 제안 |
|---|---|---|---|---|
| 1 | 도구 우선순위 | bash를 우선할 수 있음 | 커스텀 도구 우선 | 에이전트라면 customtools |
| 2 | 범용 품질 | 모든 시나리오에서 균형 잡힘 | 비도구 시나리오에서 미세한 변동 | 일반 작업은 표준 버전 |
| 3 | 사양/가격 | 완전히 동일 | 완전히 동일 | 비용 차이 없음 |
| 4 | API 호출 | model 파라미터만 다름 | model 파라미터만 다름 | 클릭 한 번으로 전환 가능 |
| 5 | 커뮤니티 피드백 | 표준 버전은 도구 호출이 불안정함 | 도구 호출이 더 안정적임 | 에이전트 시나리오는 customtools |
| 6 | 적용 프레임워크 | Chat/RAG/순수 추론 | Cursor/Claude Code/MCP | 애플리케이션 유형에 따라 선택 |
한 줄 요약: customtools는 업그레이드 버전이 아니라 전용 버전입니다. 두뇌는 같지만 도구를 선택하는 전략이 다를 뿐이죠. 에이전트를 개발한다면 customtools를, 그 외의 시나리오라면 표준 버전을 사용하세요. 두 버전 모두 APIYI(apiyi.com)에서 동일한 API Key로 자유롭게 전환하며 사용할 수 있습니다.
선택 가이드
| 상황 | 답변 |
|---|---|
| 단순 대화형 앱을 만들고 있어요 | 표준 버전 사용 |
| 에이전트(Agent)를 개발 중이에요 | customtools 버전 사용 |
| 두 버전 중 어느 것이 더 강력한가요? | 추론 능력은 같지만, 도구 호출은 customtools가 더 안정적입니다 |
| 전환할 때 코드를 많이 수정해야 하나요? | model 파라미터만 바꾸면 되며, 나머지 코드는 그대로 유지됩니다 |
| 비용 차이가 있나요? | 완전히 동일합니다 |
참고 자료
-
Google AI 문서: Gemini 3.1 Pro Preview 모델 페이지
- 링크:
ai.google.dev/gemini-api/docs/models/gemini-3.1-pro-preview - 설명: customtools 엔드포인트 소개 및 사용 시 주의 사항
- 링크:
-
Gemini 3 개발자 가이드: FAQ — 모델 전환 시기
- 링크:
ai.google.dev/gemini-api/docs/gemini-3 - 설명: 표준 버전에서 customtools 버전으로 전환할 시기에 대한 공식 권장 사항
- 링크:
-
Gemini API Changelog: 2026년 2월 19일 릴리스 노트
- 링크:
ai.google.dev/gemini-api/docs/changelog - 설명: customtools 변형 모델의 최초 출시 공지
- 링크:
-
Hacker News 토론: Gemini 3.1 Pro 도구 호출(Tool Calling)에 대한 개발자 피드백
- 링크:
news.ycombinator.com/item?id=47074735 - 설명: 실제 개발자들의 경험 및 문제 보고
- 링크:
-
GitHub Copilot Changelog: Gemini 3.1 Pro 통합
- 링크:
github.blog/changelog/2026-02-19-gemini-3-1-pro-is-now-in-public-preview-in-github-copilot - 설명: 코딩 어시스턴트 시나리오에서의 도구 정밀도 평가
- 링크:
📝 작성자: APIYI 팀 | 기술 교류는 APIYI apiyi.com을 방문해 주세요.
📅 업데이트 날짜: 2026년 2월 20일
🏷️ 키워드: gemini-3.1-pro-preview-customtools, 표준 버전 비교, 에이전트(Agent) 개발, 도구 호출, 함수 호출(function calling), 모델 선택
