AI 코딩 에이전트 직접 만들기: 파이썬·Gemini로 배우는 도구 호출과 에이전트 루프

핵심 메시지

• 이 강의의 목표는 코딩 에이전트를 팔아 돈을 버는 것이 아니라, 개발자가 매일 쓰는 AI 도구가 내부에서 어떻게 동작하는지 직접 만들어 보며 깊이 이해하는 것이다.
• 에이전트는 단발성 응답과 달리, 사용자의 한 번의 프롬프트에 대해 '도구 호출'을 반복하며 스스로 여러 번 시도하는 루프를 돌 수 있다는 점이 핵심이다.
• 단 네 가지 도구(디렉터리 목록 보기, 파일 읽기, 파일 쓰기, 파이썬 코드 실행)만으로도 에이전트는 코드를 스캔하고 수정하고 실행해 피드백을 얻으며 버그를 고칠 수 있다.
• 에이전트가 작업 디렉터리 밖의 파일에 접근하지 못하도록 하드코딩된 경계를 두는 것이 기본적인 안전장치이며, 함수는 예외 대신 LLM이 읽을 수 있는 명확한 오류 문자열을 돌려줘야 한다.
• LLM은 토큰 단위로 과금되므로 파일 읽기에 글자 수 상한을 두는 등 토큰 사용을 의식적으로 관리해야 하며, 이 프로젝트는 무료 Gemini Flash 한도 안에서 충분히 진행된다.

쉽게 이해하기

이 강의는 boot.dev의 레인 와그너가 프리코드캠프와 함께 제공하는 실습형 코스로, Cursor·Claude Code·OpenAI Codex 같은 코딩 에이전트의 '장난감 버전'을 파이썬과 무료 Gemini Flash API로 직접 만든다. 강사는 골드러시에서 직접 금을 캐기(바이브 코딩)보다 '삽을 파는' 쪽, 즉 도구의 원리를 이해하는 쪽이 낫다는 비유로 동기를 설명한다. 이진 트리를 배우는 이유와 같이, 매일 쓰는 도구가 내부에서 어떻게 작동하는지 알아야 더 효과적으로 쓸 수 있다는 것이다.

에이전트와 일반 챗봇의 차이는 분명하다. 브라우저 챗봇은 프로젝트 맥락이 없어 코드를 계속 복사·붙여넣기 해야 하지만, 에이전트는 프로젝트 디렉터리를 스캔하고 파일을 읽고 코드를 실행해 스스로 맥락을 모은다. 더 중요한 차이는 '루프'다. 한 번의 프롬프트에 한 번 답하는 대신, 도구 호출을 통해 스스로에게 반복적으로 프롬프트를 던지며 여러 번 시도할 수 있다.

에이전트에게 주어지는 도구는 네 가지다. 디렉터리의 파일 목록 보기, 파일 내용 읽기, 파일 내용 덮어쓰기, 그리고 파이썬 코드 실행이다. 강사는 '계산기 앱이 안 켜진다, 고쳐줘' 같은 요청을 받으면 에이전트가 파일 트리를 훑고, 문제가 있을 법한 파일을 읽고, 수정하고, 실행해 보고, 안 되면 다시 고치는 과정을 반복하는 흐름을 보여준다.

프로젝트는 파이썬 3.10 이상, 의존성 관리 도구 uv, 유닉스 계열 셸을 전제로 한다. uv로 프로젝트와 가상환경을 만들고 google-genai SDK와 python-dotenv를 추가한 뒤, Google AI Studio에서 발급한 API 키를 .env에 두고 git에서 제외한다. 그리고 client.models.generate_content로 Gemini Flash를 호출해 응답 텍스트와 토큰 사용량을 출력하며 기본기를 익힌다.

강의는 단발성 호출에서 출발해 대화 기록을 user·model 역할의 메시지 리스트로 관리하고, 개발자용 정보를 토글하는 --verbose 플래그를 추가하는 식으로 점진적으로 발전시킨다. 이어 functions 디렉터리에 get_files_info, get_file_content, write_file, run_python_file 함수를 하나씩 구현하는데, 모든 함수는 작업 디렉터리 밖 접근을 막는 가드레일과 LLM이 읽고 다음 시도에서 스스로 교정할 수 있는 좋은 오류 메시지를 갖추도록 강조한다.

주요 인사이트

• 에이전트의 본질은 학습 데이터에서 바로 답을 받는 것이 아니라, 백엔드 함수를 도구로 호출해 최신 정보나 외부 동작을 끌어와 응답에 반영하는 능력에 있다.
• 파일 경로를 직접 슬래시로 파싱하지 말고 os.path.abspath·join·dirname 같은 표준 라이브러리를 써야 운영체제 차이와 수많은 예외 상황을 안전하게 처리할 수 있다.
• 파일 읽기에 글자 수 상한(예: config.py의 MAX_CHARS)을 두고 초과 시 잘라내는 것은, 거대한 파일을 통째로 API에 올려 토큰을 낭비하지 않기 위한 실용적 장치다.
• LLM에게 임의의 파이썬 코드를 실행하게 하는 것은 위험하므로, 30초 타임아웃과 작업 디렉터리 제한을 두더라도 이 프로젝트는 교육용 장난감으로만 쓰고 일상 업무에는 Codex·Claude Code 같은 검증된 도구를 권한다.
• 에이전트를 직접 만들어 보면 LLM API의 동작, 토큰 관리, 도구 호출 기반 에이전트 루프를 깊이 이해하게 되어, AI 도구를 잘 다루는 개발자들과 경쟁하는 데 유리하다.

자주 묻는 질문

관련 AI 소식