🪡 orra
Orra는 회복 탄력성이 있는 AI 에이전트 워크플로 (Agent Workflows)를 위한 인프라입니다. API 중단, 평가 (Evals) 실패 등과 같은 장애로부터 에이전트가 복구할 수 있도록 도와 워크플로가 계속 진행되도록 유지합니다.
에이전트, 도구 (Tools), 그리고 기존 스택 (Stack) 전반에 걸쳐 작업을 지능적으로 조정함으로써, orra는 어떤 환경에서도 견고한 실행을 보장합니다. 어떠한 언어, 에이전트 프레임워크 (Agent Framework), 또는 배포 플랫폼 (Deployment Platform)과도 원활하게 작동하도록 설계되었습니다.
- 🧠 자동 에이전트/서비스 검색 기능을 갖춘 계획 에이전트 (Planning agent)
- 🗿 상태 지속성 (State persistence)을 통한 내구성이 있는 실행 (Durable execution)
- 🎯 사전 검증된 실행 계획 (Pre-validated execution plans)
- ↩️ 장애 처리를 위한 상태 되돌리기 (Revert state)
- 🕵 추적 가능성을 위한 감사 로그 (Audit logs)
- 🚀 서비스를 도구로 활용하여 속도 향상 및 비용 절감
- ⛑️ 자동 상태 모니터링 (Automatic health monitoring)
- 🔮 실시간 상태 추적 (Real-time status tracking)
- 🏢 온프레미스 (On-premises) 배포
- 🪝 완료 및 실패에 대한 웹훅 (Webhooks) 알림
orra를 구축한 이유 알아보기 →
출시 예정 (Coming Soon)
- 인기 있는 에이전트 프레임워크를 위한 통합 어댑터 (Integration adapters)
- 신뢰할 수 있는 커버리지로 워크플로 확장
- 평가 (Evals) 실패 시 계획 수정 (Course correction) 계획
- 에이전트 재생 (Agent replay) 및 멀티 LLM 합의 계획 (Multi-LLM consensus planning)
- 종단간 암호화 (End-to-end encryption)
- 세분화된 워크플로 액세스 제어 (Granular workflow access controls)
- 런타임 (Runtime) 중 에이전트 워크플로의 지속적인 조정
- 추가 언어 SDK - Ruby, DotNet 및 Go 곧 지원 예정!
- MCP 통합
- 규제 산업의 요구 사항을 충족하기 위한 SOC 2 및 GDPR 준비
목차 (Table of Contents)
설치 (Installation)
필수 요구 사항 (Prerequisites)
- Docker 및 Docker Compose - Plan Engine (플랜 엔진) 실행용
- 작업 계획 (Task Planning) 및 실행 계획 캐싱/검증 (Caching/Validation)을 위한 추론 모델 (Reasoning Models) 및 임베딩 모델 (Embedding Models) 설정
Plan Engine을 위한 모델 설정
지원되는 다양한 모델 중에서 선택하십시오:
추론 모델 (Reasoning Models):
- 클라우드 기반 OpenAI의
o1-mini 또는 o3-mini
- 클라우드 또는 셀프 호스팅 (온프레미스 또는 로컬) 기반의
deepseek-r1 또는 qwq-32b
임베딩 모델 (Embedding Models):
- 클라우드 기반 OpenAI의
text-embedding-3-small
- 클라우드 또는 셀프 호스팅 (온프레미스 또는 로컬) 기반의
jina-embeddings-v2-small-en
참고 (Note): Plan Engine은 모든 모델 엔드포인트가 **OpenAI API와 호환 (OpenAI API-compatible)**될 것을 요구합니다. 대부분의 모델 서빙 솔루션 (vLLM, LMStudio, Ollama 등)은 이 호환 가능한 API 형식을 노출하도록 구성할 수 있습니다.
클라우드 빠른 설정 예시:
_env 파일을 기반으로 다음 중 하나를 사용하여 .env 파일을 업데이트하십시오:
# OpenAI 추론 (Reasoning)
LLM_MODEL=o1-mini
LLM_API_KEY=your_api_key
...
셀프 호스팅/온프레미스 예시:
_env 파일을 기반으로 다음 중 하나를 사용하여 .env 파일을 업데이트하십시오:
# 셀프 호스팅 QwQ 모델
LLM_MODEL=qwq-32b-q8
LLM_API_KEY=your_internal_key # 설정에 따라 선택 사항
...
→ 전체 모델 구성 문서 (Complete Model Configuration Documentation)
1. orra CLI 설치
릴리스 페이지에서 사용 중인 플랫폼에 맞는 최신 CLI 바이너리를 다운로드하십시오:
# macOS
curl -L https://github.com/orra-dev/orra/releases/download/v0.2.6/orra-darwin-arm64 -o /usr/local/bin/orra
chmod +x /usr/local/bin/orra
...
→ 전체 CLI 문서 (Full CLI documentation)
2. orra Plan Engine 실행하기
저장소(Repository)를 클론하고 Plan Engine을 시작하십시오:
git clone https://github.com/ezodude/orra.git
cd orra/planengine
...
Plan Engine의 작동 원리
Plan Engine은 지능적인 계획 (Intelligent Planning)과 신뢰할 수 있는 실행 (Reliable Execution)을 통해 멀티 에이전트 애플리케이션을 구동합니다:
점진적 계획 단계 (Progressive Planning Levels)
1. 기본 계획 (Base Planning)
에이전트가 깔끔하고 단순한 상태를 유지합니다 (orra SDK로 래핑됨):
Python
from orra import OrraAgent, Task
from pydantic import BaseModel
...
JavaScript
import { initAgent } from '@orra.dev/sdk';
const agent = initAgent({
...
주요 기능:
- AI가 의도 (Intent)를 분석하고 구성 요소 (Components)를 대상으로 하는 실행 계획 (Execution Plans)을 생성합니다.
- 자동 서비스 검색 (Service Discovery) 및 조정 (Coordination)
- 가능한 경우 병렬 실행 (Parallel Execution)
2. 도메인 접지(Domain Grounding)를 통한 프로덕션 계획 (Production Planning)
name: research-workflow
domain: content-generation
...
주요 기능:
- 실행 계획에 대한 완전한 의미론적 검증 (Semantic Validation)
- 역량 매칭 (Capability Matching) 및 검증
- 안전 제약 조건 (Safety Constraints) 강제 적용
- 상태 전이 (State Transition) 검증
3. 신뢰할 수 있는 실행 (Reliable Execution)
orra verify run "Research and summarize AI trends" \
--data topic:"AI in 2024" \
...
계획 엔진 (Plan Engine)은 다음을 보장합니다:
- 자동 서비스 상태 모니터링 (Service Health Monitoring)
- 상태 유지 실행 추적 (Stateful Execution Tracking)
- 내장된 재시도 (Retries) 및 복구 (Recovery)
- 실시간 상태 업데이트
- 결과 전달 및 모니터링을 위한 웹훅 (Webhook) 이벤트
Orra vs 에이전트 프레임워크 및 워크플로우 엔진
Orra는 AI 워크플로우 오케스트레이션 (Orchestration)에 독특한 접근 방식을 취합니다. 다른 솔루션과의 비교는 다음과 같습니다:
| orra | Agent Frameworks<br/>(예: Mastra, LangGraph) | Workflow Engines<br/>(예: Temporal, Inngest) |
|---|
| 목적 (Purpose) | 멀티 에이전트 조정 계층 (Multi-agent coordination layer) | 개별 AI 에이전트 구축 (Build individual AI agents) | 사전에 계획된 워크플로우 실행 (Run pre-planned workflows) |
| ... | | | |
| Orra는 문제가 발생했을 때 취약한 스크립트나 수동 수정 없이 적응하고 복구해야 하는 AI 시스템을 구축하기 위한 것입니다. | | | |
Orra Plan Engine 대 MCP
| 측면 (Aspect) | Orra Plan Engine | Model Context Protocol (MCP) |
|---|
| 목적 (Purpose) | 멀티 에이전트 워크플로우를 엔드투엔드로 조정 (Orchestrate multi-agent workflows end-to-end) | 단일 LLM을 외부 도구/데이터에 연결 (Connect single LLM to external tools/data) |
| ... | | |
실제 사례
MCP 사용 시:
- Claude 챗봇에 웹 검색 기능 추가하기
- LLM을 회사 데이터베이스에 연결하기
- 여러 데이터 소스가 필요한 리서치 어시스턴트 구축하기
Orra 사용 시:
- 사용자 지정 중단/재시도 로직이나 상태 관리를 작성하지 않고 사기 탐지 에이전트 파이프라인 조정하기
- 실패 복구 또는 에스컬레이션 인프라를 구현하지 않고 사고 대응 에이전트 워크플로우 구축하기
- 보상 로직이나 트랜잭션 조정을 구축하지 않고 이커머스 에이전트 워크플로우 생성하기
함께 작동할 수 있을까요?
네! MCP는 "시스템에 어떻게 연결할 것인가"를 처리하고, orra는 "복잡한 워크플로우를 어떻게 조정할 것인가"를 처리합니다. 개별 에이전트의 기능(capabilities)을 노출하기 위해 MCP를 사용한 다음, 프로덕션 워크플로우에서 해당 에이전트들을 오케스트레이션(orchestrate)하기 위해 orra를 사용할 수 있습니다.
가이드 (Guides)
예제 살펴보기 (Explore Examples)
문서 (Docs)
셀프 호스팅 및 온프레미스 배포 (Self Hosting & On-premises Deployment)
플랜 엔진 실행 (Running Plan Engine)
orra 플랜 엔진(Plan Engine)은 쉬운 배포를 위해 Dockerfile로 패키징되어 있습니다:
- 로컬 개발 (Local Development): Docker 또는 Docker Compose를 사용하여 단일 인스턴스로 실행
- 온프레미스 배포 (On-premises Deployment): 선호하는 오케스트레이션 (Orchestration) 시스템을 사용하여 자체 인프라에 배포
- 클라우드 서비스 (Cloud Service): Digital Ocean의 App Platform 또는 모든 Kubernetes 환경과 같은 관리형 컨테이너 서비스에서 실행
셀프 호스팅 모델 사용 (원격 또는 온프레미스)
플랜 엔진 (Plan Engine)은 셀프 호스팅되는 오픈 소스 모델을 완벽하게 지원합니다:
- 추론 (Reasoning): 온프레미스를 포함하여 선호하는 모델 서빙 (Model Serving) 솔루션을 사용하여
deepseek-r1 또는 qwq-32b를 배포
- 임베딩 (Embeddings): 완전한 제어를 위해
jina-embeddings-v2-small-en을 셀프 호스팅
중요: 사용 중인 모델 서빙 솔루션은 반드시 **OpenAI 호환 API (OpenAI-compatible API)**를 노출해야 합니다. vLLM, LMStudio, OpenAI 호환 모드를 지원하는 Ollama 또는 Replicate와 같은 솔루션 모두 매우 잘 작동합니다.
→ 전체 모델 설정 가이드 (Complete Model Configuration Guide)
데이터 저장 (Data Storage)
플랜 엔진 (Plan Engine)은 모든 상태를 유지하기 위해 임베디드 데이터베이스인 BadgerDB를 사용하며, 운영 정보는 orra CLI를 사용하여 쿼리할 수 있습니다.
프로덕션 환경에서 orra의 플랜 엔진을 호스팅하거나 실행하는 데 도움이 필요하시면 오피스 아워 슬롯을 예약(Book an office hours slot)하세요.
지원 (Support)
도움이 필요하신가요? 저희가 지원해 드립니다:
텔레메트리 (Telemetry)
수집되는 정보와 거부(Opt-out) 방법은 telemetry.md를 참조하세요.
라이선스 (License)
Orra는 MPL-2.0 라이선스를 따릅니다.
