SENTINEL — 멀티 에이전트 AI 회사

역할을 맡은 여러 AI 에이전트(기획·개발·디자인·QA·마케팅·행정)가 협업해, 고객의 프로젝트 의뢰 한 줄을 소프트웨어 산출물(요구사항 정의서 → 디자인/코드 → 테스트 계획 → 홍보문)로 만들어내는 멀티 에이전트 시스템.

개인 학습 프로젝트. 에이전트 루프·도구 호출을 프레임워크(LangChain 등) 없이 직접 구현하고, 서로 다른 LLM 프로바이더(Claude · OpenAI · Kimi · 로컬 Ollama)를 공통 인터페이스로 추상화해 설정만으로 갈아끼울 수 있게 만들었다.

---

✨ 특징

• 멀티 에이전트 — 역할별 6개 에이전트가 매니저의 조율 아래 협업한다.
• 멀티 프로바이더 — Claude(Anthropic) · OpenAI · Kimi(Moonshot) · 로컬(Ollama)을 하나의 Agent 인터페이스로 추상화.
• 클라우드 ↔ 로컬 전환 — .env의 LLM_* 3줄만으로 전원을 로컬 모델로 전환(무료 구동) 또는 클라우드로 복귀. (12-factor)
• 두 개의 얼굴(runner) — 터미널 / 디스코드 봇. 같은 회사를 다른 얼굴로 굴린다.
• 견고성 — 도구 호출 루프 상한 + 소형 모델이 도구를 안 부르면 텍스트를 저장하는 폴백.

🏗 아키텍처

runners/            얼굴 (사람과 I/O)
├─ console.py        터미널
└─ discord_bot.py    디스코드 (!회사 <의뢰>)
        │  Company().build(의뢰)
company.py          매니저 (누구에게 무슨 일을, 어떻게 넘길지)
        │  직원.run(작업)     ← 공통 Agent 인터페이스
agents/             직원 (실제 일)
├─ pm.py             기획 (Claude)
├─ designer.py       디자인 (OpenAI)
├─ developer.py      개발 (Kimi)
├─ qa.py             QA (Kimi)
├─ marketing.py      마케팅 (Kimi)
├─ admin.py          행정 (Kimi)
├─ base.py           Agent 인터페이스(추상 클래스)
└─ openai_agent.py   OpenAI 호환 공통 베이스(루프 1벌)

핵심 설계: 얼굴 · 매니저 · 직원 3층을 분리하고, 그 사이를 공통 인터페이스로 이었다. 덕분에 —

• 직원 추가 = 클래스 하나(+ 리스트 한 줄)
• 얼굴 추가 = 러너 하나 (에이전트는 안 건드림)
• 두뇌 교체 = 해당 파일만

🚀 실행

python -m venv .venv
.venv\Scripts\activate           # PowerShell: .venv\Scripts\Activate.ps1
pip install -r requirements.txt
cp .env.example .env
python run.py                    # 의뢰 한 줄 입력 → output/ 에 산출물

A. 클라우드 (품질 우선)

.env에 키를 채운다:

ANTHROPIC_API_KEY=...
OPENAI_API_KEY=...
MOONSHOT_API_KEY=...

B. 로컬 (무료, Ollama)

Ollama로 모델을 받고, .env에 아래 3줄만 두면 전원이 로컬로 전환된다:

ollama pull hermes3:8b

LLM_BASE_URL=http://localhost:11434/v1
LLM_MODEL=hermes3:8b
LLM_API_KEY=ollama

디스코드로 굴리기

.env에 DISCORD_BOT_TOKEN=... 후:

python -m runners.discord_bot        # 채널에서 !회사 <의뢰>

🧠 이 프로젝트로 익힌 것

에이전트 루프(생각→도구→관찰→반복) · 도구 호출(function/tool calling) · 프로바이더별 API 차이(Anthropic vs OpenAI) · 인터페이스/추상화 · 오케스트레이션 · 12-factor 설정 분리 · 로컬 LLM(Ollama) 연동.

⚠️ 현재 상태 (정직하게)

동작하는 프로토타입이다. 프로덕션 완성품은 아니다.

• 로컬(Ollama)로는 실제 end-to-end 구동을 확인했고, 클라우드 경로는 구조 검증(mock) 완료.
• 직원 간 협업은 파일 기반 순차 파이프라인(진짜 상호 대화/코드 리뷰는 아직 아님).
• 자동화 테스트 스위트·상세 에러 처리·재시도 로직은 미비.
• 소형 로컬 모델 출력 품질은 거칠다(클라우드 모델 권장).

🗺 로드맵

• 직원 간 진짜 협업(QA가 개발 코드 리뷰 등)
• Anthropic 공통 베이스로 Claude 직원도 얇게 + 개발자 두뇌 Claude 전환 옵션
• 자동화 테스트 · 에러 처리/재시도
• 산출물 웹 대시보드