Theseus

Theseus는 에이전트 개발 플랫폼을 목표로 한 프로젝트입니다. 사용자의 개발 요청을 API 서버가 검증하고, Kafka 이벤트 흐름을 통해 AI 코어가 도구 계획, 도구 실행, RAG 기반 작업을 수행하는 구조를 설계했습니다.

SSAFY 정책과 팀 소스 보호를 위해 공개 저장소에는 실행 가능한 내부 코드를 공개하지 않습니다. 대신 원본 Git에서 추적하던 폴더명과 파일명을 그대로 복제한 0바이트 파일명 골격을 포함해, 전체 시스템의 경계와 규모는 확인할 수 있게 했습니다.

커리어 근거로 읽는 법

항목	내용
프로젝트 유형	SSAFY 자율 프로젝트, 팀 프로젝트
내 역할	AI 에이전트 백엔드, ERD/API, ToolPlan/ToolBuild Kafka 파이프라인, Redis/SSE 상태 복구, 원격 작업공간
주력 기술	FastAPI, Spring Boot, Kafka, Redis, SSE, Docker 샌드박스, Paramiko SSH, React
보여주고 싶은 역량	에이전트 실행 흐름을 채팅 기능이 아니라 권한, 상태, 원격 실행, 승인, 복구가 있는 서비스 계약으로 만드는 역량
결과	SSAFY 자율과정 프로젝트 우수상, 서울캠퍼스 발표 대표 선정, SSAFY 14기 전시발표회 입상

제가 이 프로젝트에서 강조하고 싶은 부분은 LLM 호출보다, AI 에이전트의 계획/승인/실행/복구 흐름을 백엔드 계약으로 고정한 경험입니다. 비공개 원본 GitLab 기준 작성자 MR 73건이 모두 병합되었고, 공개 저장소에는 실행 가능한 코드 대신 원본 파일명 골격과 구조 문서를 공개합니다.

프로젝트 방향

Theseus는 단일 API 서버에 LLM 호출을 붙이는 구조가 아니라, 서비스 API와 AI 에이전트 반복 흐름을 분리하는 방향으로 설계했습니다.

• 프론트엔드는 Theseus API 서버만 호출한다.
• API 서버는 인증, 권한, 요청 검증, 서비스 상태, 사용자 접점 계약을 담당한다.
• 코어 서버는 AI 에이전트 반복 흐름, 도구 계획, 도구 실행, RAG 작업을 담당한다.
• API 서버와 코어 서버는 Kafka 이벤트로 비동기 연결한다.
• Redis와 Kafka는 조정 계층이며 최종 데이터 저장소가 아니다.
• MySQL은 서비스 도메인 데이터, PostgreSQL/pgvector는 AI/RAG 데이터에 사용한다.

핵심 문제

에이전트 작업 흐름은 데모에서는 빠르게 만들 수 있지만, 제품화하려면 다음 경계가 필요합니다.

• 사용자의 요청을 어디서 검증하고 승인할 것인가
• 에이전트가 실행한 도구 호출과 결과를 어떤 단위로 기록할 것인가
• 채팅/세션/이력/과금 같은 서비스 도메인과 RAG/도구 실행 도메인을 어떻게 분리할 것인가
• 비동기 이벤트 흐름에서 실패, 재시도, 상태 조회를 어떻게 다룰 것인가
• LLM 공급자 키, Jenkins 인증 정보, 배포 키 같은 운영 비밀값을 어디까지 격리할 것인가

Theseus는 이 문제들을 API 서버, AI 코어, 이벤트 파이프라인, 영속 계층으로 나눠 풀려고 한 프로젝트입니다.

시스템 개요

flowchart LR
  WEB["프론트엔드"]
  API["Theseus API Server<br/>Spring Boot"]
  KAFKA["Kafka 이벤트 흐름"]
  CORE["AI 코어 서버<br/>FastAPI"]
  RAG["RAG 저장소<br/>PostgreSQL / pgvector"]
  MYSQL["서비스 DB<br/>MySQL"]
  REDIS["Redis<br/>coordination / cache"]
  TOOL["도구 실행"]

  WEB <-->|REST| API
  API --> MYSQL
  API --> REDIS
  API --> KAFKA
  KAFKA --> CORE
  CORE --> RAG
  CORE --> TOOL
  CORE --> KAFKA
  KAFKA --> API

Loading

주요 영역

영역	역할
프론트엔드	사용자 요청, 채팅/세션 화면, 작업 상태 확인
API 서버	인증, 권한, 요청 검증, 과금/이력/채팅 도메인
AI 코어	LLM 호출 조율, 도구 계획, 도구 실행, RAG 파이프라인
이벤트 흐름	Kafka 기반 API/코어 비동기 연결
영속 계층	MySQL 서비스 데이터, PostgreSQL/pgvector AI/RAG 데이터
인프라	Docker, Nginx, Jenkins/배포 스크립트, 로컬 확장 패키징

기술 스택

영역	기술
프론트엔드	TypeScript 프론트엔드
API Server	Spring Boot, Java, Gradle
AI 코어	Python, FastAPI
이벤트 흐름	Kafka
인프라/상태	Redis, MySQL, PostgreSQL, pgvector, Docker, Nginx
AI 기능	LLM, RAG, 도구 계획, 도구 실행

공개 저장소 구성

• REPOSITORY_STRUCTURE.md: 원본 Git 추적 파일 전체 구조
• 각 파일명 골격 파일: 원본 파일명을 보존하기 위한 0바이트 자리 표시 파일
• 루트 README.md: 공개 설명 문서

프론트엔드/백엔드/코어 내부 구현, DB/Redis/Kafka 인증 정보, LLM 공급자 키, Jenkins/배포 인증 정보, 생성된 빌드 산출물은 공개하지 않습니다.

공개하지 않는 항목

• Spring API 서버 내부 구현 코드 내용
• FastAPI AI Core 내부 구현 코드 내용
• 프론트엔드 내부 구현 코드 내용
• 운영 DB, Redis, Kafka, 객체 저장소 인증 정보
• LLM 공급자 키, Jenkins 인증 정보, 배포 키
• 비공개 MR/배포 맥락과 생성된 산출물

전체 개발 이력과 비공개 자료는 비공개 저장소와 원본 비공개 원격 저장소에서 관리합니다.