AI 에이전트 팀 구조를 agents/ 폴더로 재편하고 파이프라인 전체를 처음으로 완주한 날이다. 38일째 실습 기록이다.
그동안 run_pipeline.py 파일 하나에 모든 기능이 뭉쳐 있었는데, 오늘은 그걸 역할별로 쪼갰다. 작업을 나누는 게 이렇게 속 시원한 일인 줄 몰랐다.
오늘 목표
에이전트를 역할별로 분리하고, 각각 단독으로 실행되는지 확인하는 것. 분리가 다 되면 파이프라인 전체를 한 번 돌려보는 게 목표였다.
AI 에이전트(각 작업을 자율적으로 수행하는 프로그램 단위)를 하나의 파일에 몰아두면 나중에 수정할 때 어디를 건드려야 할지 알기 어렵다. 역할별로 파일을 나눠두면 각각 독립적으로 테스트하거나 교체할 수 있어서 유지보수가 훨씬 편해진다.
준비물
- Python — 에이전트 스크립트 실행 환경
- Claude API 콘솔 — API 키 발급
- 기존
run_pipeline.py파일 - 에디터 (VS Code 등)
Step 1 — agents/ 폴더 구조로 분리하기
기존 파일을 열어서 역할별로 코드를 잘라냈다. 새로 만든 구조는 이렇다.
agents/
├── research_agent.py
├── writing_agent.py
├── posting_agent.py
└── control_agent.py각 파일이 하는 일은 이름 그대로다.
research_agent— 키워드 조사, 자료 수집writing_agent— 수집된 자료로 글 초안 작성posting_agent— 작성된 글을 블로그에 발행control_agent— 전체 흐름을 순서대로 조율
잘라내는 건 어렵지 않았는데, 문제는 다음 단계였다.
위는 에디터에서 본 agents/ 폴더 구조 화면이다.
Step 2 — 각 에이전트 단독 실행 테스트
가장 오래 걸린 부분이 여기였다. 분리는 했는데, 막상 단독으로 실행하면 다른 파일에서 뭔가를 불러오지 못해서 에러가 계속 났거든요.
에러가 나올 때마다 Claude한테 에러 화면을 보여줬더니 어디서 경로 참조가 끊겼는지 짚어주고 고쳐줬다. 혼자 했으면 한참 걸렸을 것 같다.
수정 후에 research_agent부터 단독 실행 테스트를 해봤다. 터미널에서 아래 명령어를 입력했다:
python agents/research_agent.py --kw-only--kw-only는 키워드 선별 기능만 단독으로 돌리는 옵션이다. 실행하면 아래처럼 결과가 출력된다:
총 후보 키워드: 27개
선별된 키워드: 1개
→ "AI 에이전트 팀 구조"27개 항목 중 키워드 1개를 자동으로 골라내는 걸 직접 확인했다. 생각보다 깔끔하게 동작해서 이게 맞나 싶을 정도였다.
위는 research_agent 단독 실행 후 키워드 선별 결과 출력 화면이다.
Step 3 — 기본 모델을 gemma로 교체하고 전체 파이프라인 완주
단독 테스트가 다 통과되고 나서 전체 파이프라인을 한 번 돌렸다. control_agent가 나머지 에이전트를 순서대로 호출하는 구조다.
이번에 기본 모델을 기존에 쓰던 Sonnet 단독 구성에서 gemma로 바꿨다. Claude에게 두 모델의 출력 결과를 비교해보자고 했더니, 직접 써보니 글 품질 차이가 눈에 띄게 났다.
| 항목 | Sonnet 단독 | gemma 교체 후 |
|---|---|---|
| 글 자연스러움 | 보통 | 눈에 띄게 향상 |
| 파이프라인 완주 | 미완료 | 1회 완주 성공 |
| –memo 옵션 | 없음 | 추가 완료 |
▲ Sonnet 단독 vs gemma 교체 후 비교
--memo 옵션도 이번에 새로 추가했다. 이 옵션을 쓰면 오늘처럼 실습 메모를 직접 입력해서 글 소재로 쓸 수 있다. 실제로 이 글도 --memo 옵션으로 초안을 만들었다.
터미널에서 전체 파이프라인을 돌리는 명령어는 이렇다:
python agents/control_agent.py --memo "오늘 실습 내용 입력"명령어 한 줄로 research → writing → posting 순서로 전부 돌아간다. 코드를 직접 짠 게 아니라 Claude가 구조를 잡아줬고, 알려준 대로 따라하면서 동작을 확인했다.
오늘 결과 정리
- run_pipeline.py 단일 파일 → agents/ 폴더 4개 파일로 분리 완료
- research_agent 단독 실행: 27개 중 키워드 1개 자동 선별 확인
- AI 에이전트 팀 전체 파이프라인 1회 완주 성공
- 기본 모델 gemma로 교체, 글 품질 향상 확인
- –memo 옵션 추가로 실습기 직접 작성 가능
코딩을 잘 몰라도 Claude에게 에러를 보여주고 구조를 물어보면서 여기까지 왔다. 파이프라인이 돌아가는 걸 보면서 뭔가 제대로 된 AI 에이전트 팀이 시작됐다는 느낌이 들었다.
자주 묻는 질문
Q. 에이전트를 굳이 파일별로 나눠야 하나요?
하나에 몰아도 동작은 해요. 근데 나중에 특정 에이전트만 수정하거나 교체하려고 할 때 어디를 건드려야 할지 찾기 어려워지거든요. 지금은 아직 작은 규모라서 체감이 덜할 수 있는데, 기능이 늘어날수록 분리해두는 게 낫다는 걸 직접 겪어보니 알겠더라고요.
Q. –kw-only 같은 옵션은 어떻게 만드나요?
Claude한테 “이 에이전트를 단독으로 테스트할 수 있게 옵션 추가해줘”라고 하면 argparse(파이썬에서 명령줄 옵션을 처리하는 기본 라이브러리) 코드를 만들어줘요. 알려준 코드를 파일에 붙여넣는 것만으로 됐다.
Q. 파이프라인 완주 실패하면 어떻게 하나요?
에러 메시지를 그대로 복사해서 Claude에게 보여주면 어디서 끊겼는지 알려줘요. 저도 오늘 에이전트 단독 실행 단계에서 경로 에러가 몇 번 났는데, 그렇게 해결했다.
파이프라인 완주는 됐다. 근데 아직 성에 차지는 않아요. 이 팀을 어떻게 더 키울지가 진짜 숙제인데, 그건 다음 실습에서 이어가려고 한다.
📌 관련 글도 읽어보세요
썸네일: Bench Accounting on Unsplash