개발자·자동화 확장: Gemini API/Live API, 도구 호출, 보안·거버넌스

2026-03-22Views 12약 8분

개인용 Gemini는 '대화'가 중심이지만, 업무 시스템이나 제품에 Gemini를 붙이는 순간 중심이 바뀝니다. 이제 중요한 건 "얼마나 말을 잘하느냐"가 아니라 "얼마나 예측 가능하게 동작하느냐, 얼마나 안전하게 운영하느냐"입니다. 이때 Gemini는 도구가 아니라 인프라가 됩니다.

이 챕터에서는 API 키/SDK로 생성 요청을 보내는 최소 골격을 잡고, 구조화 출력과 함수 호출로 "모델의 말"을 "시스템의 동작"으로 바꾸는 방법, 그리고 Live API로 실시간 세션을 운영하는 개념을 정리합니다. 마지막으로 민감정보·조직 정책·감사 체계를 포함한 거버넌스 관점을 붙여, 프로덕션에 견디는 설계를 만들도록 돕겠습니다.

1) 개발자 API vs Vertex AI: 같은 Gemini, 다른 운영 모델

Gemini를 시스템에 연결하는 경로는 크게 두 가지로 생각하면 이해가 쉽습니다.

첫째는 Gemini Developer API(일반적으로 API 키 기반)입니다. 빠르게 실험하고 작은 서버에서 시작하기 좋습니다. 둘째는 Vertex AI(주로 조직/프로젝트 단위 인증과 운영 기능을 포함)입니다. Live API 같은 실시간 기능도 Vertex AI 문서에서 세션 관리, 제한사항, 운영 설정이 더 구체적으로 설명되는 경우가 많습니다.⁶⁷

중요한 건 "어느 쪽이 더 좋다"가 아니라, 운영 책임이 어디에 놓이느냐입니다. 개인 키로 시작한 PoC가 서비스로 커질수록, 인증·로깅·정책·감사 요구가 따라오고, 결국 '조직이 관리할 수 있는 형태'로 옮겨가게 됩니다.

2) API 키/인증 설계: 키는 코드가 아니라 운영 자산

API 키는 편하지만, 동시에 가장 흔한 사고 지점입니다. 키를 코드에 박아 넣는 순간, 로그/스크린샷/깃 히스토리를 통해 유출될 확률이 급격히 올라갑니다. 따라서 원칙은 단순합니다.

개발 단계에서도 키는 환경변수나 시크릿 매니저에 보관하고, 실행 환경에서 주입합니다. 팀/조직에서 사용한다면 키 발급·폐기·교체(로테이션) 절차를 문서화하고, 최소한 "누가, 어떤 서비스가, 어떤 범위로" 사용하는지 추적 가능해야 합니다.

또 하나의 원칙은 클라이언트(브라우저/앱)에서 직접 키로 호출하지 않는다입니다. 특히 Live API는 "서버 간 통신을 위해 설계되었으며", 웹/모바일 앱은 중간 서버를 거치도록 가이드합니다.⁷ 즉, 사용자의 기기에는 비밀을 두지 않고, 서버가 정책과 인증을 책임지는 구조가 기본값입니다.

3) SDK 호출의 최소 골격: "요청-응답"을 서비스로 만들기

SDK를 쓰면 모델 호출 자체는 어렵지 않습니다. 하지만 프로덕션에서는 "호출 성공"보다 "호출이 실패해도 시스템이 정상 동작"하는지가 중요합니다.

서버에서의 최소 골격은 다음 질문에 답하는 형태로 잡습니다.

어떤 모델을 쓸 것인가(Flash/Pro, 추론 옵션 포함)
입력(프롬프트/파일/컨텍스트)은 어디서 오고, 어디까지 허용되는가
출력은 자유 텍스트인가, 아니면 스키마를 강제하는가
실패/타임아웃/재시도/폴백은 어떻게 할 것인가

이 골격이 잡히면, 이후 기능(구조화 출력, 함수 호출, Live 세션)은 "옵션"이 아니라 "신뢰성 장치"로 들어옵니다.

4) 구조화 출력: JSON 모드 vs 스키마 강제(Structured Outputs)

업무 시스템에서 가장 큰 비용은 모델이 틀린 말을 해서가 아니라, 모델의 답을 파싱하느라 발생하는 예외 처리 비용에서 나옵니다. 그래서 프로덕션에서는 자유 텍스트 대신 구조화 출력이 빠르게 표준이 됩니다.

Gemini API의 구조화 출력은 크게 두 층위로 이해하면 됩니다.

(1) JSON 모드: "JSON으로만 말해"

JSON 모드는 출력 MIME 타입을 JSON으로 강제해 파싱 가능한 형태를 얻는 방식입니다. 다만 구조(필드/타입)는 프롬프트 의존이므로, 데이터 계약이 엄격한 시스템에는 한계가 있습니다.¹⁶

(2) 스키마 강제: "이 JSON Schema대로만 말해"

Structured Outputs는 JSON Schema를 제공해, 응답이 그 스키마를 따르도록 만드는 방식입니다.¹ 이때 기대 효과는 명확합니다. 데이터 추출, 분류(특히 enum), 에이전트 워크플로에서 "다음 단계 입력"으로 바로 넘길 수 있는 타입 안전한 결과를 얻습니다.¹

SDK에서는 Python의 Pydantic, JavaScript/TypeScript의 Zod 같은 라이브러리로 스키마를 더 자연스럽게 정의할 수 있습니다.¹³

또한 2025년 업데이트로 JSON Schema 지원이 강화되면서 anyOf, $ref 같은 키워드 지원이 확장되고, 스키마 키 순서가 출력에 더 잘 반영되는 개선이 강조되었습니다.²

아래는 "자유 텍스트 요약"이 아니라 "업무에 바로 넣을 카드"를 만드는 전형적인 패턴입니다.

# 개념 예시: 요약을 "제목/핵심/리스크/다음 액션" 스키마로 강제
# (실제 코드는 SDK 버전에 맞춰 조정)

schema = {
  "type": "object",
  "properties": {
    "title": {"type": "string"},
    "key_points": {"type": "array", "items": {"type": "string"}},
    "risks": {"type": "array", "items": {"type": "string"}},
    "next_actions": {"type": "array", "items": {"type": "string"}}
  },
  "required": ["title", "key_points", "next_actions"]
}

config = {
  "response_mime_type": "application/json",
  "response_schema": schema
}

이 방식의 핵심은 "모델이 잘 말하게"가 아니라, 시스템이 기대하는 계약을 먼저 고정하고 모델을 그 안에 넣는 것입니다.

5) 함수 호출(도구 호출): 모델은 '결정', 시스템은 '실행'

프로덕션에서 함수 호출은 단순한 편의 기능이 아니라 권한·감사·재현성을 위한 장치입니다. 모델이 외부 API를 직접 때리는 구조는 위험합니다. 대신 모델은 "무슨 도구를 어떤 인자로 호출할지"를 제안하고, 실제 실행은 서버가 담당합니다.

Live API 문서의 메시지 구조를 보면, 이 철학이 인터페이스에 그대로 들어가 있습니다. 세션에서 서버가 tool call을 보내면 클라이언트(즉, 여러분의 서버)는 해당 요청을 실행한 뒤 toolResponse 메시지로 결과를 돌려줍니다.⁷

이 구조가 주는 장점은 세 가지입니다.

모델이 잘못된 도구를 호출하려 해도, 서버에서 정책으로 차단할 수 있습니다.
모든 호출은 "언제, 누가, 어떤 인자"로 실행됐는지 감사 로그를 남길 수 있습니다.
장애 시 도구 실행 결과를 캐시/재시도/대체(폴백)하는 등 SRE 관점의 제어가 가능합니다.

결국 함수 호출은 "에이전트가 똑똑해지는 기능"이기 전에, 시스템이 모델을 안전하게 통제하는 표준 인터페이스입니다.

6) Live API: 실시간 대화는 '세션'을 운영하는 일이다

Live API는 단발성 요청-응답이 아니라, 연속 스트림(오디오/텍스트/이미지)을 처리하는 상태ful 세션입니다.⁵ 그래서 실시간 경험을 만들려면, 모델 선택보다 세션 수명과 끊김 대응이 더 중요해집니다.

세션 수명, 연결 수명, 그리고 재개(resumption)

Vertex AI 문서 기준으로 Live 세션은 연결 수명이 약 10분으로 제한되고, 종료가 임박하면 goAway 신호를 받을 수 있습니다.⁶ 실서비스에서는 이 신호를 감지해 재연결을 준비하고, 필요하면 세션 재개를 통해 컨텍스트를 유지한 채 연결을 이어갑니다. 또한 세션 재개는 최대 24시간 내 재개가 가능하다고 설명됩니다.⁶

컨텍스트 윈도우 압축: '무한 대화'는 자동 요약의 다른 이름

긴 대화는 컨텍스트 한도에 부딪힙니다. Live API는 컨텍스트 윈도우 압축을 통해 오래된 턴을 삭제/요약하는 방식으로 세션을 연장할 수 있습니다.⁶ 여기서 중요한 설계 포인트는 "무한히 기억하는 AI"가 아니라, 무엇을 잃어도 되는지(요약 가능 영역)와 무엇은 잃으면 안 되는지(불변 정책/사용자 프로필/금칙사항)를 분리하는 것입니다.

Live API 메시지 모델: 실시간 입력과 대화 기록은 다르다

Live API는 클라이언트 메시지를 역할에 따라 분리합니다. 예를 들어 실시간 오디오/동영상은 realtimeInput으로 보내며, 대화 기록을 쌓는 clientContent와는 성격이 다릅니다.⁷ 이 구분을 이해하면, "말을 끊고(barge-in) 다시 말하기" 같은 자연스러운 인터랙션을 구현할 때 어떤 메시지가 대화를 중단시키는지, 어떤 메시지가 기록을 구성하는지 더 명확해집니다.⁵⁷

7) 보안·거버넌스: AI가 아니라 '시스템'이 책임진다

이제부터는 모델 성능보다, 조직이 책임질 수 있는 운영 체계가 핵심입니다. 거버넌스는 "규정 준수 문서"가 아니라, 매일의 설계 선택에 스며드는 실행 규칙입니다.

민감정보(PII/기밀) 최소화: 프롬프트는 데이터 파이프라인이다

시스템에 Gemini를 붙이면 프롬프트는 곧 데이터 흐름이 됩니다. 따라서 원칙은 최소 수집, 최소 전송, 최소 보관입니다.

개발 단계에서 흔히 하는 실수는 디버그를 위해 원문을 전부 로그로 남기는 것입니다. 하지만 운영에서는 마스킹(예: 이메일/전화번호/계좌), 요약 저장, 해시 기반 식별자 같은 방식으로 "모델이 필요로 하는 정보만" 전달해야 합니다. 특히 Live API는 음성/영상까지 다룰 수 있으므로, 저장·전송·접근 통제가 더 민감해집니다.⁵⁷

정책을 코드로 만든다: Policy-as-Code와 런타임 거버넌스

AI 에이전트가 도구를 호출하는 순간, 보안은 "모델의 안전 필터"만으로 해결되지 않습니다. 실제로 필요한 것은 행동을 통제하는 정책 엔진입니다. 예를 들어 다음 같은 규칙이 있어야 합니다.

어떤 사용자/역할이 어떤 도구를 호출할 수 있는가(최소 권한)
어떤 데이터 범주(PII/재무/인사)가 입력으로 들어오면 어떤 처리(마스킹/차단/승인)가 필요한가
어떤 외부 도메인/URL/저장소로는 절대 데이터가 나가면 안 되는가

이런 접근을 런타임에서 강제하는 도구로, 에이전트의 행동을 정책으로 평가하고 차단/감사하도록 설계된 툴킷들도 등장했습니다.⁸ 핵심은 특정 제품이 아니라 관점입니다. "출력을 검사하는 것"에서 "행동을 허용/거부하는 것"으로 무게중심을 옮기는 것이 프로덕션의 기준입니다.