AI Supervisor: AI 에이전트가 작업을 수행하고, AI Supervisor가 그 작업 완료를 보장합니다.

_이 글은 Hacktoberfest Open-Source AI Challenge Week 2: Side Hustle에 제출하는 내용입니다.

제가 만든 것

AI 코딩 에이전트는 코드를 작성하고 작업을 완료할 수 있지만, 단순히 '완료' 메시지가 작동하는 결과를 보장하지는 못합니다. 이들은 실패한 접근 방식을 반복하거나, 작업 인계 과정에서 컨텍스트를 잃거나, 변경 사항이 여전히 검증에 실패했음에도 성공했다고 보고할 수 있습니다. 개발자는 결국 모든 실행을 수동으로 감독해야 합니다.

AI Supervisor는 AI 코딩 에이전트를 위한 제어 평면(control plane)입니다. 사용자가 미션(mission)을 주면, 이 시스템은 작업을 태스크로 구조화하고, 실행 전에 인간의 승인을 요구하며, 호환되는 에이전트 런타임을 조정하고, 진행 상황을 모니터링하며, 실패에 대응하고, 수락 기준(acceptance criteria)에 따라 결과를 검증합니다.

그 핵심 원칙 중 하나는 '완료됨(completed)'과 '검증됨(verified)'은 다른 상태라는 것입니다. 의존적인 작업이 단순히 에이전트가 끝났다고 말한다고 해서 진행되어서는 안 됩니다.

또한, 저희는 FalkorDB를 그래프 메모리 레이어(graph memory layer)로 통합했습니다. 실행 이력을 단절된 로그로 취급하는 대신, 미션, 태스크, 실패, 감독 결정(supervisory decisions), 인계 과정, 검증 증거를 연결합니다. 이를 통해 개발자가 어떤 작업이 왜 실패했는지, 그 뒤에 어떤 결정이 따랐는지, 그리고 결과가 무엇을 뒷받침하는지 이해할 수 있는 추적 가능한 이력(history)을 생성합니다.

이 프로젝트는 실제 다단계 소프트웨어 개발 작업을 AI 에이전트로 실행하는 개발자, AI 엔지니어 및 소규모 팀을 위해 설계되었습니다.

데모

실시간 애플리케이션: https://ai-supervisior.vercel.app/

이 애플리케이션에는 미션 실행을 위한 제어실(Control Room)과 그래프 상태, 태스크 관계, 실행 계보(execution lineage), 감독 결정 및 검증 증거를 탐색할 수 있는 FalkorDB 그래프 메모리 작업 공간(Graph Memory Workspace)이 포함되어 있습니다.

코드

GitHub 저장소: https://github.com/M0izz/AI-Supervisior

프로젝트는 프런트엔드에 React, TypeScript, Vite를 사용하고, 백엔드에는 Python과 FastAPI를 사용합니다. 실시간 업데이트에는 WebSockets을 사용하며, 애플리케이션 상태에는 SQLite를, 연결된 미션 메모리에는 FalkorDB를, 그리고 구성된 경우 작업 격리를 위해 Git Worktrees를 사용합니다.

구축 과정

저는 AI Supervisor를 LLM 주변의 또 다른 채팅 인터페이스가 아니라 오케스트레이션 및 신뢰성 문제로 접근했습니다.

워크플로우는 미션 생명주기(mission lifecycle)를 중심으로 구축되었습니다:

이해 → 계획 → 승인 → 실행 → 모니터링 → 복구 → 검증

사용자가 먼저 목표를 제출합니다. Supervisor가 이를 작업, 의존성 및 수용 기준(acceptance criteria)으로 구조화합니다. 사용자는 실행을 시작하기 전에 계획을 검토합니다. 실행 중에는 시스템이 작업 상태와 이벤트를 추적하며, 워치독 모니터링(watchdog monitoring)은 정지(stalls) 및 반복되는 실패를 파악하는 데 도움을 줍니다. 그 후 결과는 요구된 기준에 따라 평가됩니다.

FalkorDB는 미션 관계의 배경이 되는 그래프 모델을 제공합니다. 노드(Nodes)는 미션, 작업, 실행, 실패, 결정, 인계(handoffs), 검증, 증거와 같은 개체들을 나타냅니다. DEPENDS_ON, FAILS_WITH, RESPONDS_TO, SELECTS, EVALUATES_EXECUTION, SUPPORTED_BY와 같은 관계들이 이 개체들을 연결합니다.

이 구조는 실행 기록을 조사하기 쉽게 만듭니다. 예를 들어, 실패는 그 뒤를 이은 결정, 다음 시도를 위해 선택된 에이전트, 그리고 검증과 관련된 증거까지 추적할 수 있습니다.

SQLite와 FalkorDB는 서로 다른 목적을 수행합니다: SQLite는 애플리케이션 상태를 처리하고, FalkorDB는 연결된 미션 기록 및 관계를 나타냅니다. 전용 그래프 저장 계층(graph storage layer)과 Graph Memory Workspace 덕분에 해당 정보가 애플리케이션과 개발자에게 접근 가능하게 됩니다.

UTF-8 BOM 파싱 오류와 관련된 시연 워크플로우는 실패한 시도, 복구 경로, 그리고 검증 증거가 어떻게 연결되고 검사될 수 있는지 보여주었습니다.

Open Innovation은 왜 중요한가요?

AI 감독(supervision)은 다양한 도구, 런타임 및 인프라 선택 전반에 걸쳐 작동해야 합니다. 전체 시스템을 하나의 독점 에이전트나 모델에 고정하는 것은 개발자들이 워크플로우를 자신들의 프로젝트에 맞게 조정하기 어렵게 만들 것입니다.

개방형 혁신(Open innovation)은 아키텍처를 검사하고, 통합을 조정하며, 다양한 호환 런타임으로 실험하고, 시스템을 협력적으로 개선하는 것을 가능하게 합니다. 또한 오픈 소스 구성 요소들은 모든 것을 단일 플랫폼에 강제하기보다 각기 다른 책임에 맞는 전문화된 도구를 선택할 수 있게 해줍니다.

FalkorDB는 특히 관련성이 높았는데, 그 그래프 모델이 실패(failures), 결정(decisions), 의존성(dependencies) 및 증거(evidence) 간의 관계를 명시적으로 표현하는 방법을 제공했기 때문입니다. 이러한 연결고리들은 임무 기록을 디버깅과 감독에 유용하게 만드는 데 핵심적입니다.

더 큰 교훈은 신뢰할 수 있는 AI 에이전트 시스템은 단순히 뛰어난 모델만으로는 부족하다는 것입니다. 이들은 투명한 상태(transparent state), 연결된 컨텍스트(connected context), 검사 가능한 결정(inspectable decisions), 그리고 결과를 검증하는 방법들을 필요로 합니다.

수상 부문

• 최우수 오픈 소스 AI 프로젝트