Google ADK, AI 에이전트 개발의 치트키 (feat. Fit-Finder 개발기)

 

최근 AI 에이전트 개발에 관한 과제를 맡았다.

이번에 'Fit-Finder'라는 의류 쇼핑몰 에이전트를 개발하면서 Google ADK (Agent Development Kit)를 처음 사용해 보았는데,

생각보다 매우 강력하고 유용한 도구다.

프로젝트에 어떻게 적용했는지 ADK의 핵심 기능 위주로 정리해 보았다.

 

🧐 Google ADK란 무엇인가?

보통 LLM 애플리케이션을 개발할 때 LangChain을 사용하거나 직접 API를 호출하여 구현한다. Google ADK는 구글에서 만든

'에이전트 개발 전용 프레임워크'다.

• 에이전트 정의 (agent.py)
• 도구 정의 (tools.py)

이렇게 역할이 명확하게 나뉘어 있어 코드가 복잡해지는 것을 방지하고, Function Calling(도구 사용) 구현이 매우 편리하다.

📘 공식 문서: Google ADK Docs - Get Started

Agent Development Kit

 

🛠️ 프로젝트 세팅

ADK를 설치하고 프로젝트를 생성하면 기본 골격을 자동으로 잡아준다.

pip install google-adk
adk create root_agent

생성된 파일들을 backend 폴더 내에 구성했다. 단순히 파일만 생성되는 것이 아니라, 에이전트가 상태(State)를 관리하고 설정을 불러오는 기본적인 보일러플레이트 코드를 모두 생성해 준다.

 

🧠 에이전트의 뇌: agent.py

ADK의 핵심은 Agent 클래스다.

여기서 어떤 모델을 사용할지, 에이전트의 성격(System Prompt)은 무엇인지, 어떤 도구를 사용할지 결정한다.

fit-finder 프로젝트에서는 다음과 같이 설정했다.

# backend/root_agent/agent.py

from google.adk.agents.llm_agent import Agent
from .tools import search_products, get_product_detail

# 에이전트에게 페르소나 부여
SYSTEM_INSTRUCTION = """
당신은 스마트한 패션 검색 도우미 'Fit-Finder'입니다. 
사용자의 예산, 색상, 스타일 요구사항에 맞춰 상품을 검색해 주세요.
"""

# Gemini 모델 + 도구(Tool) 장착
root_agent = Agent(
    model='gemini-3-flash-preview',
    name='root_agent',
    instruction=SYSTEM_INSTRUCTION,
    tools=[search_products, get_product_detail], # 핵심! 사용할 함수 등록
)

tools 리스트에 파이썬 함수를 등록하기만 하면 된다.

복잡한 JSON 스키마를 직접 작성할 필요가 없다는 점이 큰 장점이다.

 

🔧 에이전트의 손과 발: tools.py

ADK를 사용하며 가장 인상 깊었던 부분이다. 바로 Type Hinting(타입 힌트)을 적극적으로 활용한다는 점이다.

일반적으로 LLM에게 도구를 사용하게 하려면 복잡한 JSON 형식을 제공해야 한다.

하지만 ADK는 Python 함수에 타입만 명시하면 알아서 LLM이 이해할 수 있는 형태로 변환해 준다.

# backend/root_agent/tools.py

# 타입 힌트(str, int)를 명시하는 것이 중요하다.
def search_products(category: str, color: str, max_price: int) -> str:
    """
    조건에 맞는 상품을 검색하여 반환합니다.
    """
    # ... (상품 검색 로직) ...
    
    return json.dumps({
        "action": "search_products",
        "data": results
    })

이렇게 코드를 작성해 두면, 사용자가 "10만 원 이하 검은색 패딩 찾아줘"라고 요청했을 때, ADK가 자동으로 파라미터를 추출하여 함수를 실행한다.

• category -> "padding"
• color -> "black"
• max_price -> 100000

 

🚀 서버 띄우기: server.py

기본 적으로 공식문서에 나와 있듯이 adk web --port 8000 을 활용해 adk 에서 제공하는 UI와 Server를 바로 띄울 수 있지만,

커스텀 UI 적용을 위해 Python Server 실행 파일을 따로 작성하였다.

ADK는 FastAPI와 강력하게 통합되어 있다.

get_fast_api_app이라는 함수 하나로 세션 관리 기능이 포함된 API 서버를 즉시 구축할 수 있다.

# backend/server.py

import uvicorn
from google.adk.cli.fast_api import get_fast_api_app

# ADK 전용 FastAPI 앱 생성
# agent_dir 위치만 지정해주면 된다
app = get_fast_api_app(agent_dir="backend/root_agent")

if __name__ == "__main__":
    uvicorn.run(app, host="0.0.0.0", port=8000)

직접 엔드포인트(/chat, /history 등)를 구현하지 않아도 되므로 개발 속도가 비약적으로 빨라졌다.

 

📝 총평: ADK 사용 후기

이번에 Fit-Finder를 개발하며 느낀 ADK의 장점은 세 가지로 요약할 수 있다.

1. 구조의 통일성: agent, tools가 명확히 분리되어 있어 협업 및 유지보수에 유리하다.
2. 강력한 도구(Tool) 연동: 파이썬 함수 작성만으로 AI가 도구를 인식하므로 생산성이 매우 높다.
3. FastAPI 내장: 서버 구축에 대한 고민 없이 비즈니스 로직 구현에만 집중할 수 있다.

Google ADK 덕분에 AI Agent 개발을 아주 편하게 할 수 있었다.

해당 프로젝트는 계속해서 개발중이며, 최종 목적은 결제 flow까지 개발해 보는 것이다.

• GitHub: wana1997/fit-finder

GitHub - wana1997/fit-finder

 

 

 

 

- Just Do It -