4. G-ADK Tool 활용[2] - Custom Tool / Function Tool (파이썬 함수를 도구로 변환)

개발자가 직접 작성한 일반 파이썬 함수를 LLM이 인식하고 실행할 수 있는 에이전트 도구로 자동 변환하여 사용하는 방식입니다.

1. 주요 동작 방식

ADK는 파이썬 함수의 함수명, Docstring(주석 설명), Type Hint(타입 힌트)를 자동으로 분석(Parsing)하여, 이를 LLM이 이해할 수 있는 OpenAPI/JSON Schema 형태의 툴 스펙으로 변환합니다.

2. 코드 라인별 상세 해설

• MOCK_WEATHER_DATA = { ... }
  • 외부 API 연동 대신 테스트 목적으로 만든 가짜(Mock) 날씨 데이터베이스입니다.
• def get_current_weather(city: str) -> str: 및 Docstring
  • [가장 중요한 부분] LLM이 이 함수를 언제, 어떻게 사용해야 할지 판단하는 기준이 됩니다.
  • city: str: 파라미터 타입 힌트를 통해 LLM이 도시 이름을 문자열 형태로 전달해야 함을 이해합니다.
  • Docstring (""" ... """): 함수의 역할("주어진 도시의 현재 날씨를 반환")과 인자 설명("도시 이름 (예: '서울', '대전')")이 상세히 적혀 있습니다. LLM은 이 설명을 읽고 "사용자가 날씨를 물어보면 이 함수를 호출해야겠구나!"라고 판단합니다.
• tools=[get_current_weather]
  • 작성한 파이썬 함수 객체를 에이전트의 tools 배열에 등록합니다. 별도의 수동 변환 작업 없이 함수 이름만 넣으면 ADK가 내부적으로 툴로 패킹해 줍니다.
• instruction="사용자가 날씨를 물어보면, 반드시 Tool을 이용해 현재 날씨를 알려주세요."
  • 사용자 요청이 들어왔을 때 모델이 임의로 답하지 않고, 등록된 get_current_weather 툴을 거쳐 최신/정확한 정보를 조회한 뒤 답변을 가공하여 출력하도록 지시합니다.

 

    import os

    from google.adk import Agent

    MOCK_WEATHER_DATA = {

        "서울": {

            "condition": "맑음",

            "temperature_c": 22,

            "min_temp_c": 12,

            "max_temp_c": 22,

            "humidity": 45,

            "summary": "서울은 맑고 쾌청합니다.",

        },

        "부산": {

            "condition": "흐림",

            "temperature_c": 20,

            "min_temp_c": 10,

            "max_temp_c": 18,

            "humidity": 60,

            "summary": "대전은 흐리고 바람이 약간 붑니다.",

        },

    }

    # 일반 파이썬 함수를 툴로 정의

    def get_current_weather(city:str)->str:

        """

        주어진 도시의 현재 날씨를 반환합니다.

        Args:

            city: (str) 도시 이름 (예: "서울", "대전")

        Returns:

            (str) 해당 도시의 날씨 설명 문자열    

        """

        weather = MOCK_WEATHER_DATA.get(city)

        if weather is None:

            return f"{city}의 날씨 정보는 현재 없습니다.."  

        return(

            f"{city}: {weather['condition']}, 현재 {weather['temperature_c']}도, "

            f"최고 {weather['max_temp_c']}도 / 최저 {weather['min_temp_c']}도, "

            f"습도 {weather['humidity']}%, {weather['summary']}"

        )

    weather_agent = Agent(

        model=os.getenv("GOOGLE_MODEL", "gemini-3.5-flash"),

        name="weather-agent",

        description="날씨를 알려주는 에이전트입니다.",

        instruction="사용자가 날씨를 물어보면, 반드시 Tool을 이용해 현재 날씨를 알려주세요.",

        tools=[get_current_weather]

    )

    root_agent = weather_agent