Agent Orchestration Service (AOS)

LangGraph 기반 멀티 에이전트 오케스트레이션 서비스입니다.

Features

• 🤖 LangGraph 기반 에이전트 오케스트레이션: Orchestrator → Planner → Executor → Reviewer 그래프
• 📊 실시간 대시보드: WebSocket 기반 태스크 트리 및 에이전트 활동 시각화
• 🔄 자동 태스크 분해: 복잡한 작업을 서브태스크로 분해
• 📝 완전한 추적성: 모든 에이전트 활동 및 태스크 이력 저장
• 🔍 RAG: Qdrant 기반 의미론적 검색
• 🔐 인증: OAuth (Google/GitHub) + Email/Password
• 🛡️ HITL 승인: 위험 작업 전 사용자 승인 요청
• 🔌 MCP 연동: 외부 도구 통합 (filesystem, github, playwright)

🚀 Quick Start (Docker)

권장 방법 - Docker만 있으면 한 줄로 실행:

# 1. 저장소 클론
git clone https://github.com/k002bill2/Agent-System.git
cd Agent-System

# 2. 환경변수 설정 (LLM 키만 — 보안 시크릿은 setup.sh가 자동 생성)
cp .env.example .env
# .env 파일 편집하여 API 키 설정 (GOOGLE_API_KEY 또는 ANTHROPIC_API_KEY)

# 3. 셋업: 시크릿 자동 생성 + 이미지 빌드 + 전체 기동
./setup.sh

# 4. 접속
open http://localhost:5173

Self-host로 팀에 배포하나요? 원격 접속 설정, 첫 관리자 계정 부트스트랩, 백업, 그리고 보안 주의사항(내부망 전용) 은 docs/self-host-quickstart.md를 참조하세요. docker compose up -d를 직접 실행하면 시크릿 미설정으로 실패하므로 ./setup.sh를 사용하세요.

필수 환경변수

# LLM 프로바이더 선택 (하나만 필요)
LLM_PROVIDER=codex_cli       # codex_cli, openai, google, anthropic, ollama 중 선택
# codex_cli는 OpenAI API 키 대신 `codex` CLI의 ChatGPT 로그인 세션 사용
# 또는
OPENAI_API_KEY=your_key      # OpenAI API (사용량 과금)
# 또는
GOOGLE_API_KEY=your_key      # Google Gemini
# 또는
ANTHROPIC_API_KEY=your_key   # Claude
# 또는
# Ollama는 API 키 불필요 (로컬 실행)

서비스 URLs

서비스	URL
Dashboard	http://localhost:5173
Backend API	http://localhost:8000
PostgreSQL	localhost:5432
Redis	localhost:6379

Docker 명령어

# 상태 확인
docker compose ps

# 로그 보기
docker compose logs -f backend

# 중지
docker compose down

# 데이터 포함 완전 삭제
docker compose down -v

시스템 요구사항

항목	최소 요구
Docker	24.0+
Docker Compose	2.20+
RAM	4GB
디스크	10GB

---

🛠️ Development Setup (로컬 개발)

Docker 없이 개발 환경을 직접 구성하려면:

Prerequisites

• Python 3.11+
• Node.js 20+
• Docker & Docker Compose (PostgreSQL, Redis용)
• LLM API Key (Google, Anthropic, 또는 Ollama)

1. 환경 설정

cp .env.example .env
# .env 파일에 API 키 입력

2. 인프라 실행 (DB, Redis)

cd infra/scripts
./dev.sh

3. Backend 실행

cd src/backend
uv pip install -e .
uvicorn api.app:app --reload

4. Dashboard 실행

cd src/dashboard
npm install
npm run dev

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         Dashboard (React)                        │
│                      http://localhost:5173                       │
└─────────────────────────────────────────────────────────────────┘
                                 │
                         WebSocket/REST
                                 │
┌─────────────────────────────────────────────────────────────────┐
│                        FastAPI Backend                           │
│                      http://localhost:8000                       │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │                   LangGraph Engine                       │    │
│  │                                                          │    │
│  │   ┌──────────┐    ┌─────────┐    ┌──────────┐           │    │
│  │   │Orchestrator│──▶│ Planner │──▶│ Executor │           │    │
│  │   └──────────┘    └─────────┘    └──────────┘           │    │
│  │         │              │              │                  │    │
│  │         └──────────────┴──────────────┘                  │    │
│  │                        │                                 │    │
│  │                   ┌─────────┐                           │    │
│  │                   │Reviewer │                           │    │
│  │                   └─────────┘                           │    │
│  └─────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────┘
                                 │
                    ┌────────────┼────────────┐
                    │            │            │
           ┌────────┴────────┐ ┌┴──────────┐ ┌┴──────────┐
           │    PostgreSQL    │ │   Redis   │ │  Qdrant   │
           │   localhost:5432 │ │ :6379     │ │ :6333     │
           └─────────────────┘ └───────────┘ └───────────┘

Tech Stack

Layer	Technology
Backend	Python 3.11, LangGraph 0.2+, FastAPI 0.115+, SQLAlchemy 2.0+
Frontend	React 18, TypeScript 5.6+, Tailwind CSS 3.4, Zustand 5.0, Vite 6.0+
Database	PostgreSQL 16
Cache/Queue	Redis 7
Vector DB	Qdrant (RAG)
AI	Codex CLI (기본), OpenAI API, Google Gemini, Anthropic Claude, Ollama

API

REST Endpoints

Method	Path	Description
POST	/api/sessions	Create new session
GET	/api/sessions/{id}	Get session state
POST	/api/sessions/{id}/tasks	Submit task
DELETE	/api/sessions/{id}	Delete session

WebSocket

// Connect
const ws = new WebSocket('ws://localhost:8000/ws/{session_id}')

// Send task
ws.send(JSON.stringify({
  type: 'task_create',
  payload: { title: 'My Task', description: 'Task description' }
}))

// Receive events
ws.onmessage = (event) => {
  const { type, payload } = JSON.parse(event.data)
  // type: task_started, task_progress, agent_thinking, ...
}

Development

Backend Tests

cd src/backend
pytest ../../tests/backend -v

Dashboard Tests

cd src/dashboard
npm test

Type Checking

# Backend
cd src/backend
mypy .

# Dashboard
cd src/dashboard
npx tsc --noEmit

Deployment

프로덕션 배포는 Railway 또는 Render를 권장합니다:

Railway (권장)

Render

1. Render Dashboard에서 "New Blueprint" 선택
2. 이 저장소 연결
3. render.yaml이 자동으로 감지되어 배포됨

자세한 배포 가이드는 docs/deployment.md를 참조하세요.

License

MIT