🪡 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)
• 계획 엔진 작동 방식 (How The Plan Engine Works)
• Orra vs 에이전트 프레임워크 및 워크플로 엔진 (Orra vs Agent Frameworks & Workflow Engines)
• Orra 계획 엔진 vs MCP (Orra Plan Engine vs MCP)
• 가이드 (Guides)
• 예제 살펴보기 (Explore Examples)
• 문서 (Docs)
• 셀프 호스팅 및 온프레미스 배포 (Self Hosting & On-premises Deployment)
• 지원 (Support)
• 텔레메트리 (Telemetry)
• 라이선스 (License)

설치 (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)

# 계획 엔진 (Plan Engine)으로 액션 실행
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 Plan Engine 대 MCP

실제 사례

MCP 사용 시:

• Claude 챗봇에 웹 검색 기능 추가하기
• LLM을 회사 데이터베이스에 연결하기
• 여러 데이터 소스가 필요한 리서치 어시스턴트 구축하기

Orra 사용 시:

• 사용자 지정 중단/재시도 로직이나 상태 관리를 작성하지 않고 사기 탐지 에이전트 파이프라인 조정하기
• 실패 복구 또는 에스컬레이션 인프라를 구현하지 않고 사고 대응 에이전트 워크플로우 구축하기
• 보상 로직이나 트랜잭션 조정을 구축하지 않고 이커머스 에이전트 워크플로우 생성하기

함께 작동할 수 있을까요?

네! MCP는 "시스템에 어떻게 연결할 것인가"를 처리하고, orra는 "복잡한 워크플로우를 어떻게 조정할 것인가"를 처리합니다. 개별 에이전트의 기능(capabilities)을 노출하기 위해 MCP를 사용한 다음, 프로덕션 워크플로우에서 해당 에이전트들을 오케스트레이션(orchestrate)하기 위해 orra를 사용할 수 있습니다.

가이드 (Guides)

• 취약한 상태에서 프로덕션 준비가 된 멀티 에이전트 앱으로 (From Fragile to Production-Ready Multi-Agent App)
• 취약한 상태에서 프로덕션 준비가 된 멀티 에이전트 앱으로 (Cloudflare Agents 포함) (From Fragile to Production-Ready Multi-Agent App (with Cloudflare Agents))

예제 살펴보기 (Explore Examples)

• 🛒 이커머스 AI 어시스턴트 (JavaScript) (E-commerce AI Assistant (JavaScript)) - 배송 전문 에이전트가 포함된 이커머스 고객 서비스
• 👻 고스트라이터 (Python) (Ghostwriters (Python)) - CrewAI와 함께 orra를 사용하는 방법을 보여주는 콘텐츠 생성 예제
• 📣 서비스로서의 Echo 도구 (JavaScript) (Echo Tools as Service (JavaScript)) - JS를 사용하여 핵심 개념을 보여주는 간단한 예제
• 📣 서비스로서의 Echo 도구 (Python) (Echo Tools as Service (Python)) - Python을 사용하여 핵심 개념을 보여주는 간단한 예제

문서 (Docs)

• orra를 이용한 신속한 멀티 에이전트 앱 개발 (Rapid Multi-Agent App Development with orra)
• orra에서 에이전트란 무엇인가? (What is an Agent in orra?)
• orra를 이용한 액션 오케스트레이션 (Orchestrating Actions with orra)
• 웹후크를 이용한 모니터링 (Monitoring with Webhooks)
• 도메인 그라운딩 실행 (Domain Grounding Execution)
• 실행 계획 캐싱 (Execution Plan Caching)
• 핵심 주제 및 내부 구조 (Core Topics & Internals)
• orra 플랜 엔진을 위한 모델 구성 (Model Configuration for the orra Plan Engine)

셀프 호스팅 및 온프레미스 배포 (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)

도움이 필요하신가요? 저희가 지원해 드립니다:

• 이슈(Issue)를 생성하여 버그를 보고하거나 기능을 요청하세요
• 아이디어나 질문에 대해 토론(Discussion)을 시작하세요

텔레메트리 (Telemetry)

수집되는 정보와 거부(Opt-out) 방법은 telemetry.md를 참조하세요.

라이선스 (License)

Orra는 MPL-2.0 라이선스를 따릅니다.