수강생한테 약속한 단어가 "챗봇"이 아니라 "에이전트"였다

오늘 오후 강의 자료를 점검하다가 멈칫했다. 수강생들에게 미리 보낸 안내에는 "파일 읽고 쓰고 웹서치하고 자료찾고 글도 써주는 에이전트 셋팅" 이라고 적혀 있었다. 그런데 강의용으로 만들어둔 코드는 그냥 텔레그램에서 Gemini 와 대화하는 챗봇 한 마리. 도구 0개. 권한 0개.

그대로 가면 강의 끝나고 수강생이 폰에서 봇한테 "내 바탕화면 뭐 있어?" 물어볼 거고, 봇은 "저는 PC 에 접근할 수 없어요" 라고 답할 거다. 돈 받고 ChatGPT 의 열등 복제판 만든 게 된다. 즉시 갈아엎기로 결정.

1단계: 도구 5개 박기 (Gemini Function Calling)

google-generativeai 의 tools=[...] 인자에 함수 객체 그대로 넣으면 Gemini 가 자동으로 함수 시그니처와 docstring 을 읽어서 호출 후보로 삼는다. 그리고 start_chat(enable_automatic_function_calling=True) 를 켜면 SDK 가 호출 → 결과 → 다음 추론 사이클을 자동으로 돌린다. 학생 입장에서는 그냥 자연어로 시키기만 하면 됨.

박은 도구 5종:

def list_files(directory): ...        # 작업 폴더 목록
def read_file(filename): ...          # 텍스트 파일 읽기
def write_file(filename, content): ... # 텍스트 파일 쓰기
def web_search(query): ...            # DuckDuckGo 검색
def fetch_url(url): ...               # 웹페이지 텍스트 추출

파일 R/W 는 ~/Desktop/agent-workspace/ 안에서만 동작하도록 path traversal 차단 함수 _safe_path() 박음. 이걸로 봇이 시스템 파일 건드리는 사고는 차단.

2단계: 자동 시작 + 준비 완료 알림

수강생이 강의 끝나고 PC 끄면 봇도 같이 꺼진다. 그러면 폰으로 날린 메시지에 답이 안 옴. 수강생이 "이거 작동 안 해요" 라고 강사한테 메시지 보내고, 강사는 "PowerShell 창 켜져있어요?" 답하는 핑퐁이 발생할 게 뻔하다.

해결: Windows 시작프로그램 폴더 (shell:startup) 에 박는 start_bot.bat. PC 켜지면 자동으로 봇 시작 + 텔레그램으로 "🟢 AI 에이전트 준비 완료" 알림 푸시.

python-telegram-bot 의 post_init 콜백을 활용해서 봇이 polling 시작 직전에 ALLOWED_USER_IDS 에게 메시지 한 번 보냄. 학생은 폰 알림 받으면 "준비됐구나" 인지.

3단계: 검증 4번 — 한글 인코딩 지뢰 발견

여기서 4번의 검증 사이클을 돌렸다. 첫 두 번은 통과. 세 번째에 격리된 환경에서 직접 cmd.exe 로 .bat 을 실행시켜봤더니 메시지가 깨지고 학생이 봇이 죽었을 때 받는 출력이 이렇게 나왔다:

'��세요.' is not recognized as an internal or external command
'TART_COUNT!' is not recognized as an internal or external command

원인: 한국어 윈도우의 cmd.exe 가 .bat 파일을 cp949 로 먼저 파싱하고, UTF-8 한글 바이트가 cp949 로 미스매치되면서 일부 명령줄이 깨짐. chcp 65001 을 위로 올려도 파일 자체 파싱은 그 전에 일어나서 안 풀림.

해결: bat 안의 모든 한글 메시지 영문화. 어차피 학생은 .bat 안 읽음. 한국어 출력은 Python (bot.py) 의 print() 가 책임지고, Python 은 UTF-8 안전. 4번째 검증에서 깨끗한 출력 확인.

[INFO] Waiting 10 seconds for network...
========================================
[2026-05-04 18:20:13] Starting AI Agent (attempt #0)
========================================
fake bot started, exiting clean
[2026-05-04 18:20:13] Bot exited (code: 0)
Normal exit. Run this file again to restart.

4단계: 무한 재시작 루프 차단

자동 재시작은 양날의 검이다. API 키 잘못 박으면 영원히 재시작 → CPU 빨고 텔레그램 알림 폭주. 학생이 새벽 3시에 "선생님 텔레그램이 5천번 울렸어요" 메시지 보내는 시나리오를 차단해야 함.

start_bot.bat 에 MAX_RESTART=5 카운터 박음. 5회 연속 실패 시 자동 재시작 중단 + "키 3개 확인하세요" 안내. 정상 종료 (Ctrl+C, exit 0) 와 크래시 (exit ≠ 0) 를 구분해서, 정상 종료는 재시작 안 함.

결과물 4개

1. AI 에이전트 만들기 가이드 (Google Docs)
2. bot.py                   ~240줄, 도구 5개, allowlist 박힘
3. start_bot.bat            ASCII-only, 5회 재시도 한도
4. requirements.txt         pinned versions 5개

학생이 다운받아서 키 3개만 채우면 폰에서 진짜 PC 작업이 가능한 에이전트가 손에 들어온다. 그게 약속이었고, 약속을 지켰다.

이걸 깃허브 공개 레포로 올리면서, 강의 후 수강생이 직접 도구를 추가할 수 있도록 "Tool 더 박기 — 2편: subprocess / 3편: 클라우드 24/7" 시리즈로 확장 예정. 첫 강의에서 챗봇 → 에이전트 갈아탔으니, 후속 강의는 에이전트 → 자동화 → 운영 단계로.