AI 에이전트를 위한 오픈 소스, 로컬 우선 워크플로우 실행 엔진

AI 에이전트를 위한 오픈 소스, 로컬 우선 (local-first) 워크플로우 실행 엔진

문서 ·
텔레메트리 (Telemetry) ·
기능 ·
아키텍처 (Architecture) ·
이슈 (Issues)

당신은 순서가 지정된 단계 (LLM, HTTP, Tool, Delay)로 구성된

**워크플로우 (Workflow)**를 생성합니다 -
워크플로우를 실행하면

태스크 (Task) (수동 또는 예약됨)가 생성됩니다 -

**에이전트 (Agent)**가 각 단계를 **결정론적 (deterministically)**으로 실행합니다 -
모든 단계는 다음을 생성합니다:

• 입력 (input)

• 출력 (output)

• 성공 / 실패 (success / failure)

당신은 **완전한 가시성 (full visibility)**을 바탕으로 검사, 디버깅, 재실행 및 자동화를 수행할 수 있습니다.

**AI 에이전트 자동화 플랫폼 (AI Agent Automation Platform)**은 AI 기반 워크플로우를 위한 **개발자 우선 실행 엔진 (developer-first execution engine)**입니다.

이것은 다음이 아닙니다:

• 프롬프트 플레이그라운드 (prompt playground)
• 챗봇 UI 데모
• SaaS에 종속된 자동화 도구

이것은 다음입니다:

• 실제 워크플로우 엔진
• 결정론적이고 단계별인 실행
• 에이전트 주도 자동화
• 완전한 로컬 및 셀프 호스팅 (self-hosted)

만약 당신이 n8n, Zapier, 또는 Temporal과 같은 도구를 좋아하지만, **AI 네이티브 (AI-native)**하고, 로컬이며, 검사 가능한 (inspectable) 무언가를 원한다면, 이 프로젝트가 당신을 위한 것입니다.

✔ AI 기반 자동화를 구축하는 개발자 ✔ 검사 및 디버깅 가능한 실행이 필요한 팀 ✔ 개인정보 보호를 중시하며 셀프 호스팅 환경을 사용하는 사용자

❌ 챗봇 전용 데모 ❌ 프롬프트 전용 실험 ❌ 노코드 (No-code) SaaS 사용자

• 자율적인 AI 에이전트가 워크플로우를 실행합니다

• 플러그형 LLM 지원 (OpenAI, Gemini, Groq, 로컬 모델)

• 결정론적 실행 모델

• 단계별 명시적 입력 및 출력

• 단계 수준의 성공 / 실패 추적

• 시각적 워크플로우 빌더

• 순차적인 단계

• 지원되는 단계 유형:
  LLM— 추론 및 생성
  HTTP— API 호출
  Tool— 내부 작업
  Delay— 시간 기반 제어

각 워크플로우 실행은 완전한 추적성을 가진 **태스크 (Task)**가 됩니다.

• Cron 기반 스케줄

• 자동 태스크 생성

• 다음 용도에 이상적입니다:

• 모니터링

• 보고서

• 백그라운드 자동화

• 주기적 데이터 동기화

• 태스크 실행 타임라인

• 단계 수준의 출력 및 오류

• 실시간 시스템 로그

• 명확한 실패 원인 규명

• 추측이 아닌 **근본 원인 분석 (root-cause analysis)**을 위해 구축되었습니다

• 지속적이고 에이전트 범위 내에서 관리되는 시맨틱 메모리 (semantic memory)

• 코사인 유사도 (cosine similarity)를 이용한 임베딩 기반 검색 (embedding-based retrieval)

• 노이즈 방지를 위한 유사도 임계값 필터링 (similarity threshold filtering)

• 에이전트당 보유 용량 제한 (retention cap)

• 토큰 안전 프롬프트 인젝션 (token-safe prompt injection)

• 완전한 벤더 중립성 (외부 벡터 DB 불필요)

에이전트가 워크플로우 실행 전반에 걸쳐 관련 있는 과거 상호작용을 회상할 수 있도록 합니다.

Frontend (Next.js)
↓
REST API (Express)
...

📘 상세 아키텍처, 실행 모델 및 내부 구조: https://vmdeshpande.github.io/ai-automation-platform-website/

백엔드 (Backend)

• Node.js + Express
• MongoDB
• Cron 스케줄러 (Cron Scheduler)
• 커스텀 에이전트 런타임 (Custom Agent Runtime)

프론트엔드 (Frontend)

• Next.js
• React
• Tailwind CSS

AI 및 자동화 (AI & Automation)

• 플러그형 LLM 어댑터 (Pluggable LLM adapters)

• 도구 샌드박싱 (Tool sandboxing)

• 로컬 우선 실행 (Local-first execution)

• AI 워크플로우 자동화

• 예약된 백엔드 작업

• 모니터링 및 경고 에이전트

• 문서 처리 파이프라인

• 내부 개발자 도구

• 보안 AI 실험

• 완전한 셀프 호스팅 (Fully self-hosted)

• 기본적으로 데이터가 시스템 외부로 유출되지 않음

• 환경 변수를 통해서만 비밀 정보 (secrets) 관리

• 벤더 종속성 없음 (No vendor lock-in)

• 숨겨진 SaaS 의존성 없음

• 메모리는 MongoDB에 로컬로 저장됨

• 외부 벡터 데이터베이스가 필요하지 않음

git clone https://github.com/vmDeshpande/ai-agent-automation.git
cd ai-agent-automation

cd backend
npm install
cp .env.example .env
...

백엔드 (Backend) → http://localhost:5000

cd frontend
npm install
npm run dev

프론트엔드 (Frontend) → http://localhost:3000

Docker를 사용하여 전체 플랫폼(MongoDB, 백엔드 API, 워커, 프론트엔드)을 실행하세요.

• Docker Desktop: https://www.docker.com/products/docker-desktop/
• Docker Compose (Docker Desktop에 포함됨)

설치 확인:

docker --version
docker compose version

cd infra
# 환경 설정 복사
cp .env.example .env
...

시작 후 다음 주소로 접속하세요:

만약 3000, 5000, 또는 27017 포트가 이미 사용 중이라면, 시작하기 전에 infra/.env 파일에서 FRONTEND_PORT, BACKEND_PORT, 또는 MONGO_PORT를 변경하십시오.

서비스	URL	설명
Frontend	http://localhost:3000	Next.js 웹 인터페이스 (기본값, 설정 가능)
...

시작 순서:

MongoDB
↓
Mongo Replica Init
...

MongoDB 레플리카 셋 (Replica Sets)은 시작 중에 자동으로 초기화됩니다.

환경 파일 편집:

infra/.env

설정 예시:

MONGO_URI=mongodb://mongo:27017/ai-agent
JWT_SECRET=your-secure-random-string
# LLM 제공자 (LLM Providers)
...

이 포트 변수들은 선택 사항입니다. 변경하지 않고 그대로 두면, Docker Compose는 위에 표시된 기본 포트를 사용합니다. 프론트엔드 API URL은 BACKEND_PORT로부터 자동으로 유도됩니다.

Docker 배포를 위해 infra/.env에서 NEXT_PUBLIC_API_URL을 설정할 필요는 없습니다.

docker compose up -d

docker compose logs -f

docker compose down

docker compose up --build

docker compose down -v

기본 포트가 이미 사용 중인 경우:

# infra/.env
MONGO_PORT=27018
BACKEND_PORT=5001
...

프론트엔드 API URL은 BACKEND_PORT로부터 자동으로 유도되므로, Docker 배포를 위해 NEXT_PUBLIC_API_URL을 설정할 필요가 없습니다.

시작 직후 Docker가 백엔드(backend)를 비정상(unhealthy) 상태로 보고하는 경우:

docker compose logs -f backend mongo mongo-init-replica

이전에 이전 레플리카 셋 설정으로 MongoDB가 시작된 적이 있다면, 로컬 초기화(clean local reset)를 수행하십시오:

docker compose down -v
docker compose up -d --build

이렇게 하면 로컬 Mongo 볼륨(volume)이 제거되고 레플리카 셋이 처음부터 다시 생성됩니다.

시작 후 스택(stack)이 정상인지 확인하려면:

docker compose ps
docker compose logs --tail 50 backend worker

이미 nginx 리버스 프록시 (reverse proxy)를 실행 중인 경우:

/api → http://localhost:5000
/ → http://localhost:3000

infra/.env에서 BACKEND_PORT 또는 FRONTEND_PORT를 재정의(override)했다면, 이 프록시 대상(proxy targets)을 그에 맞춰 업데이트하십시오.

개발을 위해서는 보통 다음 명령만 필요합니다:

docker compose up

Docker가 자동으로 이미지를 빌드하고 모든 서비스를 시작합니다.

backend/
├─ agents/
├─ models/
...

계획된 기능(Planned features)과 장기적인 비전은 프로젝트 웹사이트에서 확인할 수 있습니다.

기여(Contributions)는 언제나 환영합니다.

만약 다음과 같은 분야에 관심이 있다면:

• AI 에이전트 (AI agents)
• 백엔드 시스템 (Backend systems)
• 자동화 엔진 (Automation engines)
• 개발자 도구 (Developer tooling)

이곳이 매우 편안하게 느껴지실 것입니다.

자세한 내용은 CONTRIBUTING.md를 참조하세요.

Apache License 2.0

단순한 프롬프트 놀이터 (Prompt playground)가 아닙니다. 진짜 AI 실행 엔진 (AI execution engine)입니다.