728x90
Suna는 완전 오픈소스 범용 AI 에이전트 플랫폼으로, 자연어 대화를 통해 실제 업무를 자동화하고 지원하는 디지털 동반자입니다. 단순한 챗봇을 넘어서 웹 브라우저를 제어하고, 파일을 관리하며, 복잡한 워크플로우를 실행할 수 있는 진정한 AI 에이전트입니다.
- 🌐 완전 오픈소스: 전체 소스 코드가 공개되어 있어 자유롭게 수정 및 확장 가능
- 🤖 자연어 인터페이스: 복잡한 명령어 대신 일상 언어로 작업 지시
- 🔧 강력한 도구 통합: 브라우저 자동화, 파일 관리, API 호출 등 다양한 기능
- 🔒 격리된 실행 환경: Docker 기반 보안 샌드박스에서 각 에이전트 실행
- 📊 실시간 데이터 처리: 웹 크롤링, 데이터 분석, 보고서 생성 자동화
300x250
🏗️ 시스템 아키텍처
1. 백엔드 API (Python/FastAPI)
주요 기능:
- REST API 엔드포인트 제공
- LLM 통합 (Anthropic, OpenAI, Groq 등)
- 스레드 및 세션 관리
- 에이전트 작업 오케스트레이션2. 프론트엔드 (Next.js/React)
주요 기능:
- 반응형 사용자 인터페이스
- 실시간 채팅 인터페이스
- 파일 업로드/다운로드 관리
- 작업 진행 상황 시각화3. 에이전트 Docker 환경
포함 도구:
- Chromium 브라우저 (Playwright 통합)
- Python 코드 인터프리터
- 파일 시스템 접근
- 네트워크 도구
- 보안 샌드박스4. Supabase 데이터베이스
관리 항목:
- 사용자 인증 및 권한
- 대화 히스토리
- 파일 스토리지
- 에이전트 상태
- 실시간 구독📋 사전 준비사항
1. 필수 소프트웨어 설치
# Docker 설치 확인
docker --version
# Python 3.11 설치
python --version
# Git 설치
git --version
# Node.js (수동 설정 시)
node --version
npm --version2. Supabase 프로젝트 설정
- Supabase 계정 생성
- 새 프로젝트 생성
- Project Settings → API에서 다음 정보 확보
- Project URL:
https://xxxxx.supabase.co - Anon Key:
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... - Service Role Key:
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
- Project URL:
3. 필수 API 키 준비
LLM 제공자 (최소 1개 필수)
- Anthropic (권장): Claude API 키
- OpenAI: GPT API 키
- Groq: 고속 추론 API 키
- OpenRouter: 다중 모델 접근 키
검색 및 크롤링
- Tavily: 고급 웹 검색 API
- Firecrawl: 웹 스크래핑 API
실행 환경
- Daytona: 보안 컨테이너 실행 API
- QStash: 백그라운드 작업 처리
🚀 설치 프로세스
방법 1: 자동 설치 (권장)
# 1. 저장소 클론
git clone https://github.com/kortix-ai/suna.git
cd suna
# 2. 설정 마법사 실행
python setup.py설정 마법사 14단계
- 도구 확인: 필수 소프트웨어 설치 여부 확인
- API 키 수집: 각 서비스별 API 키 입력
- Supabase 설정: 데이터베이스 연결 구성
- Redis 구성: 캐싱 설정
- Daytona 설정: 에이전트 실행 환경 구성
- LLM 통합: AI 모델 선택 및 설정
- 검색 도구 설정: Tavily, Firecrawl 구성
- QStash 설정: 백그라운드 작업 구성
- 환경 파일 생성:
.env파일 자동 생성 - 의존성 설치: 필요한 패키지 설치
- 데이터베이스 마이그레이션: 스키마 생성
- 권한 설정: 필요한 권한 구성
- 최종 확인: 설정 검증
- 서비스 시작: Docker 컨테이너 실행
방법 2: 수동 설치
백엔드 환경 설정 (backend/.env)
# 기본 설정
ENV_MODE=local
# 데이터베이스
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_ANON_KEY=your-anon-key
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key
# 캐싱
REDIS_HOST=redis
REDIS_PORT=6379
REDIS_PASSWORD=
REDIS_SSL=false
# 메시지 큐
RABBITMQ_HOST=rabbitmq
RABBITMQ_PORT=5672
# LLM 제공자
ANTHROPIC_API_KEY=sk-ant-xxxxx
OPENAI_API_KEY=sk-xxxxx
MODEL_TO_USE=anthropic/claude-sonnet-4-20250514
# 웹 도구
TAVILY_API_KEY=tvly-xxxxx
FIRECRAWL_API_KEY=fc-xxxxx
# 에이전트 실행
DAYTONA_API_KEY=dyt-xxxxx
DAYTONA_SERVER_URL=https://app.daytona.io/api
# 백그라운드 작업
QSTASH_URL=https://qstash.upstash.io
QSTASH_TOKEN=qst-xxxxx
WEBHOOK_BASE_URL=https://your-domain.com
# MCP 암호화
MCP_CREDENTIAL_ENCRYPTION_KEY=your-32-char-key
# 프론트엔드 URL
NEXT_PUBLIC_URL=http://localhost:3000프론트엔드 환경 설정 (frontend/.env.local)
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
NEXT_PUBLIC_BACKEND_URL=http://localhost:8000/api
NEXT_PUBLIC_URL=http://localhost:3000
NEXT_PUBLIC_ENV_MODE=LOCAL🏃 실행 방법
Docker Compose 사용 (권장)
# 모든 서비스 시작
docker compose up -d
# 또는 Python 스크립트 사용
python start.py
# 중지
docker compose down수동 실행
# 1. 필수 서비스 시작
docker compose up redis rabbitmq -d
# 2. 프론트엔드 실행 (터미널 1)
cd frontend
npm install
npm run dev
# 3. 백엔드 API 실행 (터미널 2)
cd backend
uv run api.py
# 4. 워커 실행 (터미널 3)
cd backend
uv run dramatiq run_agent_background💼 실제 활용 사례
1. 경쟁사 분석
"영국 헬스케어 산업의 주요 기업들을 분석해줘.
시장 규모, 강점, 약점을 포함하고 웹사이트 URL도 추가해줘.
완료되면 PDF 보고서로 생성해줘."2. 투자자 리스트 작성
"미국의 주요 VC 펀드 목록을 만들어줘.
운용자산(AUM) 기준으로 정렬하고,
웹사이트 URL과 연락 가능한 이메일을 포함해줘."3. 인재 채용
"LinkedIn에서 뮌헨에 거주하는 주니어 소프트웨어 엔지니어
10명의 프로필을 찾아줘. 컴퓨터 과학 학사 학위와
1년 이상의 경력이 있는 구직자여야 해."4. SEO 분석
"suna.so 웹사이트의 SEO 분석 보고서를 생성해줘.
키워드 클러스터별 상위 페이지를 찾고,
누락된 주제를 식별해줘."5. 과학 논문 요약
"지난 5년간 알코올이 신체에 미치는 영향에 대한
과학 논문을 조사하고 비교해줘.
주요 논문들에 대한 종합 보고서를 생성해줘."🔧 고급 설정 및 최적화
Daytona 스냅샷 생성
1. Daytona 대시보드 접속
2. 새 스냅샷 생성:
- 이름: kortix/suna:0.1.3
- 이미지: kortix/suna:0.1.3
- 엔트리포인트: /usr/bin/supervisord -n -c /etc/supervisor/conf.d/supervisord.confQStash 웹훅 설정
1. Upstash 콘솔에서 QStash 활성화
2. 웹훅 엔드포인트 설정:
- URL: https://your-domain.com/api/webhooks
- 서명 키 저장
3. 환경 변수에 키 추가성능 최적화
# docker-compose.yml 수정
services:
backend:
deploy:
resources:
limits:
cpus: '2'
memory: 4G
reservations:
cpus: '1'
memory: 2G🐛 일반적인 문제와 해결법
1. Docker 서비스 시작 실패
# 로그 확인
docker compose logs -f
# 포트 충돌 확인
sudo lsof -i :3000
sudo lsof -i :8000
# Docker 재시작
sudo systemctl restart docker2. 데이터베이스 연결 오류
-- Supabase 대시보드에서 실행
GRANT USAGE ON SCHEMA basejump TO anon, authenticated;
GRANT ALL ON ALL TABLES IN SCHEMA basejump TO anon, authenticated;3. LLM API 오류
# 백엔드 로그에서 확인
tail -f backend/logs/api.log
# API 키 검증
curl -H "Authorization: Bearer YOUR_API_KEY" \
https://api.anthropic.com/v1/messages4. 에이전트 실행 오류
# Daytona 로그 확인
docker logs suna-agent-container
# 권한 문제 해결
chmod -R 755 ./agent5. 로그 모니터링
# 전체 시스템 로그
docker compose logs -f
# 특정 서비스 로그
docker compose logs -f backend
docker compose logs -f frontend
docker compose logs -f worker🔒 보안 권장사항
1. API 키 관리
- 환경 변수 사용 (하드코딩 금지)
.env파일을.gitignore에 추가- 정기적인 키 순환
2. 네트워크 보안
- HTTPS 적용 (Let's Encrypt 사용)
- 방화벽 규칙 설정
- VPN 사용 고려
3. 데이터 보호
- 정기적인 백업
- 암호화된 스토리지 사용
- 접근 로그 모니터링
4. 컨테이너 보안
- 최신 이미지 사용
- 불필요한 권한 제거
- 리소스 제한 설정
📚 추가 리소스
- 공식 문서: https://docs.suna.so
- GitHub: https://github.com/kortix-ai/suna
- Discord 커뮤니티: 기술 지원 및 토론
- YouTube 튜토리얼: 실제 사용 예시 영상
728x90
그리드형(광고전용)
댓글