Gemini Agent란? Google AI Agent가 도구·API·함수를 호출하는 방법

최종 갱신 2026년 8월 18일. 기술 서술은 Google Managed Agents(Gemini Agent), Function calling, Using Tools with Gemini API 문서와 대조했습니다.

증상: 문서에 Gemini, Agent, Tools, Function calling이 섞여 Interactions·자체 루프·관리형 Agent를 구분하지 못합니다.
빠른 해법: “모델이 호출을 제안했다”와 “부작용을 누가 실행하는가”를 나눕니다. 내장 도구는 Google, 사용자 함수는 function_result를 돌려줄 때까지 여러분의 앱입니다.

주문·내부 API에 Google AI Agent를 붙이는 백엔드, 자체 Agent Loop와 Managed Agents를 비교하는 아키텍트, 채팅은 되지만 DB에 안전하게 쓰지 못하는 플랫폼 팀을 위한 글입니다.

Gemini Agent가 가리키는 세 층

회의에서 같은 말이 세 층을 가리킵니다. 섞으면 IAM과 장애 대응이 반대로 갑니다.

첫째는 Gemini 모델입니다. 함수 스키마를 주면 산문이 아니라 구조화된 function_call을 낼 수 있습니다. “무엇을 부를지 아는가”의 문제이지, DB 비밀번호를 넘기는 문제가 아닙니다.

둘째는 Gemini API 도구입니다. 공식 문서는 턴 또는 Live 세션에서 모델이 요청할 능력으로 Search, Code Execution, URL Context와 자체 Function Calling을 묶습니다. Tools 문서

셋째가 제품으로서의 Gemini Agent / Managed Agents입니다. 시스템 지시, 기본 도구, 원격 MCP, 사용자 함수, 파일, AGENTS.md를 ID로 호출하는 에이전트로 고정하고 Interactions API로 실행합니다. 기본값은 code_execution, google_search, url_context이며 interaction마다 덮어쓸 수 있습니다. Building Managed Agents

한 번의 구조화 조회면 Function calling으로 충분합니다. 샌드박스·검색·코드 실행·MCP·재사용 설정이 필요하면 Managed Agents로 올리세요. Agent라는 이름만으로 업무 규칙을 프롬프트에 붓지 마세요.

도구·API·함수의 책임 분리

• 도구는 모델이 보는 목록입니다. 호스팅 도구는 Google이 실행하고, 사용자 도구는 선언일 뿐입니다.
• API는 업무 HTTP와 조회입니다. 비밀은 모델에 없고 서비스 계정이 인증합니다.
• 함수는 로컬 코드와 큐 생산자입니다. JSON Schema로 선언하고 id로 결과를 맞춥니다.

공식 Function calling 용도는 행동, 지식 보강, 능력 확장입니다. 최종 응답 형태만 묶는 Structured Outputs와 다릅니다. 중간 홉에서 자사 시스템을 치면 Function calling을 씁니다. Function calling 가이드

도구가 파일을 건드릴 때는 호스트 디스크와 Agent 작업 공간을 분리하는 편이 안전합니다. AI Virtual File System이란? 2026 완전 가이드를 참고하고, 사내 문서를 도구로 노출할 때는 PDF를 AI 지식库로 바꾸는 방법: Book to Skill 완전 가이드(2026)의 범위 설정과 맞춰 보세요.

함수 호출 한 바퀴

함수 이름이 나온 시점을 성공으로 치지 마세요. 공식 흐름은 다섯 단계입니다.

1. 이름·설명·JSON Schema를 선언하고, 호출하면 안 되는 조건도 적습니다.
2. 사용자 입력과 tools를 interactions.create 또는 generateContent로 보냅니다.
3. 모델은 텍스트로 답하거나 id와 arguments가 있는 function_call을 반환합니다.
4. 타입 검증, 인증, 타임아웃, 멱등 키 뒤에 실제 API를 칩니다. 사용자 코드는 모델이 실행하지 않습니다.
5. 같은 id로 function_result를 보내고 필요하면 previous_interaction_id를 붙입니다.

{
  "type": "function",
  "name": "get_order_status",
  "description": "주문 번호로 이행 상태를 조회한다. 생성·취소에 쓰지 않는다.",
  "parameters": {
    "type": "object",
    "properties": {
      "order_id": {"type": "string", "description": "OD-20260818-001 같은 업무 번호"}
    },
    "required": ["order_id"]
  }
}

모델 인자를 SQL이나 셸에 이어 붙이지 마세요. 스키마 검증, 내부 DTO, 서비스 계정 순입니다. 스트림 arguments는 JSON이 완성된 뒤에만 실행합니다. 병렬 호출은 재고와 배송을 동시에 가져올 수 있고, 조합 호출(위치 다음 날씨)은 이전 결과를 기다립니다.

내장 도구와 사용자 함수

“모델이 도구를 요청했다”를 “서버가 끝냈다”로 읽는 것이 전형적인 장애입니다. 내장은 Google이 관리하고 짝이 맞는 function_result가 나옵니다. 사용자 함수는 앱 책임입니다.

Managed Agents는 단계 매칭을 씁니다. 내장은 서버에서 끝나고, 미실행 사용자 호출은 requires_action입니다. 이미 결과가 있는 call_id를 다시 실행하면 결제에서는 사고입니다. 원본 call, 실행 로그, result, interaction 상태 네 가지를 남기세요.

모드, MCP, 조합 호출

tool_choice는 auto, any, none, 미리보기 validated입니다. 날씨 조회를 any로 두는 것은 괜찮지만, 승인 없는 운영 데이터 삭제를 any로 두면 안 됩니다. 원격 MCP는 name과 url로 외부 도구 서버를 붙입니다. 인증 없는 공개 MCP를 모델의 자제에 맡기지 마세요. Gemini 3는 한 interaction에서 내장과 사용자를 섞을 수 있고 previous_interaction_id가 맥락을 이어 줍니다. 로그는 HTTP 한 방이 아니라 interaction 단위로 보관하세요.

쓰기 권한 개방 전 통제

1. 읽기와 쓰기를 다른 함수로 나누고, 보여선 안 되는 능력은 Schema에서 뺍니다.
2. 생성·결제·메일은 function_call.id 또는 자체 request-id로 멱등 처리합니다.
3. 타임아웃은 형식 있는 오류를 돌려 빈 문자열 재시도를 막습니다.
4. 상태·요약·다음 힌트만 반환합니다.
5. 홉 수, 경과 시간, 토큰 예산을 두고 초과 시 사람 큐로 보냅니다.
6. 스키마 버전, 모델 버전, 인자, 결과 해시를 남겨 재현합니다.

업무 시스템에 이미 썼을 수 있으면 멱등 표를 먼저 봅니다. “모델에게 한 번 더”는 금지입니다. UI가 한 호출을 두 번 그린 것이면 로그 집계를 고치고 프롬프트는 건드리지 않습니다.

최종 페이로드만 묶으면 Structured Outputs, 자사 API에 닿으면 Function calling, 샌드박스·검색·MCP·재사용 설정이 필요하면 Managed Agents. 세 가지를 한 제품에 넣어도 실행 책임은 아키텍처 그림에 적으세요.

잠드는 노트북에서 Gemini Agent를 돌리면 requires_action 콜백과 interaction 로그가 끊깁니다. 밤새 함수 호출을 재현하려면 맥 미니 렌탈 환경이 개인 PC를 점유하는 것보다 낫습니다. 운영 이슈는 맥 지원 안내와 함께 보세요. USB나 전용망이 필수면 자체 장비를 유지하세요.