7. G-ADK Tool 활용[4.2] - Declarative OpenAPI Spec Tool (OpenWeatherMap_OpenAPI

Agentic AI/Google ADK

7. G-ADK Tool 활용[4.2] - Declarative OpenAPI Spec Tool (OpenWeatherMap_OpenAPI_명세서.json)

아톨 2026. 10. 10. 14:29

Declarative OpenAPI Spec Tool 코드에서 사용하는 OpenAPIToolset은 OpenWeatherMap처럼 거대하고 복잡한 공식 Swagger 명세서 전체를 넣으면 파싱 에러가 나거나 토큰이 낭비되기 쉽습니다. 따라서 가장 현명하고 신속하며 확실하게 작동하는 방식은 "에이전트가 실제로 사용하는 핵심 엔드포인트(/weather, /forecast)만 쏙쏙 골라 담은 미니멀 OpenAPI 3.0 JSON 명세서를 직접 구성하는 것"입니다.

아래에 Declarative OpenAPI Spec Tool 코드와 완벽하게 호환되며 곧바로 파일로 저장해 쓸 수 있는 실전용 OpenWeatherMap_OpenAPI_명세서.json 코드 템플릿을 정리합니다.

실전용 OpenWeatherMap_OpenAPI_명세서.json 파일 내용

프로젝트 디렉토리에 이 내용을 복사해서 OpenWeatherMap_OpenAPI_명세서.json 파일로 저장하시면 됩니다.

{
  "openapi": "3.0.0",
  "info": {
    "title": "OpenWeatherMap Minimal API Spec",
    "version": "1.0.0",
    "description": "Google ADK OpenAPIToolset 연동을 위한 OpenWeatherMap 경량 명세서"
  },
  "servers": [
    {
      "url": "https://api.openweathermap.org"
    }
  ],
  "paths": {
    "/data/2.5/weather": {
      "get": {
        "summary": "Get current weather data",
        "operationId": "getCurrentWeather",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "description": "도시 이름 (예: Seoul,KR 또는 Tokyo)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "units",
            "in": "query",
            "required": false,
            "description": "온도 단위 (섭씨를 원하면 metric 설정)",
            "schema": {
              "type": "string",
              "default": "metric"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response"
          }
        }
      }
    },
    "/data/2.5/forecast": {
      "get": {
        "summary": "Get 5 day/3 hour forecast data",
        "operationId": "getForecast",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "description": "도시 이름 (예: Seoul,KR)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "units",
            "in": "query",
            "required": false,
            "description": "온도 단위 (섭씨를 원하면 metric 설정)",
            "schema": {
              "type": "string",
              "default": "metric"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response"
          }
        }
      }
    }
  }
}

이 방식이 가장 현명한 이유와 개발 팁

에러 원천 차단 (Minimalism): 공식 스펙에는 인증 방식, 스키마 컴포넌트 참조($ref) 등이 복잡하게 얽혀 있어 ADK 파서가 간혹 에러를 뿜어냅니다. 필요한 파라미터(q, units)만 플랫(Flat)하게 정의해 두면 파싱 에러가 절대 나지 않습니다.
API Key 중복 제거: 코드 4에서 이미 auth_helpers를 통해 appid를 공통 쿼리 파라미터로 자동 주입하도록 세팅해 두었으므로, JSON 명세서 안의 parameters 목록에는 q와 units만 정의해 주는 것이 깔끔합니다.
확장성: 나중에 다른 API(예: 미세먼지 API 등)를 연동할 때도 이와 동일한 구조로 필요한 경로(paths)만 JSON에 추가해주면 코드를 수정할 필요 없이 에이전트가 능동적으로 툴을 확장해서 사용하게 됩니다.

*[ Gemini에게 줄 정보]

OpenWeatherMap과 같은 외부 서비스(또는 전혀 다른 새로운 API)를 위한 맞춤형 OpenAPI JSON 명세서(OpenAPI_명세서.json)를 정확하고 완벽하게 작성해 드리려면, 보통 다음과 같은 3가지 핵심 정보를 알려주셔야 합니다.

1. 기본 서버 정보 (Base URL & API 이름)

API 기본 주소 (Base URL): API 요청이 시작되는 공통 도메인 주소 (예: [https://api.openweathermap.org](https://api.openweathermap.org))
API 이름 및 목적: 어떤 서비스를 연동하는 것인지 (예: "날씨 조회 API", "주식 시세 API")

2. 사용할 엔드포인트와 기능 (Paths & Methods)

어떤 경로(Path)를 쓸 것인가?: 문서에서 에이전트가 실제로 호출했으면 하는 API 경로 (예: /data/2.5/weather, /v1/search)
HTTP 메서드: 주로 GET 방식인지, 데이터를 보내는 POST 방식인지 여부

3. 파라미터 (Parameters / Request Body)

입력값(파라미터): 사용자가 질문했을 때 에이전트가 API로 넘겨주어야 하는 필수/선택 값들
- 예: 도시 이름(q), 위경도(lat, lon), 검색어(keyword), 페이지 번호(page) 등
- 쿼리 파라미터(query)로 들어가는지, 경로(path)에 포함되는지, 혹은 POST의 본문(body)으로 들어가는지 여부

💡 Tip: 복잡한 공식 API 문서 전체를 줄 필요는 없습니다. API 공식 문서의 "Example Request(요청 예시)" 주소나 "Parameters(매개변수) 표" 정도만 텍스트나 링크로 툭 던져주시면, 그 내용을 분석해서 Google ADK가 가장 에러 없이 완벽하게 읽어 들일 수 있는 명세서 JSON으로 뚝딱 만들어 드립니다!

** [반드시 확인하고 뽑아내야 하는 핵심 정보]

OpenWeatherMap의 두 공식 문서 페이지(current와 forecast5)에서 OpenAPI JSON 명세서를 정교하게 작성하기 위해 반드시 확인하고 뽑아내야 하는 핵심 정보는 크게 3가지(엔드포인트, 요청 파라미터, 응답 필드 구조)입니다.

각 페이지에서 어떤 정보를 구체적으로 확인해야 하는지 항목별로 집어드리겠습니다.

1. API 엔드포인트 경로 (Paths)

문서 상단이나 'API call' 섹션에서 실제 요청을 날릴 URL의 경로를 확인해야 합니다.

현재 날씨 (Current Weather) 페이지:
- 경로: /data/2.5/weather
5일 예보 (5 Day Forecast) 페이지:
- 경로: /data/2.5/forecast
공통 서버 Base URL: [https://api.openweathermap.org](https://api.openweathermap.org)

2. 요청 파라미터 (Parameters) - 가장 중요

에이전트가 사용자의 질문을 받고 API를 호출할 때 전달해야 하는 쿼리스트링(Query Parameter) 목록입니다. 두 페이지 모두 공통적으로 다음 파라미터들을 지원합니다.

q (필수 수준의 입력값): 도시 이름 (예: Seoul, London,uk)
units (선택값): 온도 단위 설정 (metric: 섭씨, imperial: 화씨, standard: 켈빈)
lang (선택값): 응답 언어 설정 (예: kr 지정 시 날씨 설명이 한글로 반환)
appid (필수 인증값): 사용자의 API Key (코드 4처럼 auth_helpers로 자동 주입할 경우 명세서 파라미터에는 생략 가능)

3. 주요 응답 데이터 구조 (Response Fields) - 에이전트 지침 작성용

명세서 자체에는 필수가 아니지만, 에이전트의 instruction 프롬프트를 작성할 때 어떤 키(Key)를 파싱해야 하는지 문서의 "Example of API response" 영역을 보고 파악해야 합니다.

현재 날씨(/weather) 응답 핵심 필드:
- main.temp: 현재 온도
- main.feels_like: 체감 온도
- weather[0].description: 날씨 상세 설명 (예: "clear sky", "light rain")
5일 예보(/forecast) 응답 핵심 필드:
- list: 3시간 간격의 예보 데이터 배열
- list[i].dt_txt: 예보 일시 (예: "2026-06-07 15:00:00")
- list[i].main.temp: 해당 시간대의 예보 온도
- list[i].weather[0].description: 해당 시간대의 날씨 설명

💡 [종합] 현재 날씨와 5일 예보를 모두 지원하는 완성형 JSON 명세서

위 링크들의 정보를 종합하여, 즉시 투입할 수 있는 [현재 날씨 + 5일 예보 통합 OpenAPI 3.0 JSON 명세서] 구성.

{
  "openapi": "3.0.0",
  "info": {
    "title": "OpenWeatherMap Current & Forecast API",
    "version": "1.0.0",
    "description": "현재 날씨와 5일간의 3시간 단위 예보를 조회하는 통합 명세서"
  },
  "servers": [
    {
      "url": "https://api.openweathermap.org"
    }
  ],
  "paths": {
    "/data/2.5/weather": {
      "get": {
        "summary": "Get current weather data",
        "operationId": "getCurrentWeather",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "description": "도시 이름 (예: Seoul 또는 New York,US)",
            "schema": { "type": "string" }
          },
          {
            "name": "units",
            "in": "query",
            "required": false,
            "description": "온도 단위 (metric 설정 시 섭씨)",
            "schema": { "type": "string", "default": "metric" }
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "description": "응답 언어 (kr 설정 시 한국어)",
            "schema": { "type": "string", "default": "kr" }
          }
        ],
        "responses": { "200": { "description": "Successful response" } }
      }
    },
    "/data/2.5/forecast": {
      "get": {
        "summary": "Get 5 day / 3 hour forecast data",
        "operationId": "getForecastWeather",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "description": "도시 이름 (예: Seoul)",
            "schema": { "type": "string" }
          },
          {
            "name": "units",
            "in": "query",
            "required": false,
            "description": "온도 단위 (metric 설정 시 섭씨)",
            "schema": { "type": "string", "default": "metric" }
          },
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "description": "응답 언어 (kr 설정 시 한국어)",
            "schema": { "type": "string", "default": "kr" }
          }
        ],
        "responses": { "200": { "description": "Successful response" } }
      }
    }
  }
}

저작자표시 비영리 변경금지 (새창열림)