02. 개발 환경 준비와 API 키 관리

비유로 시작하기: 프로젝트마다 다른 작업대

여러 요리를 동시에 한다고 해 봅시다. 모든 재료를 한 도마에 쌓아두면, 디저트용 설탕과 메인용 소금이 섞여 사고가 납니다. 가상환경(virtual environment)은 프로젝트마다 깨끗한 도마를 따로 주는 것과 같습니다. A 프로젝트는 langgraph==1.2를, B 프로젝트는 구버전을 써야 할 때, 환경을 격리하면 서로 간섭하지 않습니다.

에이전트 강좌는 OpenAI Agents SDK, AutoGen, LangGraph, CrewAI 등 의존성이 제각각인 도구를 다룹니다. 환경을 섞으면 버전 충돌로 시간을 허비하기 쉽습니다. 그래서 부(部)마다 또는 도구마다 가상환경을 분리하는 것을 권합니다.

Python 버전 정하기

2026년 현재 대부분의 에이전트 프레임워크는 Python 3.10 이상을 요구합니다. 안전한 선택은 3.11 또는 3.12입니다.

💡 팁: 3.13/3.14는 가장 최신이지만, 일부 생태계 라이브러리가 아직 따라오지 못한 경우가 있습니다. 학습 목적이라면 3.11이나 3.12가 가장 무난합니다.

가상환경 만들기

강의는 Anaconda를 안내하지만, 결과는 어떤 방식이든 같습니다. 셋 중 익숙한 것을 고르세요.

세 도구를 한 줄로 정리하면: conda는 Anaconda(데이터·AI용 파이썬 배포판)에 딸려 오는 환경·패키지 관리 도구이고, venv는 파이썬에 기본 내장된 가상환경 생성 기능(따로 설치할 필요 없음)이며, uv는 최근 등장한 매우 빠른 패키지 설치·환경 관리 도구입니다. 셋 다 "프로젝트별 독립 작업대"를 만든다는 목적은 같습니다.

방법 A — conda (강의 기본)

# 새 환경 생성 (Python 3.12)
conda create -n agentic python=3.12 -y

# 활성화
conda activate agentic

# 비활성화
conda deactivate

방법 B — venv (표준 라이브러리, 추가 설치 불필요)

# 환경 생성
python3.12 -m venv .venv

# 활성화 (macOS/Linux)
source .venv/bin/activate

# 활성화 (Windows PowerShell)
.venv\Scripts\Activate.ps1

방법 C — uv (빠른 차세대 패키지 매니저, CrewAI 권장)

# uv 설치 (한 번만)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 프로젝트 초기화 + 가상환경
uv venv --python 3.12
source .venv/bin/activate

⚠️ 흔한 실수: 가상환경을 활성화하지 않은 채 pip install을 실행하는 것. 그러면 패키지가 전역에 깔려 다른 프로젝트와 충돌합니다. 터미널 프롬프트 앞에 (agentic) 같은 환경 이름이 보이는지 항상 확인하세요.

패키지 설치

각 부에서 필요한 패키지는 해당 장에서 다시 안내합니다. 여기서는 1부(OpenAI 기반 첫 에이전트)에 필요한 최소한만 설치합니다.

pip install openai python-dotenv

도구별로 추가될 패키지를 미리 맛보기로 정리하면 다음과 같습니다.

# 2~3부: OpenAI Agents SDK
pip install "openai-agents"

# 4부: AutoGen
pip install -U "autogen-agentchat" "autogen-ext[openai]"

# 5부: LangGraph
pip install langgraph langchain langchain-openai

# 6부: CrewAI
pip install crewai crewai-tools

API 키 안전하게 다루기

에이전트는 LLM API를 호출하므로 API 키가 필요합니다. 여기서 API(Application Programming Interface)는 다른 프로그램의 기능을 호출해 쓰는 약속된 창구로, LLM API는 "문장을 보내면 답을 돌려주는" 외부 서비스 창구라고 보면 됩니다. 키는 비밀번호와 같습니다. 코드에 직접 적거나 GitHub(코드를 올려 공유·관리하는 대표적 웹 서비스)에 올리면, 누군가 도용해 요금을 폭증시킬 수 있습니다.

올바른 방법은 .env 파일에 키를 두고, 코드에서 읽어 오는 것입니다.

.env 파일 (프로젝트 루트에 생성):

OPENAI_API_KEY=sk-여기에_실제_키
TAVILY_API_KEY=tvly-검색용_키
ANTHROPIC_API_KEY=sk-ant-클로드용_키
GEMINI_API_KEY=제미나이용_키

Python에서 읽어 오기:

import os
from dotenv import load_dotenv

load_dotenv()  # .env의 값을 환경변수로 로드 (환경변수 = OS가 프로그램에 건네주는 설정값. 코드 밖에 키를 두는 통로)

api_key = os.getenv("OPENAI_API_KEY")
# 이후 라이브러리들은 보통 OPENAI_API_KEY 환경변수를 자동으로 읽습니다

그리고 반드시 .gitignore에 .env를 추가하세요.

# .gitignore
.env
.venv/
__pycache__/

📌 핵심: 키는 .env에. 코드에는 절대 직접 쓰지 않는다. .env는 깃에 올리지 않는다. 이 세 가지는 모든 프로젝트의 기본기입니다.

⚠️ 흔한 실수: .env를 만들었지만 .gitignore에 넣지 않고 그대로 커밋. 한 번 푸시된 키는 이미 노출된 것으로 간주하고 즉시 폐기(rotate)해야 합니다. 폐기(rotate)란 노출된 키를 무효화하고 새 키를 발급받는 것을 말합니다. 커밋 기록을 지워도 안전하지 않습니다.

환경 설정 점검 흐름

flowchart TD
    classDef step fill:#80DEEA,stroke:#00838F,color:#000
    classDef check fill:#FFE082,stroke:#F9A825,color:#000
    classDef ok fill:#A5D6A7,stroke:#2E7D32,color:#000
    classDef bad fill:#EF9A9A,stroke:#C62828,color:#000

    A[Python 3.11/3.12 설치]:::step --> B[가상환경 생성·활성화]:::step
    B --> C{프롬프트에<br/>환경명 보이나?}:::check
    C -->|아니오| B
    C -->|예| D[패키지 설치]:::step
    D --> E[.env에 API 키 작성]:::step
    E --> F[.gitignore에 .env 추가]:::step
    F --> G{키 로드 테스트}:::check
    G -->|성공| H[준비 완료]:::ok
    G -->|None 반환| I[load_dotenv 위치·<br/>파일명 확인]:::bad
    I --> E

키 로드 테스트

설치가 끝났다면, 키가 제대로 읽히는지 한 줄로 확인합니다.

import os
from dotenv import load_dotenv

load_dotenv()
print("키 로드 OK" if os.getenv("OPENAI_API_KEY") else "키를 찾을 수 없음")

None이 나온다면 흔한 원인은 다음과 같습니다. .env 파일이 실행 디렉터리에 없거나, 파일명이 env.txt처럼 잘못되었거나, load_dotenv()를 키를 읽기 전에 호출하지 않은 경우입니다.

이 장에서 배운 것

• 도구마다 의존성이 달라 가상환경 격리가 필수다. conda·venv·uv 중 편한 것을 쓴다.
• 안전한 선택은 Python 3.11/3.12다.
• API 키는 .env에 두고 os.getenv로 읽으며, 코드에 하드코딩하지 않는다.
• .env는 반드시 .gitignore에 추가한다. 노출된 키는 즉시 폐기한다.

✍️ 확인 문제

1. 같은 컴퓨터에서 LangGraph 1.2를 쓰는 프로젝트와 구버전을 쓰는 프로젝트를 동시에 운영하려 한다. 충돌 없이 진행하려면 무엇을 해야 하는가?
2. .env에 키를 넣었는데 os.getenv("OPENAI_API_KEY")가 계속 None을 반환한다. 점검할 항목 3가지를 들어라.
3. 실수로 API 키가 든 .env를 공개 저장소에 푸시했다. 가장 먼저 해야 할 조치는 무엇인가?

이전 장: 01. 에이전틱 AI란 무엇인가
다음 장: 03. 가장 단순한 에이전트 — 이제 메모리도 도구도 없는 가장 작은 에이전트를 직접 만들어 봅니다.