1장 · 실습 환경과 첫 호출 — 절 목차01. 이 과정에서 만들 것 02. LLM이 답하지 못하는 세 가지 질문 03. 미니콘다 설치하기 04. 파이썬 3.10 가상환경 만들기 05. VS Code 설치와 프로젝트 폴더 열기 06. 인터프리터 고르기 가장 많이 막히는 지점 07. 폴더 구조와 실습 데이터 그리고 라이브러리 설치 08. API키를 env 파일에 넣기 09. 따라하기 설치 점검과 첫 LLM 호출 10. 정리 자주 나는 오류 5가지

API 키를 `.env` 파일에 넣기

한 줄 요약

직접 발급받은 Gemini API 키를 .env 라는 파일에 한 줄로 적어 둡니다. 그러면 8장 내내 모든 코드가 알아서 그 키를 씁니다. 코드에 키를 직접 쓰지 않는 이유도 여기서 짚습니다.

1. API 키란 무엇인가

API(Application Programming Interface) 는 "프로그램이 다른 프로그램의 기능을 빌려 쓰는 창구"입니다. 우리는 구글이 운영하는 Gemini 모델을 인터넷 너머에서 빌려 씁니다.

이때 구글 입장에서는 누가 얼마나 썼는지 알아야 합니다. 그 신분증이 API 키입니다.

내 코드  ──[ 질문 + API 키 ]──▶  구글 서버 (Gemini)
        ◀──[     답변      ]──

키는 AIzaSy... 로 시작하는 40자 남짓의 문자열입니다.

키는 직접 발급받습니다. https://aistudio.google.com/apikey 에 구글 계정으로 로그인한 뒤, 안내에 따라 키를 만들면 됩니다. 무료로 발급받을 수 있습니다.

2. `.env` 파일 만들기

(1) VS Code에서 새 파일 만들기

VS Code 왼쪽 탐색기에서 agentic_ai 폴더 이름 위에 마우스를 올리면 아이콘 몇 개가 나타납니다. 새 파일(New File) 아이콘을 누르고, 파일 이름을 정확히 입력합니다.

.env

점(.)으로 시작합니다. env 가 아니라 .env 입니다. 확장자는 없습니다. 그리고 반드시 code/ 안이 아니라 agentic_ai 바로 아래에 만들어야 합니다.

(2) 키 적어 넣기

만든 .env 파일에 아래 한 줄을 씁니다. 등호 뒤에 발급받은 키를 그대로 붙여 넣으세요.

GEMINI_API_KEY=AIzaSy...여기에_받은_키_전체...

저장합니다 (Ctrl+S / Cmd+S).

적을 때 흔히 하는 실수

GEMINI_API_KEY = AIzaSy...      ← ✗ 등호 양옆 공백
GEMINI_API_KEY="AIzaSy..."      ← △ 따옴표 (동작은 하지만 불필요)
GEMINI_API_KEY=AIzaSy... 여기까지 ← ✗ 뒤에 딸려 온 글자
GEMINI-API-KEY=AIzaSy...        ← ✗ 하이픈 (밑줄이어야 함)

올바른 형태는 딱 이겁니다 — 이름, 등호, 키. 공백 없음.

GEMINI_API_KEY=AIzaSy1234567890abcdefghijklmnopqrstuvwxyz

3. 모델도 바꿀 수 있습니다 (선택)

이 과정은 gemini-2.5-flash 모델을 씁니다. .env 에 아무것도 안 적으면 이 모델이 기본으로 잡힙니다.

나중에 다른 모델로 바꾸고 싶다면 .env 에 한 줄만 추가하면 됩니다. 코드는 하나도 안 고쳐도 됩니다.

GEMINI_API_KEY=AIzaSy...
GEMINI_MODEL=gemini-2.5-flash
GEMINI_EMBED_MODEL=models/gemini-embedding-001

이름	무엇을 정하나	기본값
`GEMINI_API_KEY`	신분증	(필수)
`GEMINI_MODEL`	대화·판단에 쓸 모델	`gemini-2.5-flash`
`GEMINI_EMBED_MODEL`	6장 문서검색에 쓸 임베딩 모델	`models/gemini-embedding-001`

GEMINI_EMBED_MODEL 이 뭔지 몰라도 됩니다. 1절에서 한 번 나왔던 임베딩 — 문장을 숫자 목록으로 바꿔 두는 것 — 을 해 주는 모델 이름입니다. 6장 문서검색에서 씁니다. 지금은 안 적어도 됩니다. 적어 두면 6장에서 그대로 쓰입니다.

flash 를 쓰는 이유 — Gemini에는 더 똑똑한 pro 계열도 있지만, flash 는 빠르고 저렴합니다. 실습에서는 같은 코드를 수십 번 돌리게 되므로 속도와 비용이 중요합니다. 성능도 이 과정의 예제에는 충분합니다.

4. 왜 코드에 직접 안 쓰나

이렇게 써도 동작은 합니다.

아래는 개념 설명용 코드입니다 — 실습 파일에 넣지 않습니다.

client = genai.Client(api_key="AIzaSy1234...")   # ✗ 이렇게 하지 않습니다

그런데 이러면 문제가 생깁니다.

코드를 공유하는 순간 키가 함께 새어 나갑니다. GitHub에 올리면 그대로 공개됩니다. 실제로 유출된 키를 자동으로 긁어가는 프로그램이 돌아다닙니다.
키를 바꾸려면 코드를 다 고쳐야 합니다. 8개 파일에 흩어져 있으면 8군데를 고쳐야 합니다.
사람마다 키가 다릅니다. 코드에 박아 두면 남에게 그대로 줄 수 없습니다.

.env 로 빼면 이 셋이 한 번에 해결됩니다. 코드에는 "환경에서 키를 읽어라"만 적히고, 키 자체는 코드 밖에 있습니다.

아래는 제공된 code/common.py 의 일부입니다 — 고치지 않아도 됩니다.

# code/common.py 안 — 키 자체는 어디에도 안 적혀 있다
load_dotenv(ROOT / ".env")
_key = os.getenv("GOOGLE_API_KEY") or os.getenv("GEMINI_API_KEY")

.env 는 절대 남에게 보내지 마세요. 카톡·메일·GitHub 어디에도 올리면 안 됩니다. 코드를 공유할 때는 .env.example(키 없는 양식)만 함께 보냅니다. 실습 폴더에 .env.example 이 들어 있는 이유가 그것입니다.

키 이름이 두 가지인 이유

common.py 를 보면 이름 두 개를 다 받아들입니다.

아래는 제공된 code/common.py 의 일부입니다 — 고치지 않아도 됩니다.

_key = os.getenv("GOOGLE_API_KEY") or os.getenv("GEMINI_API_KEY")

구글 SDK는 GEMINI_API_KEY 를 보고, LangChain은 GOOGLE_API_KEY 를 봅니다. 서로 다른 이름을 써 왔습니다. 여러분이 어느 쪽으로 적든 동작하도록 common.py 가 알아서 맞춰 줍니다. 그냥 GEMINI_API_KEY 로 적으세요.

.env 에는 GEMINI_API_KEY 로 적으세요. 위 한 줄이 두 이름을 다 받아들인 뒤, 프로그램 안에서는 GOOGLE_API_KEY 하나로 통일해 씁니다. 그래서 라이브러리 문서나 오류 메시지에서 GOOGLE_API_KEY 를 보더라도 여러분이 잘못 적은 게 아닙니다.

5. 확인하기

터미널에서 (agentic) 을 확인한 뒤:

터미널에서 실행 — 프로젝트 폴더 agentic_ai 에서, (agentic) 표시를 확인한 뒤.

python code/common.py

이렇게 나오면 준비 완료입니다.

========================================================
실습 환경 점검
========================================================
  프로젝트 폴더 : C:\Users\사용자명\Documents\agentic_ai
  데이터 폴더   : C:\Users\사용자명\Documents\agentic_ai\data  (존재: True)
  문서 폴더     : C:\Users\사용자명\Documents\agentic_ai\data\docs  (존재: True)
  사용 모델     : gemini-2.5-flash
  API 키        : 찾음
========================================================
모두 준비되었습니다. 1장을 시작하세요.
  python code/ch01_hello.py

경로는 각자 다릅니다. 볼 것은 세 가지입니다.

데이터 폴더 ... (존재: True)
사용 모델 : gemini-2.5-flash
API 키 : 찾음

`API 키 : 없음` 이 나오면

  API 키        : 없음
========================================================
위에서 '없음'이나 'False'가 보이면 1장 안내를 다시 확인하세요.

이 순서로 점검하세요.

.env 파일이 code/ 가 아니라 agentic_ai 바로 아래에 있는가
파일 이름이 env.txt 나 .env.txt 가 아니라 정확히 .env 인가 (Windows 메모장으로 만들면 .txt 가 몰래 붙습니다 — VS Code로 만드세요)
등호 양옆에 공백이 없는가
파일을 저장했는가

핵심 정리

API 키는 구글 서버에 내가 누구인지 알리는 신분증입니다.
키는 agentic_ai/.env 파일에 GEMINI_API_KEY=... 한 줄로 넣습니다.
코드에 키를 직접 쓰지 않는 이유는 유출·수정·공유 세 가지 때문입니다.
모델은 gemini-2.5-flash 를 씁니다. .env 의 GEMINI_MODEL 로 바꿀 수 있습니다.
python code/common.py 에서 API 키 : 찾음 이 보이면 환경 준비 끝입니다.
다음 절에서 드디어 첫 LLM 호출을 합니다.

API 키를 .env 파일에 넣기