날씨 정보 에이전트 개발의 이점
복합적인 AI 에이전트 개발에 앞서, ‘날씨 정보 에이전트’는 다음과 같은 실용적인 이점으로 인해 학습 초기 단계에 매우 적합한 프로젝트입니다.
- 단순한 데이터 소스: OpenWeatherMap과 같은 단일 API를 활용함으로써 데이터 수집의 복잡성을 최소화합니다.
- 간결한 데이터 처리: 수집된 JSON 형식의 데이터를 직접 파싱하여 활용하므로, 복잡한 인공지능(AI) 기반의 자연어 처리 과정(예: 텍스트 요약)이 필수적이지 않습니다.
- 명확한 입/출력: 사용자로부터 도시 이름을 입력받아 현재 날씨 정보를 출력하는 명확한 인터페이스를 제공합니다.
- 신속한 결과 확인: 개발 과정에서 코드 실행 후 즉각적인 결과 확인이 가능하여, 학습자의 동기 부여 및 성취감 증진에 기여합니다.
개발 일정 (3일 완성 계획)
본 프로젝트는 총 3일의 개발 기간을 기준으로 구성되었으며, 각 단계별 목표는 다음과 같습니다.
- 1일차: 개발 환경 구축 및 API 키 확보
- 2일차: 핵심 기능 구현 (API 호출 및 데이터 처리)
- 3일차: 에이전트 완성 및 테스트
세부 개발 항목 및 단계별 지침
각 개발 단계에 필요한 구체적인 항목과 실질적인 지침을 제공하오니, 순서대로 따라오시면 성공적인 에이전트 개발이 가능할 것입니다.
1단계: 개발 환경 준비 (1일차 오전)
이 단계는 모든 파이썬 기반 프로젝트의 기본 설정에 해당합니다.
- 파이썬(Python) 설치:
- Python 공식 웹사이트에서 최신 버전을 다운로드하여 설치합니다.
- 설치 시 “Add Python.exe to PATH” 옵션을 반드시 선택하여 명령 프롬프트(터미널)에서 python 명령어를 직접 사용할 수 있도록 설정합니다.
- 설치 확인: 터미널에서 python –version 또는 python3 –version을 입력하여 버전 정보가 정상적으로 출력되는지 확인합니다.
- Visual Studio Code (VS Code) 설치 및 설정:
- VS Code 공식 웹사이트에서 VS Code를 다운로드하여 설치합니다.
- VS Code 실행 후, 좌측 사이드바의 ‘확장(Extensions)’ 아이콘을 클릭하고 Microsoft가 제공하는 ‘Python’ 확장 프로그램을 설치합니다.
- 가상 환경(Virtual Environment) 설정:
- 프로젝트별 라이브러리 의존성 관리를 위해 가상 환경을 사용합니다.
- 프로젝트 폴더 (my_weather_agent)를 생성하고 VS Code에서 해당 폴더를 엽니다.
- VS Code 터미널 (터미널(Terminal) > 새 터미널(New Terminal))을 엽니다.
- 가상 환경 생성: python -m venv venv
- 가상 환경 활성화:
- Windows: .\venv\Scripts\activate
- macOS/Linux: source venv/bin/activate
- 터미널 프롬프트 앞에 (venv)가 표시되면 성공입니다.
2단계: OpenWeatherMap API 키 확보 및 이해 (1일차 오후)
날씨 정보 조회를 위한 핵심 서비스인 OpenWeatherMap API를 설정합니다.
- OpenWeatherMap 회원가입 및 API 키 발급:
- OpenWeatherMap 웹사이트에 접속하여 계정을 생성하고 로그인합니다.
- 로그인 후 ‘API keys’ 탭에서 생성된 API 키를 확인하고 복사합니다. 이 키는 외부에 노출되지 않도록 각별히 유의해야 합니다.
- 참고: API 키 발급 후 실제 데이터 사용까지는 다소 시간이 소요될 수 있습니다.
- API 문서 간략히 이해:
- Current Weather Data API 문서를 통해 API 호출을 위한 기본 URL 및 필수 파라미터(예: q for city name, appid for API key, units for temperature unit, lang for language)를 파악합니다.
- API 호출 시 반환되는 JSON 데이터의 구조를 미리 확인하여 필요한 정보를 추출하는 방식을 이해합니다.
3단계: 핵심 기능 구현 (2일차 오전)
본격적으로 파이썬 코드를 작성하여 날씨 정보를 호출하고 출력하는 기능을 구현합니다.
- 필요 라이브러리 설치:
- requests: HTTP 요청을 전송하는 데 사용됩니다.
- python-dotenv: 환경 변수로부터 API 키를 안전하게 로드하는 데 사용됩니다.
- 활성화된 가상 환경 터미널에서 다음 명령어를 입력합니다:
Bash
pip install requests python-dotenv
- API 키 안전 관리 (.env 파일):
- 프로젝트 폴더 내에 .env라는 이름의 파일을 새로 생성합니다.
- OPENWEATHER_API_KEY=”귀하의_API_키” 형식으로 발급받은 API 키를 저장합니다.
- 중요: .env 파일은 Git(GitHub)에 업로드되지 않도록 .gitignore 파일에 반드시 추가해야 합니다.
- weather_agent.py 파일 생성 및 코드 작성:
- 프로젝트 폴더 내에 weather_agent.py 파일을 생성합니다.
- 아래 코드를 복사하여 붙여넣고, 각 섹션의 주석을 참조하여 기능별 역할을 이해합니다.
Python
# weather_agent.py
import os
import requests
from dotenv import load_dotenv
# — 1. 설정 정보 불러오기 —
load_dotenv()
API_KEY = os.getenv(“OPENWEATHER_API_KEY”)
BASE_URL = “http://api.openweathermap.org/data/2.5/weather”
if not API_KEY:
print(“경고: OpenWeatherMap API 키가 .env 파일에 설정되지 않았습니다.”)
print(“`.env` 파일에 `OPENWEATHER_API_KEY=\”YOUR_API_KEY\”` 형식으로 키를 입력해주십시오.”)
# — 2. 날씨 정보 가져오는 함수 —
def get_weather_data(city_name):
“””
주어진 도시 이름으로 OpenWeatherMap API를 호출하여 날씨 데이터를 가져옵니다.
“””
params = {
“q”: city_name,
“appid”: API_KEY,
“units”: “metric”, # 섭씨
“lang”: “kr” # 한국어 설명
}
try:
response = requests.get(BASE_URL, params=params)
response.raise_for_status() # HTTP 오류 발생 시 예외 발생
weather_data = response.json()
return weather_data
except requests.exceptions.RequestException as e:
print(f”네트워크 오류 또는 API 요청 실패: {e}”)
return None
except ValueError as e:
print(f”API 응답 파싱 오류: {e}. 응답 내용: {response.text[:200]}…”)
return None
except Exception as e:
print(f”예상치 못한 오류 발생: {e}”)
return None
# — 3. 날씨 정보를 보기 좋게 출력하는 함수 —
def display_weather_info(weather_data):
“””
가져온 날씨 데이터를 콘솔에 가독성 높게 출력합니다.
“””
if weather_data is None:
print(“날씨 정보를 가져올 수 없습니다. 도시 이름을 다시 확인하거나 API 키 설정을 점검하십시오.”)
return
try:
city = weather_data[“name”]
country = weather_data[“sys”][“country”]
temperature = weather_data[“main”][“temp”]
feels_like = weather_data[“main”][“feels_like”]
humidity = weather_data[“main”][“humidity”]
description = weather_data[“weather”][0][“description”]
wind_speed = weather_data[“wind”][“speed”]
pressure = weather_data[“main”][“pressure”]
print(f”\n— {city}, {country} 현재 날씨 —“)
print(f”날씨 상태: {description.capitalize()}”)
print(f”현재 온도: {temperature}°C”)
print(f”체감 온도: {feels_like}°C”)
print(f”습도: {humidity}%”)
print(f”바람 속도: {wind_speed} m/s”)
print(f”기압: {pressure} hPa”)
print(“—————————–\n”)
except KeyError as e:
print(f”날씨 데이터에서 필수 정보를 찾을 수 없습니다: {e}”)
print(“API 응답 구조가 예상과 다르거나, 정보가 누락되었을 수 있습니다.”)
print(f”API 응답 전체 (디버깅용): {weather_data}”)
except IndexError as e:
print(f”날씨 상태 정보를 찾을 수 없습니다: {e}”)
print(f”API 응답 전체 (디버깅용): {weather_data}”)
except Exception as e:
print(f”날씨 정보 출력 중 예상치 못한 오류 발생: {e}”)
# — 4. 메인 실행 부분 —
if __name__ == “__main__”:
print(“AI 날씨 정보 에이전트에 오신 것을 환영합니다.”)
print(“종료하시려면 ‘종료’ 또는 ‘quit’을 입력하십시오.”)
while True:
city_input = input(“날씨를 조회할 도시 이름을 입력하십시오 (예: Seoul, Tokyo, New York): “)
if city_input.lower() in [“종료”, “quit”]:
print(“날씨 에이전트를 종료합니다. 이용해 주셔서 감사합니다.”)
break
if not API_KEY:
print(“API 키가 없어 날씨 정보를 조회할 수 없습니다. .env 파일을 확인해주십시오.”)
continue
weather_data = get_weather_data(city_input)
display_weather_info(weather_data)
4단계: 에이전트 완성 및 테스트 (3일차)
작성된 코드를 실행하고, 다양한 시나리오에서 에이전트가 올바르게 작동하는지 검증합니다.
- 코드 실행 및 테스트:
- VS Code 터미널에서 (가상 환경이 활성화된 상태) python weather_agent.py 명령어를 입력합니다.
- 정상 작동 확인: Seoul, Tokyo, New York 등 유효한 도시 이름을 입력하여 올바른 날씨 정보가 출력되는지 확인합니다.
- 오류 처리 확인:
- asdfasdf와 같이 존재하지 않는 도시를 입력하여 오류 메시지가 적절히 처리되는지 확인합니다.
- 인터넷 연결을 일시적으로 끊어 네트워크 오류 발생 시 에이전트의 반응을 확인합니다.
- .env 파일에서 API 키를 임의로 변경하거나 삭제하여 API 키 오류 상황을 테스트합니다.
- 종료 확인: 종료 또는 quit을 입력하여 프로그램이 정상적으로 종료되는지 확인합니다.
- 코드 정리 및 주석 추가:
- 코드의 가독성을 높이기 위해 중요한 함수나 로직에 대한 주석을 추가합니다.
- 테스트용 print문 등 불필요한 코드는 제거하거나 주석 처리합니다.
- (선택 사항) README.md 파일 작성 및 Git/GitHub 버전 관리:
- README.md 생성: 프로젝트 폴더 내에 README.md 파일을 생성하고, 프로젝트의 개요, 설치 및 사용 방법, 주요 기능 등을 Markdown 문법으로 작성합니다.
- .gitignore 파일 업데이트: 프로젝트 폴더 내 .gitignore 파일에 다음 내용을 추가하여 민감 정보 및 불필요 파일이 Git 저장소에 업로드되지 않도록 합니다.
venv/
__pycache__/
.env - Git 커밋 및 푸시: git add ., git commit -m “feat: Initial weather agent complete”, git push 명령어를 활용하여 코드 버전을 관리하고 GitHub에 백업합니다.