XI. Agent의 핵심 부품을 여러 파일로 나누어 실제 프로젝트 구조 만들기
#-------- 1. tools.py 파일와 main.py 파일: main.py에서 tools 사용하기
# 파일1: tools.py
def calculator(expr):
return eval(expr)
def word_count(text):
return len(text.split())
REGISTRY = {"calculator":calculator, "word_count":word_count}
# 파일2: main.py
import tools
from tools import REGISTRY, word_count
print(tools.calculator("8*5"))
print(word_count("에이전트는 루프입니다"))
print("available: ", list(REGISTRY))
print(REGISTRY["calculator"]("200/25"))
#-------- 2. __name__과 __main__
def build_agent():
return {"name":"Scout", "tools":["search"]}
print("__name__is: ", __name__)
if __name__ == "__main__":
agent = build_agent()
print("직접 실행 중, 시작: ", agent["name"])
else:
print("가져오기 완료, 아무것도 시작하지 않음")
#-------- 3. 실제 프로젝트 폴더 구조
# my-agent/
# venv/ 가상 환경 (커밋되지 않음)- the virtual environment, never committed
# .env 비밀 키 (커밋되지 않음) - your secrets, never committed
# .gitignore Git이 건너뛸 항목을 지정 - tells git what to skip
# requirements.txt 고정된 종속성 - pinned dependencies
# main.py 진입점, 모든 것을 연결 - entry point, wires everthing up
# agent.py 에이전트 클래스 및 반복문 - the Agent class and the loop
# tools.py 도구 함수 및 레지스트리 - tool functions and the registry
# llm.py 모델 호출 및 응답 파싱 - the model call and response parsing
# agent_data/ 런타임에 기록되는 기록 및 로그 - history and logs written at runtime
#-------- 4. 환경변수에서 API Key 읽기
import os
api_key = os.environ.get("MODEL_API_KEY")
if not api_key:
print("MODEL_API_KEY is not set, refusing to start")
else:
print("key loaded, length: ", len(api_key))
print("safe preview: ", api_key[:4] + " ... " + api_key[-2:])
#-------- 5. .env와 python-dotenv 그리고 config Dictionary 만들기
# pip install python-dotenv
# .env (a plain text file, no quotes, no spaces around=)
# MODEL_API_KEY=sk-abcde12345
# MODEL_NAME=some-model
# MAX_STEPS=5
import os
from dotenv import load_dotenv
load_dotenv()
config ={
"api_key":os.environ.get("MODEL_API_KEY"),
"model":os.environ.get("MODEL_NAME", "default-model"),
"max_steps":int(os.environ.get("MAX_STEPS", "5")),
}
print("model: ", config["model"])
print("max_steps: ", config["max_steps"], type(config["max_steps"]))
print("key present: ", bool(config["api_key"]))
#-------- 6. .gitignore
# gitignore 파일
# .env
# venv/
# __pycache__/
# *.pyc
# agent_data/
# .DS_Store
#-------- 7. 이제 진짜 프로젝트 구조
# 파일1. tool.py 파일
def calculator(expr):
allowed = set("0123456789+-*/().")
if not set(expr) <= allowed:
return "unsupported characters"
return str(eval(expr))
def greet(name):
return f"안녕, {name}!"
REGISTRY = {"calculator":calculator, "greet":greet}
# 파일2. agent.py
class Agent:
def __init__(self, tools, max_steps=5):
self.tools=tools
self.max_steps=max_steps
self.steps=0
self.history=[]
def run_tool(self, name, args):
self.steps +=1
if name not in self.tools:
return f"unknown tool '{name}'"
try:
return str(self.tools[name](**args))
except Exception as e:
return f"tool failed: {e}"
# 파일3: main.py
import os
from agent import Agent
from tools import REGISTRY
def load_config():
return {
"api_key":os.environ.get("MODEL_API_KEY"),
"model":os.environ.get("MODEL_NAME", "default-model"),
"max_steps":int(os.environ.get("MAX_STEPS", "5")),
}
def main():
config = load_config()
print(f"model={config['model']} max_steps={config['max_steps']}")
print("key configured: ", bool(config["api_key"]))
bot = Agent(REGISTRY, max_steps=config["max_steps"])
print(bot.run_tool("calculator", {"expr":"(25*4)+8"}))
print(bot.run_tool("greet", {"name":"스티븐"}))
print(f"steps used: {bot.steps}/{bot.max_steps}")
if __name__ == "__main__":
main()
지금까지는 하나의 .py 파일 안에서:
Agent
Tools
Config
환경변수
실행 코드를 모두 작성했습니다.
이번 코드부터는 이렇게 나눕니다.
my-agent/
│
├── main.py ← 프로그램 시작점
├── agent.py ← Agent 클래스
├── tools.py ← Tool 함수들
├── llm.py ← AI 모델 호출
├── .env ← API Key
└── requirements.txt ← 필요한 라이브러리이것은 실제 AI Agent 프로젝트의 기본적인 구조입니다.
전체 구조를 먼저 그림으로 보면
┌─────────────┐
│ main.py │
│ 프로그램 시작 │
└──────┬──────┘
│
┌────────────────┼────────────────┐
│ │ │
▼ ▼ ▼
agent.py tools.py llm.py
Agent Tools AI Model
│ │ │
└────────────────┼────────────────┘
│
▼
.env
API KEY / 설정이제 하나씩 보겠습니다.
1. tools.py 파일
def calculator(expr):
return eval(expr)
def word_count(text):
return len(text.split())
REGISTRY = {
"calculator": calculator,
"word_count": word_count
}이 파일의 역할은:
Agent가 사용할 도구들을 정의하고 관리하는 것
입니다.
calculator
def calculator(expr):
return eval(expr)예:
calculator("8*5")↓
40word_count
def word_count(text):
return len(text.split())예:
word_count("에이전트는 루프입니다")split() 결과:
["에이전트는", "루프입니다"]길이:
2REGISTRY
REGISTRY = {
"calculator": calculator,
"word_count": word_count
}이것은 우리가 이전에 공부했던 Tool Registry입니다.
구조는:
Tool 이름 실제 함수
───────── ─────────
calculator → calculator()
word_count → word_count()즉:
REGISTRY["calculator"]↓
calculator그리고:
REGISTRY["calculator"]("8*5")↓
40입니다.
2. main.py에서 tools 사용하기
import tools의 의미:
tools.py 파일 전체를 가져온다.
이제:
tools.calculator("8*5")처럼 사용할 수 있습니다.
구조:
tools
│
├── calculator
├── word_count
└── REGISTRY따라서:
tools.calculator("8*5")↓
40
3. from tools import ...
from tools import REGISTRY, word_count이번에는 필요한 것만 가져옵니다.
그래서:
word_count("에이전트는 루프입니다")처럼 사용할 수 있습니다.
tools.word_count()라고 안 써도 됩니다.
두 import 방식 비교
방법 1
import tools사용:
tools.calculator("8*5")장점:
어느 파일의 함수인지 명확함방법 2
from tools import calculator사용:
calculator("8*5")장점:
짧고 편함실제 프로젝트에서는 개인적으로:
import tools또는:
from tools import REGISTRY처럼 사용하는 것이 구조 파악에 편합니다.
4. list(REGISTRY)
print("available: ", list(REGISTRY))Dictionary에서:
list(REGISTRY)는 기본적으로 Key 목록을 가져옵니다.
즉:
{
"calculator": calculator,
"word_count": word_count
}↓
["calculator", "word_count"]출력:
available: ['calculator', 'word_count']5. Registry에서 Tool 실행
REGISTRY["calculator"]("200/25")이 코드는 처음 보면 약간 신기합니다.
단계별로 보면:
REGISTRY["calculator"]↓
calculator즉 함수 자체를 가져옵니다.
그리고:
("200/25")를 붙이면:
calculator("200/25")가 됩니다.
↓
8.06. __name__과 __main__
다음 코드입니다.
def build_agent():
return {
"name": "Scout",
"tools": ["search"]
}
print("__name__ is: ", __name__)Python 파일에는 자동으로:
__name__이라는 특별한 변수가 있습니다.
직접 실행하면
예:
python main.py이 경우:
__name__은:
__main__입니다.
다른 파일에서 import하면
예:
import agent이면 agent.py 안에서는:
__name__이:
agent가 됩니다.
그래서:
if __name__ == "__main__":의 의미는:
이 파일을 직접 실행했을 때만 아래 코드를 실행해라.
입니다.
직접 실행
if __name__ == "__main__":
agent = build_agent()
print("직접 실행 중")↓
실행됩니다.
import
import some_file↓
if __name__ == "__main__":조건이 False입니다.
따라서:
Agent를 자동으로 시작하지 않습니다.이것이 매우 중요합니다.
쉽게 비유하면
tools.py는:
공구함
입니다.
안에는:
망치
드라이버
렌치가 있습니다.
하지만 tools.py를 import했다고 해서 망치질을 자동으로 시작하면 이상합니다.
그래서:
도구 정의와:
실제 프로그램 실행을 분리하는 것입니다.
7. 실제 프로젝트 폴더 구조
주석에 있는 구조:
my-agent/
│
├── venv/
├── .env
├── .gitignore
├── requirements.txt
├── main.py
├── agent.py
├── tools.py
├── llm.py
└── agent_data/하나씩 보겠습니다.
venv/
가상환경프로젝트별 Python 환경입니다.
예:
Project A
└── requests 2.31
Project B
└── requests 2.32처럼 서로 독립적으로 관리할 수 있습니다.
Git에는 올리지 않습니다.
.env
비밀 설정예:
MODEL_API_KEY=sk-xxxx
MODEL_NAME=gpt-model
MAX_STEPS=5API Key를 코드에 직접 쓰지 않는 이유는:
main.py
↓
GitHub
↓
API Key 노출 ❌위험하기 때문입니다.
.gitignore
Git에게:
이 파일들은 추적하지 마세요.
라고 알려줍니다.
예:
.env
venv/
agent_data/requirements.txt
프로젝트에 필요한 라이브러리 목록입니다.
예:
openai==...
python-dotenv==...
requests==...다른 사람이:
pip install -r requirements.txt하면 필요한 라이브러리를 설치할 수 있습니다.
8. 환경변수에서 API Key 읽기
import os
api_key = os.environ.get("MODEL_API_KEY")운영체제 환경변수에서:
MODEL_API_KEY를 찾습니다.
없으면
if not api_key:
print("MODEL_API_KEY is not set, refusing to start")Agent를 실행하지 않습니다.
이것은 좋은 습관입니다.
왜냐하면 API Key 없이 실행하면:
API 호출 실패가 발생하기 때문입니다.
있으면
else:
print("key loaded")정상적으로 Key를 읽었다는 의미입니다.
9. API Key Preview
api_key[:4]앞 4글자:
sk-aapi_key[-2:]뒤 2글자입니다.
예:
sk-abcde12345↓
sk-a ... 45전체 Key를 출력하지 않고:
정상적으로 Key가 로드되었는지확인하는 방법입니다.
실제 운영 환경에서는 Key 길이나 일부 문자열조차 로그에 남기지 않는 것이 더 안전한 경우도 많습니다.
10. .env와 python-dotenv
from dotenv import load_dotenv
load_dotenv()이 함수의 역할:
.env 파일을 읽어서 환경변수로 등록한다.
예:
.env
MODEL_API_KEY=sk-abcde12345
MODEL_NAME=some-model
MAX_STEPS=5실행:
load_dotenv()이후:
os.environ.get("MODEL_API_KEY")로 읽을 수 있습니다.
⚠️ 코드에 작은 오타가 있습니다
주석에서는:
MODLE_NAME = some-model라고 되어 있습니다.
하지만 코드에서는:
os.environ.get("MODEL_NAME", "default-model")를 찾습니다.
즉:
MODLE_NAME ❌
MODEL_NAME ⭕이어야 합니다.
올바른 .env:
MODEL_API_KEY=sk-abcde12345
MODEL_NAME=some-model
MAX_STEPS=5그리고 = 앞뒤에 공백을 두지 않는 편이 좋습니다.
11. config Dictionary 만들기
config = {
"api_key": os.environ.get("MODEL_API_KEY"),
"model": os.environ.get("MODEL_NAME", "default-model"),
"max_steps": int(os.environ.get("MAX_STEPS", "5")),
}여기서 중요한 것은:
환경변수 → 문자열이라는 것입니다.
예:
MAX_STEPS=5이더라도:
os.environ.get("MAX_STEPS")결과는:
"5"문자열입니다.
그래서:
int(...)로 변환합니다.
↓
5정수입니다.
기본값
os.environ.get(
"MODEL_NAME",
"default-model"
)의 의미:
MODEL_NAME이 있으면 그것을 사용하고, 없으면 default-model을 사용하라.
입니다.
12. .gitignore
.env
venv/
__pycache__/
*.pyc
agent_data/
.DS_Store하나씩 보면:
| .env | API Key 등 비밀 |
| venv/ | 가상환경 |
| __pycache__/ | Python 캐시 |
| *.pyc | Python 컴파일 캐시 |
| agent_data/ | 실행 중 생성된 데이터 |
| .DS_Store | macOS 시스템 파일 |
특히:
.env는 정말 중요합니다.
API Key가 GitHub에 올라가면 매우 위험합니다.
13. 이제 진짜 프로젝트 구조
마지막 부분은 앞의 모든 내용을 합칩니다.
tools.py
def calculator(expr):계산기입니다.
allowed = set("0123456789+-*/().")허용되는 문자만 지정합니다.
예:
0123456789
+
-
*
/
(
)
.if not set(expr) <= allowed:의미:
expr 안의 모든 문자가 allowed 안에 들어있는가?
예:
expr = "25*4"↓
모든 문자가 허용됨.
True하지만:
expr = "__import__('os')"허용되지 않은 문자가 포함됩니다.
↓
unsupported characters그래서 이전의 단순한:
eval(expr)보다 조금 안전합니다.
다만 실제 서비스용 계산기는 eval() 자체를 피하는 것이 더 좋습니다. 나중에 Agent를 실제 OpenAI 모델과 연결할 때는 안전한 계산기 함수를 별도로 만드는 것을 추천합니다.
greet Tool
def greet(name):
return f"안녕, {name}!"간단한 Tool입니다.
REGISTRY
REGISTRY = {
"calculator": calculator,
"greet": greet
}Agent에게 줄 Tool 목록입니다.
Agent
│
└── REGISTRY
│
├── calculator()
└── greet()agent.py
class Agent:이 파일은 Agent 자체를 정의합니다.
def __init__(self, tools, max_steps=5):Agent 생성 시:
사용 가능한 Tool
최대 단계를 받습니다.
run_tool
def run_tool(self, name, args):Agent가 Tool을 실행합니다.
Step 증가
self.steps += 1Tool 호출 횟수를 기록합니다.
Tool 존재 확인
if name not in self.tools:예:
name = "emailer"그런데 Registry에는:
calculator
greet만 있다면:
unknown tool 'emailer'을 반환합니다.
여기에는 작은 오타가 있습니다.
return f"unknown too '{name}'"는:
return f"unknown tool '{name}'"가 자연스럽습니다.
Tool 실행
self.tools[name](**args)예:
name = "greet"
args = {
"name": "스티븐"
}↓
greet(name="스티븐")↓
안녕, 스티븐!main.py
이 파일은 전체 프로그램을 조립하는 곳입니다.
main.py
│
├── 설정 읽기
│
├── Agent 만들기
│
├── Tools 연결
│
└── Agent 실행load_config()
def load_config():설정을 읽는 일을 하나의 함수로 분리했습니다.
이것이 좋은 습관입니다.
이전에는:
api_key = ...
model = ...
max_steps = ...가 프로그램 여기저기에 흩어질 수 있었습니다.
하지만 이제:
load_config()만 보면:
설정은 여기서 관리하는구나.
하고 알 수 있습니다.
main()
def main():실제 프로그램의 중심입니다.
설정 로드
config = load_config()↓
{
"api_key": "...",
"model": "...",
"max_steps": 5
}Agent 생성
bot = Agent(
REGISTRY,
max_steps=config["max_steps"]
)이 부분이 중요합니다.
REGISTRY
│
├── calculator
└── greet
│
▼
AgentAgent는 Tool을 직접 모르고 있습니다.
단지:
tools라는 Dictionary를 받습니다.
이것이 좋은 설계입니다.
첫 번째 Tool 실행
bot.run_tool(
"calculator",
{"expr": "(25*4)+8"}
)흐름:
main.py
│
▼
Agent.run_tool()
│
▼
REGISTRY["calculator"]
│
▼
calculator(expr="(25*4)+8")
│
▼
108두 번째 Tool
bot.run_tool(
"greet",
{"name": "스티븐"}
)↓
안녕, 스티븐!Step 출력
print(f"steps used: {bot.steps}/{bot.max_steps}")결과:
steps used: 2/5입니다.
🔥 가장 중요한 전체 흐름
이 프로젝트 구조를 이해하면:
main.py
│
│ 시작
▼
load_config()
│
▼
.env / 환경변수
│
▼
config
│
▼
Agent 생성
│
┌──────────┴──────────┐
│ │
▼ ▼
REGISTRY max_steps
│
┌────┴─────┐
│ │
▼ ▼
calculator greet실행할 때:
사용자 요청
│
▼
Agent
│
▼
어떤 Tool?
│
▼
REGISTRY[name]
│
▼
실제 함수 실행
│
▼
결과 반환⭐ 그런데 현재 코드에는 한 가지 중요한 부분이 빠져 있습니다
마지막 main.py 코드에는 현재:
import os만 있습니다.
하지만 실제로는 Agent와 REGISTRY를 가져와야 합니다.
따라서 실제 main.py는 보통 이렇게 됩니다.
import os
from agent import Agent
from tools import REGISTRY
def load_config():
return {
"api_key": os.environ.get("MODEL_API_KEY"),
"model": os.environ.get("MODEL_NAME", "default-model"),
"max_steps": int(os.environ.get("MAX_STEPS", "5")),
}
def main():
config = load_config()
print(
f"model={config['model']} "
f"max_steps={config['max_steps']}"
)
print("key configured:", bool(config["api_key"]))
bot = Agent(
REGISTRY,
max_steps=config["max_steps"]
)
print(
bot.run_tool(
"calculator",
{"expr": "(25*4)+8"}
)
)
print(
bot.run_tool(
"greet",
{"name": "스티븐"}
)
)
print(
f"steps used: {bot.steps}/{bot.max_steps}"
)
if __name__ == "__main__":
main()🎯 이번 코드의 핵심은 이것입니다
지금까지 공부한 Agent를 실제 프로젝트로 바꾸는 과정입니다.
[이전]
하나의 파일
main.py
├── Agent
├── Tools
├── Config
└── 실행↓
[지금]
프로젝트
│
├── main.py
│ └── 조립 및 시작
│
├── agent.py
│ └── Agent의 행동
│
├── tools.py
│ └── Tool 정의
│
├── llm.py
│ └── OpenAI 모델 호출
│
├── .env
│ └── API Key
│
└── agent_data/
└── History / Log이제 다음 단계에서 여기에:
OpenAI API가 들어오면 진짜 Agent Loop가 됩니다.
사용자
↓
main.py
↓
Agent
↓
OpenAI Model
↓
"calculator를 사용하세요"
↓
Agent
↓
Tool 실행
↓
결과
↓
OpenAI Model
↓
최종 답변지금 배우는 순서가 아주 좋습니다. 앞에서 배운 함수 → Dictionary → JSON → Tool Registry → History → Loop → Error 처리 → Class → 파일 분리가 바로 실제 AI Agent를 만들기 위한 부품들이었고, 이번 코드에서 그 부품들을 처음으로 프로젝트 구조로 조립하기 시작한 것입니다.