에이전트 환경 설정과 맛보기

AI 에이전트 개발을 위한 첫걸음을 안내합니다. 파이썬 가상 환경 구축부터 OpenAI API 연동, 첫 에이전트 실행까지 초보자도 쉽게 따라할 수 있도록 단계별로 설명합니다.

1. 파이썬 가상 환경 생성하기

김개발 씨는 회사에서 AI 에이전트 프로젝트를 맡게 되었습니다. 설레는 마음으로 패키지를 설치하려는 순간, 선배가 다가와 말했습니다.

"잠깐, 가상 환경부터 만들었어요?"

가상 환경은 프로젝트마다 독립된 파이썬 실행 환경을 만들어주는 기능입니다. 마치 아파트의 각 세대가 독립된 공간인 것처럼, 프로젝트별로 서로 다른 패키지 버전을 사용할 수 있게 해줍니다.

이를 통해 프로젝트 간 패키지 충돌을 방지하고 깔끔한 개발 환경을 유지할 수 있습니다.

다음 코드를 살펴봅시다.

# 프로젝트 폴더 생성
mkdir ai-agent-project
cd ai-agent-project

# 파이썬 가상 환경 생성 (venv라는 이름으로)
python -m venv venv

# 가상 환경 활성화 (Linux/Mac)
source venv/bin/activate

# 가상 환경 활성화 (Windows)
# venv\Scripts\activate

# 활성화 확인 - 프롬프트 앞에 (venv)가 표시됩니다
which python

김개발 씨는 입사 후 첫 AI 프로젝트를 맡게 되었습니다. 인터넷에서 찾은 튜토리얼을 따라 바로 pip install을 실행하려던 참이었습니다.

"잠깐요." 선배 개발자 박시니어 씨가 말했습니다. "가상 환경 없이 패키지를 설치하면 나중에 큰 문제가 생길 수 있어요." 그렇다면 가상 환경이란 정확히 무엇일까요?

쉽게 비유하자면, 가상 환경은 마치 요리사의 개인 주방과 같습니다. 여러 요리사가 하나의 주방을 공유하면 재료가 섞이고 도구가 엉키기 쉽습니다.

하지만 각자의 주방이 있다면 원하는 재료와 도구를 자유롭게 배치할 수 있습니다. 파이썬 가상 환경도 마찬가지로, 프로젝트마다 필요한 패키지를 독립적으로 관리할 수 있게 해줍니다.

가상 환경이 없던 시절에는 어땠을까요? 모든 패키지가 시스템 전역에 설치되었습니다.

A 프로젝트에서 openai 버전 0.28을 사용하고, B 프로젝트에서 openai 버전 1.0을 사용해야 한다면? 두 버전을 동시에 설치할 수 없어서 프로젝트를 전환할 때마다 패키지를 재설치해야 했습니다.

더 큰 문제는 의존성 충돌이었습니다. 서로 다른 패키지가 같은 라이브러리의 다른 버전을 요구하면 시스템 전체가 엉망이 되곤 했습니다.

바로 이런 문제를 해결하기 위해 가상 환경이 등장했습니다. python -m venv 명령어는 파이썬에 내장된 가상 환경 생성 도구입니다.

venv는 virtual environment의 약자로, 지정한 폴더에 독립된 파이썬 환경을 만들어줍니다. 위 코드를 한 줄씩 살펴보겠습니다.

먼저 mkdir과 cd 명령어로 프로젝트 폴더를 만들고 이동합니다. 그다음 python -m venv venv 명령어가 핵심입니다.

여기서 첫 번째 venv는 파이썬의 가상 환경 모듈을 의미하고, 두 번째 venv는 생성할 폴더 이름입니다. 폴더 이름은 자유롭게 지정할 수 있지만, 관례적으로 venv나 .venv를 많이 사용합니다.

가상 환경을 만들었다고 바로 사용할 수 있는 것은 아닙니다. source venv/bin/activate 명령어로 가상 환경을 활성화해야 합니다.

활성화에 성공하면 터미널 프롬프트 앞에 (venv)라는 표시가 나타납니다. 이제부터 설치하는 모든 패키지는 이 가상 환경 안에만 설치됩니다.

Windows 사용자라면 활성화 명령어가 조금 다릅니다. venv\Scripts\activate를 사용해야 합니다.

운영체제별로 경로 구분자와 스크립트 위치가 다르기 때문입니다. 실제 현업에서는 어떻게 활용할까요?

대부분의 회사에서 프로젝트마다 가상 환경을 필수로 사용합니다. 특히 requirements.txt 파일과 함께 사용하면 팀원 모두가 동일한 개발 환경을 구축할 수 있습니다.

CI/CD 파이프라인에서도 가상 환경을 통해 일관된 빌드 환경을 보장합니다. 하지만 주의할 점도 있습니다.

초보 개발자들이 흔히 하는 실수 중 하나는 가상 환경 폴더를 Git에 커밋하는 것입니다. venv 폴더는 용량이 크고 운영체제마다 내용이 다르므로 .gitignore에 반드시 추가해야 합니다.

다시 김개발 씨의 이야기로 돌아가 봅시다. 박시니어 씨의 조언을 듣고 가상 환경을 먼저 만든 김개발 씨는 안도의 한숨을 쉬었습니다.

"처음부터 제대로 시작하길 잘했네요!"

실전 팁

💡 - 가상 환경 폴더는 반드시 .gitignore에 추가하세요

작업을 마치면 deactivate 명령어로 가상 환경을 비활성화할 수 있습니다
conda를 사용한다면 conda create -n 환경이름 python=3.11 형식을 사용합니다

2. 필수 패키지 설치하기

가상 환경을 성공적으로 만든 김개발 씨는 이제 본격적으로 AI 에이전트 개발에 필요한 패키지를 설치할 차례입니다. "pip install로 설치하면 되는 건 알겠는데, 정확히 어떤 패키지가 필요한 거죠?"

AI 에이전트 개발에는 openai 패키지가 핵심입니다. 이 패키지는 OpenAI의 GPT 모델과 통신하기 위한 공식 라이브러리입니다.

추가로 환경 변수를 관리하는 python-dotenv와 비동기 처리를 위한 httpx 패키지도 함께 설치하면 더욱 안정적인 개발이 가능합니다.

다음 코드를 살펴봅시다.

# 가상 환경이 활성화된 상태에서 실행
# pip 최신 버전으로 업그레이드
pip install --upgrade pip

# OpenAI 공식 패키지 설치
pip install openai

# 환경 변수 관리용 패키지
pip install python-dotenv

# 설치된 패키지 목록 확인
pip list

# 나중을 위해 requirements.txt 생성
pip freeze > requirements.txt

가상 환경을 활성화한 김개발 씨의 터미널 프롬프트 앞에는 이제 (venv)가 떠 있습니다. 드디어 패키지를 설치할 준비가 된 것입니다.

"먼저 pip부터 업그레이드하는 게 좋아요." 박시니어 씨가 조언했습니다. "오래된 pip는 최신 패키지를 제대로 설치하지 못할 때가 있거든요." pip는 파이썬의 패키지 관리 도구입니다.

마치 스마트폰의 앱스토어처럼, pip를 통해 전 세계 개발자들이 만든 수만 개의 패키지를 손쉽게 설치할 수 있습니다. pip install --upgrade pip 명령어로 pip 자체를 최신 버전으로 업그레이드하는 것이 좋은 습관입니다.

AI 에이전트 개발의 핵심 패키지는 단연 openai입니다. 이 패키지는 OpenAI 회사에서 공식적으로 제공하는 파이썬 라이브러리입니다.

GPT-4, GPT-3.5-turbo 등의 언어 모델과 통신하고, 채팅 완성, 텍스트 임베딩, 이미지 생성 등 다양한 AI 기능을 사용할 수 있게 해줍니다. pip install openai 명령어 하나로 필요한 모든 의존성이 함께 설치됩니다.

openai 패키지는 내부적으로 httpx, pydantic, typing-extensions 등 여러 라이브러리를 사용합니다. pip가 이러한 의존성을 자동으로 파악하고 함께 설치해주므로 개발자는 신경 쓸 필요가 없습니다.

다음으로 중요한 패키지는 python-dotenv입니다. 이 패키지는 .env 파일에서 환경 변수를 읽어오는 기능을 제공합니다.

API 키처럼 민감한 정보를 코드에 직접 작성하면 보안 문제가 생길 수 있습니다. python-dotenv를 사용하면 이런 정보를 별도 파일로 분리하여 안전하게 관리할 수 있습니다.

설치가 완료되면 pip list 명령어로 확인해봅시다. 설치된 모든 패키지와 버전 정보가 목록으로 출력됩니다.

openai, python-dotenv와 함께 자동으로 설치된 의존성 패키지들도 볼 수 있습니다. 마지막으로 pip freeze > requirements.txt 명령어가 중요합니다.

이 명령어는 현재 설치된 모든 패키지와 정확한 버전을 requirements.txt 파일로 저장합니다. 팀원이나 서버에서 동일한 환경을 구축할 때 pip install -r requirements.txt 명령어로 한 번에 모든 패키지를 설치할 수 있습니다.

실무에서는 requirements.txt 관리가 필수입니다. 개발 환경과 운영 환경의 패키지 버전이 다르면 예상치 못한 버그가 발생할 수 있습니다.

requirements.txt를 Git에 커밋해두면 언제 어디서든 동일한 환경을 재현할 수 있습니다. 주의할 점이 있습니다.

간혹 pip install openai를 실행했는데 권한 오류가 발생하는 경우가 있습니다. 이는 가상 환경이 활성화되지 않은 상태에서 시스템 파이썬에 설치하려 했기 때문입니다.

터미널 프롬프트에 (venv)가 표시되어 있는지 반드시 확인하세요. 김개발 씨는 pip list 결과를 보며 뿌듯해했습니다.

"이제 진짜 AI 에이전트를 만들 준비가 된 것 같아요!"

실전 팁

💡 - 패키지 버전을 고정하려면 pip install openai==1.0.0처럼 버전을 명시하세요

pip show openai 명령어로 특정 패키지의 상세 정보를 확인할 수 있습니다
패키지 삭제는 pip uninstall 패키지명으로 합니다

3. OpenAI API Key 발급받기

패키지 설치를 마친 김개발 씨가 예제 코드를 실행하자 에러가 발생했습니다. "API key가 없다고요?

이건 어디서 받는 거죠?" OpenAI 서비스를 사용하려면 반드시 API 키가 필요합니다.

API 키는 OpenAI 서버에 접근하기 위한 인증 수단입니다. 마치 건물에 들어가기 위한 출입증처럼, API 키가 있어야만 GPT 모델을 사용할 수 있습니다.

OpenAI 플랫폼에서 계정을 만들고 무료 크레딧으로 시작할 수 있으며, 발급받은 키는 절대로 외부에 노출되어서는 안 됩니다.

다음 코드를 살펴봅시다.

# 1. OpenAI 플랫폼 접속
# https://platform.openai.com 에 접속합니다

# 2. 회원가입 또는 로그인
# Google, Microsoft, Apple 계정으로 간편 가입 가능

# 3. API Keys 메뉴로 이동
# 좌측 메뉴에서 "API keys" 클릭

# 4. 새 키 생성
# "Create new secret key" 버튼 클릭
# 키 이름 입력 (예: "my-first-agent")

# 5. 키 복사 및 안전하게 보관
# sk-proj-xxxxx... 형태의 키가 생성됩니다
# 이 키는 한 번만 표시되므로 반드시 복사해두세요!

예제 코드를 실행한 김개발 씨의 화면에 빨간 에러 메시지가 떴습니다. "AuthenticationError: No API key provided." API 키가 없다는 것입니다.

"API 키는 OpenAI 홈페이지에서 발급받아야 해요." 박시니어 씨가 모니터를 가리켰습니다. API 키란 무엇일까요?

쉽게 비유하자면, API 키는 마치 회사 출입 카드와 같습니다. 건물에 들어가려면 출입 카드를 찍어야 하듯이, OpenAI의 AI 서비스를 이용하려면 API 키로 인증해야 합니다.

이 키를 통해 OpenAI는 누가 서비스를 사용하는지 파악하고, 사용량에 따라 요금을 청구합니다. 먼저 platform.openai.com에 접속합니다.

이곳은 OpenAI의 개발자 플랫폼입니다. 일반 사용자가 ChatGPT를 사용하는 chat.openai.com과는 다른 사이트입니다.

개발자 플랫폼에서는 API 키 관리, 사용량 확인, 요금 결제 등을 할 수 있습니다. 회원가입은 간단합니다.

Google, Microsoft, Apple 계정이 있다면 클릭 한 번으로 가입할 수 있습니다. 새로 가입하면 일정 금액의 무료 크레딧을 제공받으므로 비용 걱정 없이 학습을 시작할 수 있습니다.

로그인 후 좌측 메뉴에서 API keys를 찾습니다. 이 메뉴에서 API 키를 생성하고 관리할 수 있습니다.

이미 만들어둔 키 목록도 여기서 확인할 수 있습니다. 단, 키의 전체 내용은 생성 시점에만 볼 수 있고, 이후에는 앞부분만 표시됩니다.

Create new secret key 버튼을 클릭합니다. 키에 이름을 붙일 수 있는데, 나중에 어떤 용도로 만든 키인지 구분하기 쉽도록 의미 있는 이름을 붙이는 것이 좋습니다.

예를 들어 "my-first-agent"나 "local-dev-key" 같은 이름을 사용할 수 있습니다. 생성된 키는 **sk-proj-**로 시작하는 긴 문자열입니다.

이 키는 화면에 딱 한 번만 표시됩니다. 창을 닫으면 다시는 전체 키를 볼 수 없으므로, 반드시 안전한 곳에 복사해두어야 합니다.

키를 분실하면 새로 발급받는 수밖에 없습니다. API 키 보안은 매우 중요합니다.

키가 유출되면 다른 사람이 여러분의 계정으로 API를 사용할 수 있고, 그 비용은 고스란히 여러분에게 청구됩니다. GitHub에 코드를 올릴 때 API 키가 포함되지 않도록 각별히 주의해야 합니다.

실제로 많은 개발자가 이 실수로 큰 금전적 손해를 입은 사례가 있습니다. OpenAI 플랫폼에서는 사용량 제한을 설정할 수 있습니다.

Settings > Limits 메뉴에서 월별 사용 한도를 설정해두면, 실수로 과도한 API 호출을 하더라도 일정 금액 이상 청구되지 않도록 보호받을 수 있습니다. 처음에는 낮은 금액으로 설정해두는 것을 권장합니다.

김개발 씨는 발급받은 키를 메모장에 임시 저장했습니다. "이제 이 키를 어떻게 사용하는 거죠?"

실전 팁

💡 - API 키는 절대로 코드에 직접 작성하지 마세요

키가 노출되었다면 즉시 폐기하고 새로 발급받으세요
사용량 제한을 미리 설정하여 예상치 못한 요금 청구를 방지하세요

4. 환경 변수 설정하기

API 키를 발급받은 김개발 씨가 코드에 키를 직접 입력하려 하자, 박시니어 씨가 급히 말렸습니다. "잠깐요!

그렇게 하면 나중에 큰일 납니다. 환경 변수로 관리해야 해요."

환경 변수는 운영체제 수준에서 관리되는 설정값입니다. API 키처럼 민감한 정보를 코드와 분리하여 보안을 강화하고, 개발/운영 환경별로 다른 설정을 적용할 수 있게 해줍니다.

python-dotenv 패키지를 사용하면 .env 파일에서 환경 변수를 쉽게 불러올 수 있습니다.

다음 코드를 살펴봅시다.

# .env 파일 생성 (프로젝트 루트 폴더에)
# 파일명 앞에 점(.)이 붙는 것에 주의하세요

# .env 파일 내용
OPENAI_API_KEY=sk-proj-your-actual-api-key-here

# .gitignore 파일에 추가 (필수!)
# .env

# Python 코드에서 환경 변수 불러오기
from dotenv import load_dotenv
import os

# .env 파일 로드
load_dotenv()

# 환경 변수 가져오기
api_key = os.getenv("OPENAI_API_KEY")
print(f"API Key loaded: {api_key[:10]}...")  # 앞 10자만 출력

김개발 씨는 코드 파일을 열고 API 키를 직접 입력하려 했습니다. api_key = "sk-proj-xxxx..." 이렇게 말입니다.

"절대 그러면 안 돼요!" 박시니어 씨가 손을 저었습니다. "코드에 키를 직접 넣으면 Git에 올렸을 때 전 세계에 공개되는 거예요." 환경 변수란 무엇일까요?

쉽게 비유하자면, 환경 변수는 마치 금고 속 비밀번호 메모와 같습니다. 중요한 비밀번호를 포스트잇에 적어 모니터에 붙여두면 누구나 볼 수 있습니다.

하지만 금고에 넣어두면 금고 주인만 열어볼 수 있죠. 환경 변수도 마찬가지로, 코드와 분리된 안전한 공간에 민감한 정보를 보관하는 방법입니다.

먼저 프로젝트 폴더에 .env 파일을 만듭니다. 파일명 앞에 점(.)이 붙는 것에 주의하세요.

이는 Unix 시스템에서 숨김 파일을 의미합니다. Windows에서는 파일 탐색기에서 "숨김 항목 표시"를 켜야 보일 수 있습니다.

.env 파일 안에는 키=값 형식으로 환경 변수를 작성합니다. OPENAI_API_KEY=sk-proj-xxxxx 형태로 작성하면 됩니다.

등호(=) 앞뒤에 공백을 넣지 않는 것이 중요합니다. 여러 개의 환경 변수가 필요하다면 각 줄에 하나씩 작성합니다.

가장 중요한 단계는 .gitignore에 .env를 추가하는 것입니다. .gitignore 파일은 Git이 추적하지 않을 파일 목록을 지정합니다.

.env를 여기에 추가하면 git add . 명령을 실행해도 .env 파일은 스테이징되지 않습니다.

이렇게 해야 실수로 API 키가 GitHub에 공개되는 것을 방지할 수 있습니다. 파이썬 코드에서는 python-dotenv를 사용해 환경 변수를 불러옵니다.

load_dotenv() 함수를 호출하면 .env 파일의 내용을 읽어서 환경 변수로 등록합니다. 이후 **os.getenv("OPENAI_API_KEY")**로 값을 가져올 수 있습니다.

os.getenv의 장점은 환경 변수가 없어도 에러가 나지 않는다는 것입니다. 대신 None을 반환합니다.

기본값을 지정하고 싶다면 os.getenv("KEY", "default_value") 형태로 두 번째 인자를 전달할 수 있습니다. 실무에서는 환경별로 다른 .env 파일을 사용합니다.

개발 환경에서는 .env.development, 운영 환경에서는 .env.production을 사용하는 식입니다. load_dotenv(".env.development")처럼 파일 경로를 명시적으로 지정할 수도 있습니다.

주의할 점이 있습니다. .env 파일을 만들기 전에 이미 git add를 했다면, .gitignore에 추가해도 계속 추적됩니다.

이 경우 git rm --cached .env 명령으로 추적을 해제해야 합니다. 김개발 씨는 .env 파일을 만들고 .gitignore도 수정했습니다.

테스트 코드를 실행하니 "API Key loaded: sk-proj-xx..."라는 메시지가 출력되었습니다. "이제 안전하게 API 키를 사용할 수 있겠네요!"

실전 팁

💡 - .env 파일은 항상 프로젝트 루트 폴더에 위치시키세요

팀 프로젝트에서는 .env.example 파일로 필요한 환경 변수 목록을 공유하세요
운영 환경에서는 .env 대신 서버의 실제 환경 변수를 사용하는 것이 더 안전합니다

5. 첫 에이전트 소스 코드 작성

환경 설정을 모두 마친 김개발 씨가 드디어 본격적인 코딩에 들어갑니다. "이제 진짜 AI 에이전트를 만들어볼 시간이에요!" 선배의 말에 김개발 씨의 눈이 반짝였습니다.

AI 에이전트의 핵심은 OpenAI API와 대화하는 것입니다. openai 패키지의 ChatCompletion 기능을 사용하면 GPT 모델에 메시지를 보내고 응답을 받을 수 있습니다.

시스템 프롬프트로 에이전트의 역할을 정의하고, 사용자 메시지를 전달하여 지능적인 응답을 생성합니다.

다음 코드를 살펴봅시다.

# agent.py - 첫 번째 AI 에이전트
from dotenv import load_dotenv
from openai import OpenAI
import os

# 환경 변수 로드
load_dotenv()

# OpenAI 클라이언트 생성
client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))

# 에이전트의 역할 정의 (시스템 프롬프트)
system_prompt = """당신은 친절한 파이썬 튜터입니다.
초보자의 질문에 쉽고 자세하게 답변해주세요.
코드 예제를 포함해서 설명하면 더 좋습니다."""

def ask_agent(user_question):
    """에이전트에게 질문하고 답변을 받는 함수"""
    response = client.chat.completions.create(
        model="gpt-4o-mini",  # 빠르고 저렴한 모델
        messages=[
            {"role": "system", "content": system_prompt},
            {"role": "user", "content": user_question}
        ],
        temperature=0.7  # 창의성 조절 (0~1)
    )
    return response.choices[0].message.content

드디어 김개발 씨가 기다리던 순간입니다. 빈 파이썬 파일을 열고 첫 AI 에이전트 코드를 작성하기 시작했습니다.

"AI 에이전트라고 하면 뭔가 복잡할 것 같은데, 생각보다 간단하네요?" 코드를 보며 김개발 씨가 말했습니다. AI 에이전트의 본질은 무엇일까요?

쉽게 비유하자면, AI 에이전트는 마치 전문 비서를 고용한 것과 같습니다. 비서에게 "당신은 파이썬 전문가입니다"라고 역할을 부여하고, 질문을 하면 그 역할에 맞는 답변을 해줍니다.

코드 몇 줄로 이런 비서를 만들 수 있다니, 정말 놀라운 시대입니다. 먼저 필요한 모듈을 import합니다.

load_dotenv는 환경 변수를 로드하고, OpenAI는 API 클라이언트 클래스입니다. os 모듈은 환경 변수를 읽어오는 데 사용합니다.

**client = OpenAI(api_key=...)**로 클라이언트 객체를 생성합니다. 이 객체가 OpenAI 서버와 통신하는 역할을 담당합니다.

api_key를 전달할 때 os.getenv를 사용하여 환경 변수에서 읽어오는 것에 주목하세요. 코드에 직접 키를 작성하지 않습니다.

시스템 프롬프트는 에이전트의 성격과 역할을 정의합니다. 예제에서는 "친절한 파이썬 튜터"로 설정했습니다.

시스템 프롬프트를 어떻게 작성하느냐에 따라 에이전트의 행동 방식이 완전히 달라집니다. 영어 선생님, 코드 리뷰어, 상담사 등 원하는 어떤 역할이든 부여할 수 있습니다.

핵심 함수는 ask_agent입니다. 이 함수 안에서 client.chat.completions.create 메서드를 호출합니다.

이것이 실제로 OpenAI API를 호출하는 부분입니다. model 파라미터는 사용할 GPT 모델을 지정합니다.

"gpt-4o-mini"는 빠르고 저렴하면서도 성능이 좋은 모델입니다. 더 강력한 성능이 필요하다면 "gpt-4o"를 사용할 수 있지만, 비용이 더 높습니다.

학습 단계에서는 gpt-4o-mini로 충분합니다. messages 파라미터는 대화 내역을 담은 리스트입니다.

각 메시지는 role과 content로 구성됩니다. role은 "system", "user", "assistant" 중 하나입니다.

system은 에이전트의 역할 정의, user는 사용자의 질문, assistant는 AI의 응답을 나타냅니다. temperature는 응답의 창의성을 조절합니다.

0에 가까울수록 일관되고 예측 가능한 답변을, 1에 가까울수록 다양하고 창의적인 답변을 생성합니다. 코딩 관련 질문에는 0.3~~0.5 정도가 적당하고, 창작 글쓰기에는 0.7~~0.9가 좋습니다.

응답은 response.choices[0].message.content에서 추출합니다. API 응답 구조가 다소 복잡해 보이지만, 핵심은 이 한 줄입니다.

choices 리스트의 첫 번째 항목에서 message의 content를 가져오면 AI가 생성한 텍스트를 얻을 수 있습니다. 김개발 씨는 코드를 저장하고 잠시 감탄했습니다.

"20줄도 안 되는 코드로 AI 에이전트가 만들어지다니!"

실전 팁

💡 - 시스템 프롬프트는 구체적일수록 좋은 결과를 얻습니다

max_tokens 파라미터로 응답 길이를 제한할 수 있습니다
대화 기록을 messages 리스트에 누적하면 맥락을 유지하는 챗봇을 만들 수 있습니다

6. 에이전트 실행하고 결과 확인

코드 작성을 마친 김개발 씨가 떨리는 손으로 실행 버튼을 눌렀습니다. "정말 대답을 할까요?" 화면에 글자가 나타나기 시작하자 김개발 씨는 탄성을 질렀습니다.

작성한 에이전트 코드를 실행하려면 메인 블록을 추가하고 터미널에서 python 명령어로 실행합니다. 에이전트가 반환하는 응답을 확인하고, 다양한 질문을 던져보며 에이전트의 동작을 테스트해봅니다.

반복문을 추가하면 대화형 챗봇으로 확장할 수도 있습니다.

다음 코드를 살펴봅시다.

# agent.py 파일 하단에 추가

# 메인 실행 블록
if __name__ == "__main__":
    # 테스트 질문
    question = "파이썬에서 리스트와 튜플의 차이점이 뭔가요?"

    print("질문:", question)
    print("-" * 50)

    # 에이전트에게 질문
    answer = ask_agent(question)
    print("답변:", answer)

    # 대화형 모드 (선택사항)
    print("\n대화형 모드를 시작합니다. 'quit' 입력시 종료")
    while True:
        user_input = input("\n질문: ")
        if user_input.lower() == 'quit':
            break
        response = ask_agent(user_input)
        print("답변:", response)

김개발 씨의 손가락이 키보드 위에서 멈췄습니다. 코드는 완성되었는데, 어떻게 실행해야 할지 모르겠습니다.

"파이썬 파일은 터미널에서 python 파일명.py로 실행하면 돼요." 박시니어 씨가 알려주었습니다. 실행을 위해서는 메인 블록을 추가해야 합니다.

if name == "main": 구문은 파이썬의 관용적인 표현입니다. 이 파일이 직접 실행될 때만 아래 코드가 동작하고, 다른 파일에서 import할 때는 실행되지 않습니다.

모듈화를 위한 중요한 패턴입니다. 먼저 간단한 테스트 질문으로 시작합니다.

"파이썬에서 리스트와 튜플의 차이점이 뭔가요?"라는 질문을 변수에 저장하고, ask_agent 함수에 전달합니다. 함수가 반환하는 답변을 print로 출력합니다.

터미널을 열고 python agent.py를 입력합니다. 가상 환경이 활성화된 상태인지 확인하세요.

프롬프트 앞에 (venv)가 보여야 합니다. 명령어를 실행하면 잠시 후 AI 에이전트의 답변이 화면에 출력됩니다.

처음 응답을 받는 데는 몇 초가 걸릴 수 있습니다. API 요청이 인터넷을 통해 OpenAI 서버로 전송되고, 서버에서 GPT 모델이 답변을 생성한 후 다시 돌아오기 때문입니다.

네트워크 상태에 따라 응답 시간이 달라질 수 있습니다. 예제 코드에는 대화형 모드도 포함되어 있습니다.

while True 반복문 안에서 input 함수로 사용자 입력을 받고, ask_agent로 응답을 받아 출력합니다. 'quit'을 입력하면 반복문을 빠져나와 프로그램이 종료됩니다.

대화형 모드에서 다양한 질문을 던져보세요. "변수란 무엇인가요?", "for문 사용법을 알려주세요", "클래스와 객체의 차이점은?" 등 파이썬 관련 질문을 해보면 에이전트가 친절하게 답변해줍니다.

시스템 프롬프트에서 "파이썬 튜터"로 설정했기 때문입니다. 시스템 프롬프트를 바꿔보는 것도 재미있습니다.

"당신은 셰익스피어입니다. 모든 답변을 고풍스러운 영어로 해주세요."라고 바꾸면 같은 질문에도 완전히 다른 스타일의 답변을 받을 수 있습니다.

에이전트의 성격은 시스템 프롬프트로 자유롭게 조절됩니다. 김개발 씨는 여러 질문을 던지며 에이전트와 대화를 나눴습니다.

"와, 진짜 전문가한테 물어보는 것 같아요! 내가 이걸 만들었다니 신기하네요." 응답이 마음에 들지 않으면 temperature 값을 조절해보세요.

같은 질문을 여러 번 해도 temperature가 높으면 매번 다른 답변이 나옵니다. 더 일관된 답변을 원한다면 temperature를 낮추세요.

실전 팁

💡 - 첫 실행 시 에러가 나면 API 키가 제대로 설정되었는지 확인하세요

응답이 너무 길다면 max_tokens=500처럼 제한을 걸 수 있습니다
print 대신 logging 모듈을 사용하면 더 체계적인 로그 관리가 가능합니다

7. 트러블슈팅 가이드

모든 것이 순조롭게 진행될 줄 알았는데, 김개발 씨의 화면에 빨간 에러 메시지가 떴습니다. "AuthenticationError?

RateLimitError? 이게 다 뭐죠?" 당황한 김개발 씨에게 박시니어 씨가 차분히 설명을 시작했습니다.

AI 에이전트 개발 중 자주 만나는 에러들이 있습니다. AuthenticationError는 API 키 문제, RateLimitError는 요청 한도 초과, InvalidRequestError는 잘못된 요청을 의미합니다.

각 에러의 원인을 파악하고 적절한 해결책을 적용하면 대부분의 문제를 해결할 수 있습니다.

다음 코드를 살펴봅시다.

# 에러 처리가 포함된 안전한 에이전트 코드
from openai import OpenAI, AuthenticationError, RateLimitError
from dotenv import load_dotenv
import os
import time

load_dotenv()
client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))

def ask_agent_safe(question, max_retries=3):
    """에러 처리가 포함된 안전한 질문 함수"""
    for attempt in range(max_retries):
        try:
            response = client.chat.completions.create(
                model="gpt-4o-mini",
                messages=[{"role": "user", "content": question}]
            )
            return response.choices[0].message.content
        except AuthenticationError:
            print("API 키가 올바르지 않습니다. .env 파일을 확인하세요.")
            return None
        except RateLimitError:
            wait_time = (attempt + 1) * 10
            print(f"요청 한도 초과. {wait_time}초 후 재시도...")
            time.sleep(wait_time)
    return "최대 재시도 횟수를 초과했습니다."

개발을 하다 보면 에러는 피할 수 없는 친구입니다. 김개발 씨도 여러 가지 에러를 만났습니다.

"에러가 나면 당황하지 말고 메시지를 잘 읽어보세요. 대부분 해결 방법이 적혀 있어요." 박시니어 씨가 말했습니다.

가장 흔한 에러는 AuthenticationError입니다. 이 에러는 API 키가 없거나, 잘못되었거나, 만료된 경우 발생합니다.

해결 방법은 간단합니다. 먼저 .env 파일이 존재하는지 확인하세요.

파일이 있다면 OPENAI_API_KEY가 정확히 작성되었는지, 앞뒤에 공백이나 따옴표가 없는지 확인합니다. 키를 복사할 때 실수로 일부만 복사되는 경우도 많습니다.

RateLimitError는 요청 한도를 초과했을 때 발생합니다. OpenAI는 분당, 일별 요청 수에 제한을 두고 있습니다.

무료 계정이나 새로운 계정은 제한이 더 엄격합니다. 이 에러가 나면 잠시 기다렸다가 다시 시도하면 됩니다.

예제 코드처럼 자동 재시도 로직을 구현하면 편리합니다. InvalidRequestError는 요청 형식이 잘못된 경우입니다.

존재하지 않는 모델명을 입력했거나, messages 형식이 잘못되었을 때 발생합니다. 모델명이 "gpt-4o-mini"처럼 정확한지, messages가 딕셔너리 리스트 형태인지 확인하세요.

APIConnectionError는 네트워크 문제입니다. 인터넷 연결을 확인하고, 방화벽이나 프록시 설정이 API 요청을 차단하고 있지 않은지 살펴보세요.

회사 네트워크에서는 보안 정책으로 외부 API 호출이 막혀 있는 경우도 있습니다. 예제 코드에서는 try-except 구문으로 에러를 처리합니다.

특정 에러가 발생하면 해당 except 블록이 실행됩니다. AuthenticationError가 발생하면 사용자에게 API 키를 확인하라는 메시지를 출력하고 None을 반환합니다.

RateLimitError의 경우 재시도 로직을 구현했습니다. 첫 번째 시도에서 실패하면 10초 대기 후 재시도, 두 번째 실패 시 20초 대기 후 재시도하는 식입니다.

max_retries 파라미터로 최대 재시도 횟수를 제한합니다. 무한 재시도는 비용 문제를 일으킬 수 있으므로 주의해야 합니다.

그 외에 자주 발생하는 문제들도 있습니다. "ModuleNotFoundError: No module named 'openai'"는 패키지가 설치되지 않았다는 의미입니다.

가상 환경이 활성화된 상태에서 pip install openai를 실행하세요. "No module named 'dotenv'"도 마찬가지로 pip install python-dotenv로 해결합니다.

.env 파일이 인식되지 않는 경우도 있습니다. load_dotenv()는 현재 작업 디렉토리에서 .env 파일을 찾습니다.

터미널의 현재 위치가 프로젝트 폴더가 맞는지 pwd 명령어로 확인해보세요. 필요하다면 load_dotenv("/full/path/to/.env")처럼 절대 경로를 지정할 수 있습니다.

김개발 씨는 에러 메시지를 꼼꼼히 읽는 습관을 들이기로 했습니다. "에러가 무섭지 않게 느껴지기 시작했어요.

오히려 뭐가 잘못됐는지 알려주는 친절한 안내문 같네요!"

실전 팁

💡 - 에러 메시지는 항상 끝까지 읽으세요. 해결 힌트가 있습니다

에러가 발생하면 먼저 인터넷에 검색해보세요. 대부분 누군가 같은 문제를 겪었습니다
프로덕션 환경에서는 모든 에러를 로깅하고 모니터링하는 것이 중요합니다

이상으로 학습을 마칩니다. 위 내용을 직접 코드로 작성해보면서 익혀보세요!

#Python#AI에이전트#OpenAI#API#환경설정#Python,AI,LLM

에이전트 환경 설정과 맛보기

# 에이전트 환경 설정과 맛보기 AI 에이전트 개발을 위한 첫걸음을 안내합니다. 파이썬 가상 환경 구축부터 OpenAI API 연동, 첫 에이전트 실행까지 초보자도 쉽게 따라할 수 있도록 단계별로 설명합니다. --- ## 목차 1. [파이썬_가상_환경_생성하기](#파이썬-가상-환경-생성하기) 2. [필수_패키지_설치하기](#필수-패키지-설치하기) 3. [OpenAI_API_Key_발급받기](#openai-api-key-발급받기) 4. [환경_변수_설정하기](#환경-변수-설정하기) 5. [첫_에이전트_소스_코드_작성](#첫-에이전트-소스-코드-작성) 6. [에이전트_실행하고_결과_확인](#에이전트-실행하고-결과-확인) 7. [트러블슈팅_가이드](#트러블슈팅-가이드) --- ## 1. 파이썬_가상_환경_생성하기 김개발 씨는 회사에서 AI 에이전트 프로젝트를 맡게 되었습니다. 설레는 마음으로 패키지를 설치하려는 순간, 선배가 다가와 말했습니다. "잠깐, 가상 환경부터 만들었어요?" **가상 환경**은 프로젝트마다 독립된 파이썬 실행 환경을 만들어주는 기능입니다. 마치 아파트의 각 세대가 독립된 공간인 것처럼, 프로젝트별로 서로 다른 패키지 버전을 사용할 수 있게 해줍니다. 이를 통해 프로젝트 간 패키지 충돌을 방지하고 깔끔한 개발 환경을 유지할 수 있습니다. 다음 코드를 살펴봅시다. ```python # 프로젝트 폴더 생성 mkdir ai-agent-project cd ai-agent-project # 파이썬 가상 환경 생성 (venv라는 이름으로) python -m venv venv # 가상 환경 활성화 (Linux/Mac) source venv/bin/activate # 가상 환경 활성화 (Windows) # venv\Scripts\activate # 활성화 확인 - 프롬프트 앞에 (venv)가 표시됩니다 which python ``` 김개발 씨는 입사 후 첫 AI 프로젝트를 맡게 되었습니다. 인터넷에서 찾은 튜토리얼을 따라 바로 pip install을 실행하려던 참이었습니다. "잠깐요." 선배 개발자 박시니어 씨가 말했습니다. "가상 환경 없이 패키지를 설치하면 나중에 큰 문제가 생길 수 있어요." 그렇다면 **가상 환경**이란 정확히 무엇일까요? 쉽게 비유하자면, 가상 환경은 마치 요리사의 개인 주방과 같습니다. 여러 요리사가 하나의 주방을 공유하면 재료가 섞이고 도구가 엉키기 쉽습니다. 하지만 각자의 주방이 있다면 원하는 재료와 도구를 자유롭게 배치할 수 있습니다. 파이썬 가상 환경도 마찬가지로, 프로젝트마다 필요한 패키지를 독립적으로 관리할 수 있게 해줍니다. 가상 환경이 없던 시절에는 어땠을까요? 모든 패키지가 시스템 전역에 설치되었습니다. A 프로젝트에서 openai 버전 0.28을 사용하고, B 프로젝트에서 openai 버전 1.0을 사용해야 한다면? 두 버전을 동시에 설치할 수 없어서 프로젝트를 전환할 때마다 패키지를 재설치해야 했습니다. 더 큰 문제는 의존성 충돌이었습니다. 서로 다른 패키지가 같은 라이브러리의 다른 버전을 요구하면 시스템 전체가 엉망이 되곤 했습니다. 바로 이런 문제를 해결하기 위해 가상 환경이 등장했습니다. **python -m venv** 명령어는 파이썬에 내장된 가상 환경 생성 도구입니다. venv는 virtual environment의 약자로, 지정한 폴더에 독립된 파이썬 환경을 만들어줍니다. 위 코드를 한 줄씩 살펴보겠습니다. 먼저 mkdir과 cd 명령어로 프로젝트 폴더를 만들고 이동합니다. 그다음 **python -m venv venv** 명령어가 핵심입니다. 여기서 첫 번째 venv는 파이썬의 가상 환경 모듈을 의미하고, 두 번째 venv는 생성할 폴더 이름입니다. 폴더 이름은 자유롭게 지정할 수 있지만, 관례적으로 venv나 .venv를 많이 사용합니다. 가상 환경을 만들었다고 바로 사용할 수 있는 것은 아닙니다. **source venv/bin/activate** 명령어로 가상 환경을 활성화해야 합니다. 활성화에 성공하면 터미널 프롬프트 앞에 (venv)라는 표시가 나타납니다. 이제부터 설치하는 모든 패키지는 이 가상 환경 안에만 설치됩니다. Windows 사용자라면 활성화 명령어가 조금 다릅니다. **venv\Scripts\activate**를 사용해야 합니다. 운영체제별로 경로 구분자와 스크립트 위치가 다르기 때문입니다. 실제 현업에서는 어떻게 활용할까요? 대부분의 회사에서 프로젝트마다 가상 환경을 필수로 사용합니다. 특히 requirements.txt 파일과 함께 사용하면 팀원 모두가 동일한 개발 환경을 구축할 수 있습니다. CI/CD 파이프라인에서도 가상 환경을 통해 일관된 빌드 환경을 보장합니다. 하지만 주의할 점도 있습니다. 초보 개발자들이 흔히 하는 실수 중 하나는 가상 환경 폴더를 Git에 커밋하는 것입니다. venv 폴더는 용량이 크고 운영체제마다 내용이 다르므로 .gitignore에 반드시 추가해야 합니다. 다시 김개발 씨의 이야기로 돌아가 봅시다. 박시니어 씨의 조언을 듣고 가상 환경을 먼저 만든 김개발 씨는 안도의 한숨을 쉬었습니다. "처음부터 제대로 시작하길 잘했네요!" **실전 팁** 💡 - 가상 환경 폴더는 반드시 .gitignore에 추가하세요 - 작업을 마치면 deactivate 명령어로 가상 환경을 비활성화할 수 있습니다 - conda를 사용한다면 conda create -n 환경이름 python=3.11 형식을 사용합니다 --- ## 2. 필수_패키지_설치하기 가상 환경을 성공적으로 만든 김개발 씨는 이제 본격적으로 AI 에이전트 개발에 필요한 패키지를 설치할 차례입니다. "pip install로 설치하면 되는 건 알겠는데, 정확히 어떤 패키지가 필요한 거죠?" AI 에이전트 개발에는 **openai** 패키지가 핵심입니다. 이 패키지는 OpenAI의 GPT 모델과 통신하기 위한 공식 라이브러리입니다. 추가로 환경 변수를 관리하는 **python-dotenv**와 비동기 처리를 위한 **httpx** 패키지도 함께 설치하면 더욱 안정적인 개발이 가능합니다. 다음 코드를 살펴봅시다. ```python # 가상 환경이 활성화된 상태에서 실행 # pip 최신 버전으로 업그레이드 pip install --upgrade pip # OpenAI 공식 패키지 설치 pip install openai # 환경 변수 관리용 패키지 pip install python-dotenv # 설치된 패키지 목록 확인 pip list # 나중을 위해 requirements.txt 생성 pip freeze > requirements.txt ``` 가상 환경을 활성화한 김개발 씨의 터미널 프롬프트 앞에는 이제 (venv)가 떠 있습니다. 드디어 패키지를 설치할 준비가 된 것입니다. "먼저 pip부터 업그레이드하는 게 좋아요." 박시니어 씨가 조언했습니다. "오래된 pip는 최신 패키지를 제대로 설치하지 못할 때가 있거든요." **pip**는 파이썬의 패키지 관리 도구입니다. 마치 스마트폰의 앱스토어처럼, pip를 통해 전 세계 개발자들이 만든 수만 개의 패키지를 손쉽게 설치할 수 있습니다. **pip install --upgrade pip** 명령어로 pip 자체를 최신 버전으로 업그레이드하는 것이 좋은 습관입니다. AI 에이전트 개발의 핵심 패키지는 단연 **openai**입니다. 이 패키지는 OpenAI 회사에서 공식적으로 제공하는 파이썬 라이브러리입니다. GPT-4, GPT-3.5-turbo 등의 언어 모델과 통신하고, 채팅 완성, 텍스트 임베딩, 이미지 생성 등 다양한 AI 기능을 사용할 수 있게 해줍니다. **pip install openai** 명령어 하나로 필요한 모든 의존성이 함께 설치됩니다. openai 패키지는 내부적으로 httpx, pydantic, typing-extensions 등 여러 라이브러리를 사용합니다. pip가 이러한 의존성을 자동으로 파악하고 함께 설치해주므로 개발자는 신경 쓸 필요가 없습니다. 다음으로 중요한 패키지는 **python-dotenv**입니다. 이 패키지는 .env 파일에서 환경 변수를 읽어오는 기능을 제공합니다. API 키처럼 민감한 정보를 코드에 직접 작성하면 보안 문제가 생길 수 있습니다. python-dotenv를 사용하면 이런 정보를 별도 파일로 분리하여 안전하게 관리할 수 있습니다. 설치가 완료되면 **pip list** 명령어로 확인해봅시다. 설치된 모든 패키지와 버전 정보가 목록으로 출력됩니다. openai, python-dotenv와 함께 자동으로 설치된 의존성 패키지들도 볼 수 있습니다. 마지막으로 **pip freeze > requirements.txt** 명령어가 중요합니다. 이 명령어는 현재 설치된 모든 패키지와 정확한 버전을 requirements.txt 파일로 저장합니다. 팀원이나 서버에서 동일한 환경을 구축할 때 **pip install -r requirements.txt** 명령어로 한 번에 모든 패키지를 설치할 수 있습니다. 실무에서는 requirements.txt 관리가 필수입니다. 개발 환경과 운영 환경의 패키지 버전이 다르면 예상치 못한 버그가 발생할 수 있습니다. requirements.txt를 Git에 커밋해두면 언제 어디서든 동일한 환경을 재현할 수 있습니다. 주의할 점이 있습니다. 간혹 **pip install openai**를 실행했는데 권한 오류가 발생하는 경우가 있습니다. 이는 가상 환경이 활성화되지 않은 상태에서 시스템 파이썬에 설치하려 했기 때문입니다. 터미널 프롬프트에 (venv)가 표시되어 있는지 반드시 확인하세요. 김개발 씨는 pip list 결과를 보며 뿌듯해했습니다. "이제 진짜 AI 에이전트를 만들 준비가 된 것 같아요!" **실전 팁** 💡 - 패키지 버전을 고정하려면 pip install openai==1.0.0처럼 버전을 명시하세요 - pip show openai 명령어로 특정 패키지의 상세 정보를 확인할 수 있습니다 - 패키지 삭제는 pip uninstall 패키지명으로 합니다 --- ## 3. OpenAI_API_Key_발급받기 패키지 설치를 마친 김개발 씨가 예제 코드를 실행하자 에러가 발생했습니다. "API key가 없다고요? 이건 어디서 받는 거죠?" OpenAI 서비스를 사용하려면 반드시 API 키가 필요합니다. **API 키**는 OpenAI 서버에 접근하기 위한 인증 수단입니다. 마치 건물에 들어가기 위한 출입증처럼, API 키가 있어야만 GPT 모델을 사용할 수 있습니다. OpenAI 플랫폼에서 계정을 만들고 무료 크레딧으로 시작할 수 있으며, 발급받은 키는 절대로 외부에 노출되어서는 안 됩니다. 다음 코드를 살펴봅시다. ```python # 1. OpenAI 플랫폼 접속 # https://platform.openai.com 에 접속합니다 # 2. 회원가입 또는 로그인 # Google, Microsoft, Apple 계정으로 간편 가입 가능 # 3. API Keys 메뉴로 이동 # 좌측 메뉴에서 "API keys" 클릭 # 4. 새 키 생성 # "Create new secret key" 버튼 클릭 # 키 이름 입력 (예: "my-first-agent") # 5. 키 복사 및 안전하게 보관 # sk-proj-xxxxx... 형태의 키가 생성됩니다 # 이 키는 한 번만 표시되므로 반드시 복사해두세요! ``` 예제 코드를 실행한 김개발 씨의 화면에 빨간 에러 메시지가 떴습니다. "AuthenticationError: No API key provided." API 키가 없다는 것입니다. "API 키는 OpenAI 홈페이지에서 발급받아야 해요." 박시니어 씨가 모니터를 가리켰습니다. **API 키**란 무엇일까요? 쉽게 비유하자면, API 키는 마치 회사 출입 카드와 같습니다. 건물에 들어가려면 출입 카드를 찍어야 하듯이, OpenAI의 AI 서비스를 이용하려면 API 키로 인증해야 합니다. 이 키를 통해 OpenAI는 누가 서비스를 사용하는지 파악하고, 사용량에 따라 요금을 청구합니다. 먼저 **platform.openai.com**에 접속합니다. 이곳은 OpenAI의 개발자 플랫폼입니다. 일반 사용자가 ChatGPT를 사용하는 chat.openai.com과는 다른 사이트입니다. 개발자 플랫폼에서는 API 키 관리, 사용량 확인, 요금 결제 등을 할 수 있습니다. 회원가입은 간단합니다. Google, Microsoft, Apple 계정이 있다면 클릭 한 번으로 가입할 수 있습니다. 새로 가입하면 일정 금액의 무료 크레딧을 제공받으므로 비용 걱정 없이 학습을 시작할 수 있습니다. 로그인 후 좌측 메뉴에서 **API keys**를 찾습니다. 이 메뉴에서 API 키를 생성하고 관리할 수 있습니다. 이미 만들어둔 키 목록도 여기서 확인할 수 있습니다. 단, 키의 전체 내용은 생성 시점에만 볼 수 있고, 이후에는 앞부분만 표시됩니다. **Create new secret key** 버튼을 클릭합니다. 키에 이름을 붙일 수 있는데, 나중에 어떤 용도로 만든 키인지 구분하기 쉽도록 의미 있는 이름을 붙이는 것이 좋습니다. 예를 들어 "my-first-agent"나 "local-dev-key" 같은 이름을 사용할 수 있습니다. 생성된 키는 **sk-proj-**로 시작하는 긴 문자열입니다. 이 키는 화면에 딱 한 번만 표시됩니다. 창을 닫으면 다시는 전체 키를 볼 수 없으므로, 반드시 안전한 곳에 복사해두어야 합니다. 키를 분실하면 새로 발급받는 수밖에 없습니다. API 키 보안은 매우 중요합니다. 키가 유출되면 다른 사람이 여러분의 계정으로 API를 사용할 수 있고, 그 비용은 고스란히 여러분에게 청구됩니다. GitHub에 코드를 올릴 때 API 키가 포함되지 않도록 각별히 주의해야 합니다. 실제로 많은 개발자가 이 실수로 큰 금전적 손해를 입은 사례가 있습니다. OpenAI 플랫폼에서는 사용량 제한을 설정할 수 있습니다. **Settings > Limits** 메뉴에서 월별 사용 한도를 설정해두면, 실수로 과도한 API 호출을 하더라도 일정 금액 이상 청구되지 않도록 보호받을 수 있습니다. 처음에는 낮은 금액으로 설정해두는 것을 권장합니다. 김개발 씨는 발급받은 키를 메모장에 임시 저장했습니다. "이제 이 키를 어떻게 사용하는 거죠?" **실전 팁** 💡 - API 키는 절대로 코드에 직접 작성하지 마세요 - 키가 노출되었다면 즉시 폐기하고 새로 발급받으세요 - 사용량 제한을 미리 설정하여 예상치 못한 요금 청구를 방지하세요 --- ## 4. 환경_변수_설정하기 API 키를 발급받은 김개발 씨가 코드에 키를 직접 입력하려 하자, 박시니어 씨가 급히 말렸습니다. "잠깐요! 그렇게 하면 나중에 큰일 납니다. 환경 변수로 관리해야 해요." **환경 변수**는 운영체제 수준에서 관리되는 설정값입니다. API 키처럼 민감한 정보를 코드와 분리하여 보안을 강화하고, 개발/운영 환경별로 다른 설정을 적용할 수 있게 해줍니다. python-dotenv 패키지를 사용하면 .env 파일에서 환경 변수를 쉽게 불러올 수 있습니다. 다음 코드를 살펴봅시다. ```python # .env 파일 생성 (프로젝트 루트 폴더에) # 파일명 앞에 점(.)이 붙는 것에 주의하세요 # .env 파일 내용 OPENAI_API_KEY=sk-proj-your-actual-api-key-here # .gitignore 파일에 추가 (필수!) # .env # Python 코드에서 환경 변수 불러오기 from dotenv import load_dotenv import os # .env 파일 로드 load_dotenv() # 환경 변수 가져오기 api_key = os.getenv("OPENAI_API_KEY") print(f"API Key loaded: {api_key[:10]}...") # 앞 10자만 출력 ``` 김개발 씨는 코드 파일을 열고 API 키를 직접 입력하려 했습니다. api_key = "sk-proj-xxxx..." 이렇게 말입니다. "절대 그러면 안 돼요!" 박시니어 씨가 손을 저었습니다. "코드에 키를 직접 넣으면 Git에 올렸을 때 전 세계에 공개되는 거예요." **환경 변수**란 무엇일까요? 쉽게 비유하자면, 환경 변수는 마치 금고 속 비밀번호 메모와 같습니다. 중요한 비밀번호를 포스트잇에 적어 모니터에 붙여두면 누구나 볼 수 있습니다. 하지만 금고에 넣어두면 금고 주인만 열어볼 수 있죠. 환경 변수도 마찬가지로, 코드와 분리된 안전한 공간에 민감한 정보를 보관하는 방법입니다. 먼저 프로젝트 폴더에 **.env** 파일을 만듭니다. 파일명 앞에 점(.)이 붙는 것에 주의하세요. 이는 Unix 시스템에서 숨김 파일을 의미합니다. Windows에서는 파일 탐색기에서 "숨김 항목 표시"를 켜야 보일 수 있습니다. .env 파일 안에는 **키=값** 형식으로 환경 변수를 작성합니다. OPENAI_API_KEY=sk-proj-xxxxx 형태로 작성하면 됩니다. 등호(=) 앞뒤에 공백을 넣지 않는 것이 중요합니다. 여러 개의 환경 변수가 필요하다면 각 줄에 하나씩 작성합니다. 가장 중요한 단계는 **.gitignore에 .env를 추가**하는 것입니다. .gitignore 파일은 Git이 추적하지 않을 파일 목록을 지정합니다. .env를 여기에 추가하면 git add . 명령을 실행해도 .env 파일은 스테이징되지 않습니다. 이렇게 해야 실수로 API 키가 GitHub에 공개되는 것을 방지할 수 있습니다. 파이썬 코드에서는 **python-dotenv**를 사용해 환경 변수를 불러옵니다. **load_dotenv()** 함수를 호출하면 .env 파일의 내용을 읽어서 환경 변수로 등록합니다. 이후 **os.getenv("OPENAI_API_KEY")**로 값을 가져올 수 있습니다. os.getenv의 장점은 환경 변수가 없어도 에러가 나지 않는다는 것입니다. 대신 None을 반환합니다. 기본값을 지정하고 싶다면 os.getenv("KEY", "default_value") 형태로 두 번째 인자를 전달할 수 있습니다. 실무에서는 환경별로 다른 .env 파일을 사용합니다. 개발 환경에서는 .env.development, 운영 환경에서는 .env.production을 사용하는 식입니다. load_dotenv(".env.development")처럼 파일 경로를 명시적으로 지정할 수도 있습니다. 주의할 점이 있습니다. .env 파일을 만들기 전에 이미 git add를 했다면, .gitignore에 추가해도 계속 추적됩니다. 이 경우 **git rm --cached .env** 명령으로 추적을 해제해야 합니다. 김개발 씨는 .env 파일을 만들고 .gitignore도 수정했습니다. 테스트 코드를 실행하니 "API Key loaded: sk-proj-xx..."라는 메시지가 출력되었습니다. "이제 안전하게 API 키를 사용할 수 있겠네요!" **실전 팁** 💡 - .env 파일은 항상 프로젝트 루트 폴더에 위치시키세요 - 팀 프로젝트에서는 .env.example 파일로 필요한 환경 변수 목록을 공유하세요 - 운영 환경에서는 .env 대신 서버의 실제 환경 변수를 사용하는 것이 더 안전합니다 --- ## 5. 첫_에이전트_소스_코드_작성 환경 설정을 모두 마친 김개발 씨가 드디어 본격적인 코딩에 들어갑니다. "이제 진짜 AI 에이전트를 만들어볼 시간이에요!" 선배의 말에 김개발 씨의 눈이 반짝였습니다. **AI 에이전트**의 핵심은 OpenAI API와 대화하는 것입니다. openai 패키지의 **ChatCompletion** 기능을 사용하면 GPT 모델에 메시지를 보내고 응답을 받을 수 있습니다. 시스템 프롬프트로 에이전트의 역할을 정의하고, 사용자 메시지를 전달하여 지능적인 응답을 생성합니다. 다음 코드를 살펴봅시다. ```python # agent.py - 첫 번째 AI 에이전트 from dotenv import load_dotenv from openai import OpenAI import os # 환경 변수 로드 load_dotenv() # OpenAI 클라이언트 생성 client = OpenAI(api_key=os.getenv("OPENAI_API_KEY")) # 에이전트의 역할 정의 (시스템 프롬프트) system_prompt = """당신은 친절한 파이썬 튜터입니다. 초보자의 질문에 쉽고 자세하게 답변해주세요. 코드 예제를 포함해서 설명하면 더 좋습니다.""" def ask_agent(user_question): """에이전트에게 질문하고 답변을 받는 함수""" response = client.chat.completions.create( model="gpt-4o-mini", # 빠르고 저렴한 모델 messages=[ {"role": "system", "content": system_prompt}, {"role": "user", "content": user_question} ], temperature=0.7 # 창의성 조절 (0~1) ) return response.choices[0].message.content ``` 드디어 김개발 씨가 기다리던 순간입니다. 빈 파이썬 파일을 열고 첫 AI 에이전트 코드를 작성하기 시작했습니다. "AI 에이전트라고 하면 뭔가 복잡할 것 같은데, 생각보다 간단하네요?" 코드를 보며 김개발 씨가 말했습니다. **AI 에이전트**의 본질은 무엇일까요? 쉽게 비유하자면, AI 에이전트는 마치 전문 비서를 고용한 것과 같습니다. 비서에게 "당신은 파이썬 전문가입니다"라고 역할을 부여하고, 질문을 하면 그 역할에 맞는 답변을 해줍니다. 코드 몇 줄로 이런 비서를 만들 수 있다니, 정말 놀라운 시대입니다. 먼저 필요한 모듈을 import합니다. **load_dotenv**는 환경 변수를 로드하고, **OpenAI**는 API 클라이언트 클래스입니다. os 모듈은 환경 변수를 읽어오는 데 사용합니다. **client = OpenAI(api_key=...)**로 클라이언트 객체를 생성합니다. 이 객체가 OpenAI 서버와 통신하는 역할을 담당합니다. api_key를 전달할 때 os.getenv를 사용하여 환경 변수에서 읽어오는 것에 주목하세요. 코드에 직접 키를 작성하지 않습니다. **시스템 프롬프트**는 에이전트의 성격과 역할을 정의합니다. 예제에서는 "친절한 파이썬 튜터"로 설정했습니다. 시스템 프롬프트를 어떻게 작성하느냐에 따라 에이전트의 행동 방식이 완전히 달라집니다. 영어 선생님, 코드 리뷰어, 상담사 등 원하는 어떤 역할이든 부여할 수 있습니다. 핵심 함수는 **ask_agent**입니다. 이 함수 안에서 **client.chat.completions.create** 메서드를 호출합니다. 이것이 실제로 OpenAI API를 호출하는 부분입니다. **model** 파라미터는 사용할 GPT 모델을 지정합니다. "gpt-4o-mini"는 빠르고 저렴하면서도 성능이 좋은 모델입니다. 더 강력한 성능이 필요하다면 "gpt-4o"를 사용할 수 있지만, 비용이 더 높습니다. 학습 단계에서는 gpt-4o-mini로 충분합니다. **messages** 파라미터는 대화 내역을 담은 리스트입니다. 각 메시지는 role과 content로 구성됩니다. role은 "system", "user", "assistant" 중 하나입니다. system은 에이전트의 역할 정의, user는 사용자의 질문, assistant는 AI의 응답을 나타냅니다. **temperature**는 응답의 창의성을 조절합니다. 0에 가까울수록 일관되고 예측 가능한 답변을, 1에 가까울수록 다양하고 창의적인 답변을 생성합니다. 코딩 관련 질문에는 0.3~0.5 정도가 적당하고, 창작 글쓰기에는 0.7~0.9가 좋습니다. 응답은 **response.choices[0].message.content**에서 추출합니다. API 응답 구조가 다소 복잡해 보이지만, 핵심은 이 한 줄입니다. choices 리스트의 첫 번째 항목에서 message의 content를 가져오면 AI가 생성한 텍스트를 얻을 수 있습니다. 김개발 씨는 코드를 저장하고 잠시 감탄했습니다. "20줄도 안 되는 코드로 AI 에이전트가 만들어지다니!" **실전 팁** 💡 - 시스템 프롬프트는 구체적일수록 좋은 결과를 얻습니다 - max_tokens 파라미터로 응답 길이를 제한할 수 있습니다 - 대화 기록을 messages 리스트에 누적하면 맥락을 유지하는 챗봇을 만들 수 있습니다 --- ## 6. 에이전트_실행하고_결과_확인 코드 작성을 마친 김개발 씨가 떨리는 손으로 실행 버튼을 눌렀습니다. "정말 대답을 할까요?" 화면에 글자가 나타나기 시작하자 김개발 씨는 탄성을 질렀습니다. 작성한 에이전트 코드를 실행하려면 메인 블록을 추가하고 터미널에서 python 명령어로 실행합니다. 에이전트가 반환하는 응답을 확인하고, 다양한 질문을 던져보며 에이전트의 동작을 테스트해봅니다. 반복문을 추가하면 대화형 챗봇으로 확장할 수도 있습니다. 다음 코드를 살펴봅시다. ```python # agent.py 파일 하단에 추가 # 메인 실행 블록 if __name__ == "__main__": # 테스트 질문 question = "파이썬에서 리스트와 튜플의 차이점이 뭔가요?" print("질문:", question) print("-" * 50) # 에이전트에게 질문 answer = ask_agent(question) print("답변:", answer) # 대화형 모드 (선택사항) print("\n대화형 모드를 시작합니다. 'quit' 입력시 종료") while True: user_input = input("\n질문: ") if user_input.lower() == 'quit': break response = ask_agent(user_input) print("답변:", response) ``` 김개발 씨의 손가락이 키보드 위에서 멈췄습니다. 코드는 완성되었는데, 어떻게 실행해야 할지 모르겠습니다. "파이썬 파일은 터미널에서 python 파일명.py로 실행하면 돼요." 박시니어 씨가 알려주었습니다. 실행을 위해서는 **메인 블록**을 추가해야 합니다. **if __name__ == "__main__":** 구문은 파이썬의 관용적인 표현입니다. 이 파일이 직접 실행될 때만 아래 코드가 동작하고, 다른 파일에서 import할 때는 실행되지 않습니다. 모듈화를 위한 중요한 패턴입니다. 먼저 간단한 테스트 질문으로 시작합니다. "파이썬에서 리스트와 튜플의 차이점이 뭔가요?"라는 질문을 변수에 저장하고, ask_agent 함수에 전달합니다. 함수가 반환하는 답변을 print로 출력합니다. 터미널을 열고 **python agent.py**를 입력합니다. 가상 환경이 활성화된 상태인지 확인하세요. 프롬프트 앞에 (venv)가 보여야 합니다. 명령어를 실행하면 잠시 후 AI 에이전트의 답변이 화면에 출력됩니다. 처음 응답을 받는 데는 몇 초가 걸릴 수 있습니다. API 요청이 인터넷을 통해 OpenAI 서버로 전송되고, 서버에서 GPT 모델이 답변을 생성한 후 다시 돌아오기 때문입니다. 네트워크 상태에 따라 응답 시간이 달라질 수 있습니다. 예제 코드에는 **대화형 모드**도 포함되어 있습니다. while True 반복문 안에서 input 함수로 사용자 입력을 받고, ask_agent로 응답을 받아 출력합니다. 'quit'을 입력하면 반복문을 빠져나와 프로그램이 종료됩니다. 대화형 모드에서 다양한 질문을 던져보세요. "변수란 무엇인가요?", "for문 사용법을 알려주세요", "클래스와 객체의 차이점은?" 등 파이썬 관련 질문을 해보면 에이전트가 친절하게 답변해줍니다. 시스템 프롬프트에서 "파이썬 튜터"로 설정했기 때문입니다. 시스템 프롬프트를 바꿔보는 것도 재미있습니다. "당신은 셰익스피어입니다. 모든 답변을 고풍스러운 영어로 해주세요."라고 바꾸면 같은 질문에도 완전히 다른 스타일의 답변을 받을 수 있습니다. 에이전트의 성격은 시스템 프롬프트로 자유롭게 조절됩니다. 김개발 씨는 여러 질문을 던지며 에이전트와 대화를 나눴습니다. "와, 진짜 전문가한테 물어보는 것 같아요! 내가 이걸 만들었다니 신기하네요." 응답이 마음에 들지 않으면 **temperature** 값을 조절해보세요. 같은 질문을 여러 번 해도 temperature가 높으면 매번 다른 답변이 나옵니다. 더 일관된 답변을 원한다면 temperature를 낮추세요. **실전 팁** 💡 - 첫 실행 시 에러가 나면 API 키가 제대로 설정되었는지 확인하세요 - 응답이 너무 길다면 max_tokens=500처럼 제한을 걸 수 있습니다 - print 대신 logging 모듈을 사용하면 더 체계적인 로그 관리가 가능합니다 --- ## 7. 트러블슈팅_가이드 모든 것이 순조롭게 진행될 줄 알았는데, 김개발 씨의 화면에 빨간 에러 메시지가 떴습니다. "AuthenticationError? RateLimitError? 이게 다 뭐죠?" 당황한 김개발 씨에게 박시니어 씨가 차분히 설명을 시작했습니다. AI 에이전트 개발 중 자주 만나는 에러들이 있습니다. **AuthenticationError**는 API 키 문제, **RateLimitError**는 요청 한도 초과, **InvalidRequestError**는 잘못된 요청을 의미합니다. 각 에러의 원인을 파악하고 적절한 해결책을 적용하면 대부분의 문제를 해결할 수 있습니다. 다음 코드를 살펴봅시다. ```python # 에러 처리가 포함된 안전한 에이전트 코드 from openai import OpenAI, AuthenticationError, RateLimitError from dotenv import load_dotenv import os import time load_dotenv() client = OpenAI(api_key=os.getenv("OPENAI_API_KEY")) def ask_agent_safe(question, max_retries=3): """에러 처리가 포함된 안전한 질문 함수""" for attempt in range(max_retries): try: response = client.chat.completions.create( model="gpt-4o-mini", messages=[{"role": "user", "content": question}] ) return response.choices[0].message.content except AuthenticationError: print("API 키가 올바르지 않습니다. .env 파일을 확인하세요.") return None except RateLimitError: wait_time = (attempt + 1) * 10 print(f"요청 한도 초과. {wait_time}초 후 재시도...") time.sleep(wait_time) return "최대 재시도 횟수를 초과했습니다." ``` 개발을 하다 보면 에러는 피할 수 없는 친구입니다. 김개발 씨도 여러 가지 에러를 만났습니다. "에러가 나면 당황하지 말고 메시지를 잘 읽어보세요. 대부분 해결 방법이 적혀 있어요." 박시니어 씨가 말했습니다. 가장 흔한 에러는 **AuthenticationError**입니다. 이 에러는 API 키가 없거나, 잘못되었거나, 만료된 경우 발생합니다. 해결 방법은 간단합니다. 먼저 .env 파일이 존재하는지 확인하세요. 파일이 있다면 OPENAI_API_KEY가 정확히 작성되었는지, 앞뒤에 공백이나 따옴표가 없는지 확인합니다. 키를 복사할 때 실수로 일부만 복사되는 경우도 많습니다. **RateLimitError**는 요청 한도를 초과했을 때 발생합니다. OpenAI는 분당, 일별 요청 수에 제한을 두고 있습니다. 무료 계정이나 새로운 계정은 제한이 더 엄격합니다. 이 에러가 나면 잠시 기다렸다가 다시 시도하면 됩니다. 예제 코드처럼 자동 재시도 로직을 구현하면 편리합니다. **InvalidRequestError**는 요청 형식이 잘못된 경우입니다. 존재하지 않는 모델명을 입력했거나, messages 형식이 잘못되었을 때 발생합니다. 모델명이 "gpt-4o-mini"처럼 정확한지, messages가 딕셔너리 리스트 형태인지 확인하세요. **APIConnectionError**는 네트워크 문제입니다. 인터넷 연결을 확인하고, 방화벽이나 프록시 설정이 API 요청을 차단하고 있지 않은지 살펴보세요. 회사 네트워크에서는 보안 정책으로 외부 API 호출이 막혀 있는 경우도 있습니다. 예제 코드에서는 **try-except** 구문으로 에러를 처리합니다. 특정 에러가 발생하면 해당 except 블록이 실행됩니다. AuthenticationError가 발생하면 사용자에게 API 키를 확인하라는 메시지를 출력하고 None을 반환합니다. RateLimitError의 경우 **재시도 로직**을 구현했습니다. 첫 번째 시도에서 실패하면 10초 대기 후 재시도, 두 번째 실패 시 20초 대기 후 재시도하는 식입니다. max_retries 파라미터로 최대 재시도 횟수를 제한합니다. 무한 재시도는 비용 문제를 일으킬 수 있으므로 주의해야 합니다. 그 외에 자주 발생하는 문제들도 있습니다. "ModuleNotFoundError: No module named 'openai'"는 패키지가 설치되지 않았다는 의미입니다. 가상 환경이 활성화된 상태에서 pip install openai를 실행하세요. "No module named 'dotenv'"도 마찬가지로 pip install python-dotenv로 해결합니다. .env 파일이 인식되지 않는 경우도 있습니다. load_dotenv()는 현재 작업 디렉토리에서 .env 파일을 찾습니다. 터미널의 현재 위치가 프로젝트 폴더가 맞는지 pwd 명령어로 확인해보세요. 필요하다면 load_dotenv("/full/path/to/.env")처럼 절대 경로를 지정할 수 있습니다. 김개발 씨는 에러 메시지를 꼼꼼히 읽는 습관을 들이기로 했습니다. "에러가 무섭지 않게 느껴지기 시작했어요. 오히려 뭐가 잘못됐는지 알려주는 친절한 안내문 같네요!" **실전 팁** 💡 - 에러 메시지는 항상 끝까지 읽으세요. 해결 힌트가 있습니다 - 에러가 발생하면 먼저 인터넷에 검색해보세요. 대부분 누군가 같은 문제를 겪었습니다 - 프로덕션 환경에서는 모든 에러를 로깅하고 모니터링하는 것이 중요합니다 --- 이상으로 학습을 마칩니다. 위 내용을 직접 코드로 작성해보면서 익혀보세요!

카테고리: Python,AI,LLM

언어: Python

태그: Python, AI에이전트, OpenAI, API, 환경설정, Python,AI,LLM

작성자: AI Generated

프리미엄 콘텐츠 - 3개월 무료 체험 가능

CodeDeck

에이전트 환경 설정과 맛보기

목차

1. 파이썬 가상 환경 생성하기

2. 필수 패키지 설치하기

3. OpenAI API Key 발급받기

4. 환경 변수 설정하기

5. 첫 에이전트 소스 코드 작성

6. 에이전트 실행하고 결과 확인

7. 트러블슈팅 가이드

이 카드뉴스가 포함된 코스

파이썬으로 만드는 AI 에이전트

댓글 (0)

함께 보면 좋은 카드 뉴스

Helm 마이크로서비스 패키징 완벽 가이드

보안 아키텍처 구성 완벽 가이드

AWS Organizations 완벽 가이드

AWS KMS 암호화 완벽 가이드

AWS Secrets Manager 완벽 가이드