제미나이 API Function Calling 실전: RAG와 에이전트로 확장하는 AI 아키텍처

목차

• Function Calling: 외부 도구를 연결하는 첫 번째 계층
• RAG: 사내 데이터와 최신 정보를 답변에 결합하는 방법
• 에이전트: 계획과 실행을 반복하는 자율 작업 시스템
• CLI: 실험과 디버깅을 가속하는 개발자 도구
• 결론: 실행 엔진으로서의 제미나이 API
• 자주 묻는 질문 (FAQ)

도입부: 말 잘하는 AI를 넘어, 일 잘하는 AI로

생성형 AI의 진정한 경쟁력은 유창한 대화 능력을 넘어, 실제 세계의 시스템과 연결되어 구체적인 ‘일’을 처리하는 데서 나옵니다. 제미나이 API Function Calling은 바로 이 연결을 가능하게 하는 핵심 기술입니다. 많은 개발자가 “단순 챗봇을 넘어 우리 회사 데이터와 연동하고, 복잡한 업무를 자율적으로 처리하는 AI를 만들 수는 없을까?”라는 고민을 합니다. 이 질문에 대한 해답이 바로 외부 시스템과의 연동에 있습니다.

이 글은 제미나이(Gemini) API를 활용하여 단순한 API 호출부터, 검색 증강 생성(RAG)을 통한 지식 보강, 그리고 LLM 에이전트를 이용한 작업 자동화 시스템 구축까지, 실전 AI 아키텍처와 구현 패턴을 단계별로 안내합니다. 이 글을 통해 여러분은 단순 모델 활용을 넘어, 비즈니스 가치를 창출하는 AI 시스템의 ‘실행 계층’을 설계하는 구체적인 방법을 배우게 될 것입니다.

Function Calling: 외부 도구를 연결하는 첫 번째 계층

LLM API Tool Use, 개념부터 명확히

가장 먼저 바로잡아야 할 오해는 Function Calling이 LLM(거대 언어 모델)이 코드를 ‘직접 실행’하는 기술이 아니라는 점입니다. 실제로는 LLM이 사용자 요청을 분석하여, 특정 작업을 수행하는 데 필요한 함수와 그 인자(argument)를 구조화된 JSON 형태로 제안하는 기능입니다. 제안된 함수를 실제로 실행하는 주체는 우리의 애플리케이션 코드입니다.

이러한 구조는 오히려 시스템의 안정성과 통제 가능성을 비약적으로 높여줍니다. LLM은 어떤 도구가 필요한지만 알려줄 뿐, 실행 권한은 애플리케이션이 갖기 때문에 예상치 못한 동작을 막고 보안을 유지하기에 용이합니다.

전체적인 아키텍처 흐름은 다음과 같습니다.

• 사용자 요청: “서울 날씨 어때?”
• Gemini API (함수 호출 제안): `{“functionCall”: {“name”: “get_current_weather”, “args”: {“location”: “서울”}}}` 와 같은 JSON 응답을 반환합니다.
• 애플리케이션 (제안된 함수 실행): 이 JSON을 파싱하여, 내부적으로 `get_current_weather(“서울”)` 함수를 직접 호출하고 날씨 API로부터 결과를 받아옵니다.
• 애플리케이션 (실행 결과 재전달): 날씨 API에서 받은 결과(예: “맑음, 26도”)를 다시 Gemini API에 전달합니다.
• Gemini API (결과 기반 최종 답변 생성): “현재 서울 날씨는 맑고 기온은 26도입니다.” 와 같이 자연스러운 최종 문장을 생성하여 사용자에게 전달합니다.

Gemini API에서의 구체적인 구현법 (Python 예제)

제미나이 API Function Calling (활용법)은 총 4단계로 이루어집니다.

1단계 (Tool 정의): 호출하고자 하는 함수(`get_current_weather`)와 필요한 매개변수(`location`)를 `Tool`과 `FunctionDeclaration`을 통해 명확하게 정의합니다. 이 정의는 LLM에게 어떤 도구를 사용할 수 있는지 알려주는 설명서 역할을 합니다.

import google.generativeai as genai

get_current_weather = genai.protos.FunctionDeclaration(
    name="get_current_weather",
    description="Get the current weather in a given location",
    parameters=genai.protos.Schema(
        type=genai.protos.Type.OBJECT,
        properties={
            "location": genai.protos.Schema(type=genai.protos.Type.STRING)
        },
        required=["location"],
    ),
)
weather_tool = genai.protos.Tool(
    function_declarations=[get_current_weather],
)

2단계 (모델 호출): `generate_content`를 호출할 때, `tools` 매개변수에 위에서 정의한 `weather_tool`을 전달합니다.

model = genai.GenerativeModel(model_name="gemini-1.5-pro-latest", tools=[weather_tool])
chat = model.start_chat()
response = chat.send_message("What is the weather like in Seoul?")

3단계 (응답 처리): 모델이 함수 호출을 제안했다면, 응답에서 `function_call` 객체를 추출하여 실제 로컬 함수를 실행합니다.

function_call = response.candidates[0].content.parts[0].function_call
if function_call.name == "get_current_weather":
    # 실제 날씨 정보를 가져오는 함수 (구현 필요)
    location = function_call.args["location"]
    weather_data = call_real_weather_api(location) # 예시

4단계 (결과 재전달): 함수 실행 결과를 `Part` 형태로 다시 모델에 전달하여, 이를 바탕으로 최종 사용자 응답을 생성하도록 요청합니다.

response = chat.send_message(
    part=genai.protos.Part(
        function_response=genai.protos.FunctionResponse(
            name="get_current_weather",
            response={"weather": weather_data},
        )
    ),
)
print(response.text)

RAG: 사내 데이터와 최신 정보를 답변에 결합하는 방법

똑똑한 AI의 비결, Retrieval Augmented Generation (RAG)

LLM은 학습 데이터에 없는 최신 정보나 기업 내부의 비공개 문서에 대해서는 답변할 수 없습니다. 이럴 때 잘못된 정보를 사실처럼 말하는 환각(Hallucination) 현상이 발생하기도 합니다. RAG는 이러한 한계를 극복하기 위한 핵심 아키텍처로, LLM이 단순히 기억에 의존해 답하는 것이 아니라, 관련 문서를 ‘찾아서 근거를 가지고’ 답하게 만드는 기술입니다. 제미나이 API RAG (데이터 연동)를 통해 우리는 더 신뢰도 높은 AI 시스템을 구축할 수 있습니다.

Gemini API를 활용한 RAG 구현 전략

Gemini API를 활용해 RAG를 구현하는 방법은 크게 두 가지로 나뉩니다.

전략 1: Gemini File API 활용

Google의 `File API`는 RAG의 복잡한 과정을 놀랍도록 단순화합니다. PDF, TXT 등 파일을 API로 업로드하면, Google이 내부적으로 문서 분할(Chunking), 임베딩, 벡터 인덱싱을 모두 처리합니다. 개발자는 그저 프롬프트를 보낼 때 `FileSearchTool`을 지정하기만 하면, Gemini가 알아서 업로드된 파일 내용을 검색하여 답변에 활용합니다.

# 1. 파일 업로드
sample_file = genai.upload_file(path="my-document.pdf", display_name="My Company Policy")

# 2. FileSearchTool을 사용하여 모델에 질문
file_search_tool = genai.protos.Tool(
    file_search=genai.protos.FileSearch(files=[sample_file.name])
)
model = genai.GenerativeModel(model_name="gemini-1.5-pro-latest", tools=[file_search_tool])

# 3. Gemini가 파일을 참고하여 답변 생성
response = model.generate_content("우리 회사 연차 정책에 대해 알려줘")
print(response.text)

전략 2: 오픈소스 벡터 DB 연동

이미 자체 벡터 DB를 운영 중이라면, 전통적인 RAG 파이프라인을 직접 구축할 수 있습니다. 이 방식은 더 많은 제어권을 제공합니다.

1. 준비: 내부 문서를 잘게 쪼개고(Chunking), 각 조각을 임베딩 모델을 통해 벡터로 변환하여 ChromaDB 같은 벡터 DB에 저장합니다.
2. 실행: 사용자 질문이 들어오면, 질문 또한 벡터로 변환합니다.
3. 검색: 변환된 질문 벡터와 가장 유사한 문서 조각들을 벡터 DB에서 검색합니다.
4. 주입 및 생성: 검색된 문서 조각들을 참고 자료(Context)로 삼아 프롬프트를 구성하고, Gemini API에 전달하여 근거에 기반한 최종 답변을 생성합니다.

에이전트: 계획과 실행을 반복하는 자율 작업 시스템

단순 응답을 넘어선 LLM 에이전트 개발

에이전트는 단일 요청에 한 번 응답하고 끝나는 챗봇을 넘어, 최종 목표를 달성하기 위해 스스로 작업을 계획하고 도구를 사용하며 결과를 관찰하는 과정을 반복하는 지능형 시스템입니다. 여기서의 자율성은 ‘완전 자율’이 아닌, 개발자가 정의한 도구와 규칙 안에서 목표를 해결하는 ‘제어 가능한 자율성’을 의미하며, 이는 LLM 에이전트 개발 (Gemini API로 구현)의 핵심 철학입니다.

에이전트는 주로 ReAct(Reason + Act) 프레임워크를 기반으로 동작하며, 다음과 같은 루프를 반복합니다.

• 생각 (Thought): 목표와 현재 상황을 고려해 다음에 무엇을 해야 할지 추론합니다.
• 행동 (Action): 추론 결과에 따라 사용할 도구(Function Calling으로 정의된 함수)와 필요한 인자를 결정합니다.
• 관찰 (Observation): 도구를 실행한 결과를 관찰하고, 이 결과를 다음 ‘생각’ 단계의 입력으로 사용합니다.

Gemini API와 LangChain을 활용한 에이전트 아키텍처

LangChain과 같은 프레임워크는 이런 에이전트 루프를 구현하는 데 매우 효과적입니다. `ChatGoogleGenerativeAI` 모델을 래핑하고, 필요한 Tool들을 정의한 뒤, `create_gemini_functions_agent`와 `AgentExecutor`를 통해 손쉽게 에이전트를 실행할 수 있습니다.

from langchain_google_genai import ChatGoogleGenerativeAI
from langchain.agents import tool, AgentExecutor, create_gemini_functions_agent
from langchain_core.prompts import ChatPromptTemplate

# 1. 모델 초기화
llm = ChatGoogleGenerativeAI(model="gemini-1.5-pro-latest")

# 2. 도구(Tool) 정의
@tool
def get_current_weather(location: str) -> str:
    """Get the current weather in a given location."""
    # 실제 날씨 API 호출 로직
    return f"{location} is currently sunny and 26°C."

tools = [get_current_weather]

# 3. 에이전트 프롬프트 정의
prompt = ChatPromptTemplate.from_messages([
    ("system", "You are a helpful assistant."),
    ("human", "{input}"),
    ("placeholder", "{agent_scratchpad}"),
])

# 4. 에이전트 생성 및 실행
agent = create_gemini_functions_agent(llm, tools, prompt)
agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True)

agent_executor.invoke({"input": "What's the weather in Seoul?"})

Gemini API Agent (고급 아키텍처)로 나아가면, 특정 분야를 전문으로 하는 여러 에이전트(리서치 에이전트, 코드 생성 에이전트 등)가 서로 협력하여 더 복잡한 문제를 해결하는 ‘멀티 에이전트 시스템’도 구상할 수 있습니다. 이는 디지털 트랜스포메이션을 가속화하는 강력한 동력이 될 것입니다.

CLI: 실험과 디버깅을 가속하는 개발자 도구

개발 생산성을 높이는 제미나이 CLI 활용

제미나이 CLI 활용 (명령줄 인터페이스)는 개발자의 작업 효율을 극적으로 높여주는 도구입니다. 복잡한 UI나 코드를 거치지 않고 터미널에서 직접 모델의 성능을 테스트하고 프롬프트를 실험하며, 간단한 자동화 스크립트를 작성할 수 있습니다.

핵심 사용 사례 및 명령어

CLI의 진정한 힘은 셸 스크립트와의 연동에서 나옵니다. 예를 들어, 현재 디렉터리의 모든 텍스트 파일(`*.txt`)을 요약하는 간단한 자동화 스크립트는 다음과 같이 작성할 수 있습니다.

#!/bin/bash

# 현재 디렉터리의 모든 .txt 파일을 순회하며 요약
for file in *.txt; do
  if [ -f "$file" ]; then
    echo "--- Summarizing $file ---"
    # 파일 내용을 파이프로 gemini cli에 전달하여 요약 요청
    cat "$file" | gemini generate "다음 텍스트를 세 문장으로 요약해줘:"
    echo "" # 줄바꿈
  fi
done

이처럼 CLI를 활용하면 반복적인 작업을 자동화하고, 개발 초기 단계에서 프롬프트 엔지니어링과 모델 응답을 빠르게 검증하며 전체 개발 워크플로우를 가속할 수 있습니다.

결론: 실행 엔진으로서의 제미나이 API

우리는 제미나이 API의 네 가지 핵심 기술 요소를 통해 단순한 언어 모델을 넘어선 AI 시스템을 구축하는 여정을 살펴보았습니다.

• Function Calling은 AI에게 외부 세계와 소통할 ‘손과 발’을 제공합니다.
• RAG는 신뢰할 수 있는 최신 지식을 공급하는 ‘두뇌의 일부’ 역할을 합니다.
• 에이전트는 목표를 향해 자율적으로 계획하고 실행하는 ‘의지’를 부여합니다.
• CLI는 이 모든 것을 빠르게 만들고 테스트하도록 돕는 ‘개발자의 작업대’입니다.

이 네 가지 요소가 유기적으로 결합될 때, 제미나이 API는 단순한 API 모음을 넘어, 실제 비즈니스 가치를 창출하고 복잡한 문제를 해결하는 강력한 ‘AI 시스템의 실행 엔진’으로 거듭납니다. 이 글에서 다룬 아키텍처와 코드를 바탕으로, 이제 여러분만의 고도화된 AI 애플리케이션 개발을 시작해 보시기 바랍니다.

자주 묻는 질문 (FAQ)

Q: 제미나이 Function Calling은 코드를 직접 실행하나요?

A: 아니요, 직접 실행하지 않습니다. 제미나이는 실행할 함수와 필요한 인자를 JSON 형태로 ‘제안’할 뿐, 실제 실행은 개발자의 애플리케이션 코드에서 이루어집니다. 이는 시스템의 안정성과 보안을 높여줍니다.

Q: RAG(검색 증강 생성)는 왜 필요한가요?

A: RAG는 LLM이 학습 데이터에 없는 최신 정보나 기업 내부 데이터에 대해 답변할 때 발생할 수 있는 ‘환각(Hallucination)’ 현상을 방지합니다. 외부 지식 소스를 참조하여 더 정확하고 신뢰도 높은 답변을 생성하게 해줍니다.

Q: 에이전트(Agent)와 일반 챗봇의 가장 큰 차이점은 무엇인가요?

A: 일반 챗봇은 단일 요청에 한 번 응답하지만, 에이전트는 최종 목표 달성을 위해 스스로 ‘생각-행동-관찰’의 순환 과정을 반복합니다. 즉, 자율적으로 계획을 세우고 여러 도구를 사용하며 작업을 수행하는 더 능동적인 시스템입니다.