<p align="center"> <img src="docs/public/logo.png" alt="Orloj" width="200" /> </p>

에이전트(Agents)는 인프라입니다.

Orloj는 에이전트 시스템을 위한 풀스택(full stack)입니다.

하나의 선언적 스택(declarative stack)을 통해 멀티 에이전트 시스템(multi-agent systems)을 구축, 실행, 관리 및 관찰하십시오: 에이전트(agents), 도구(tools), 모델(models), 메모리(memory), 스케줄(schedules), 웹훅(webhooks), 승인(approvals), 정책(policies), 워커(workers), 트레이스(traces), 메트릭(metrics) 및 배포 프리미티브(deployment primitives).

Quickstart | Docs | Stack | How It Works | Screenshots

상태(Status): Orloj는 활발히 개발 중입니다. API 및 리소스 스키마(resource schemas)는 1.0 버전 이전에 변경될 수 있습니다.

Orloj란 무엇인가?

Orloj는 에이전트 시스템(agentic systems)을 개발하고 운영하기 위한 오픈 소스 풀스택(full stack)입니다.

에이전트 시스템은 더 이상 단순한 프롬프트(prompt)와 루프(loop)가 아닙니다. 모델 라우팅(model routing), 도구 권한(tool permissions), 자격 증명(credentials), 메모리(memory), 재시도(retries), 인간의 승인(human approvals), 스케줄(schedules), 웹훅(webhooks), 워커(workers), 트레이스(traces), 로그(logs), 메트릭(metrics) 및 배포 토폴로지(deployment topology)를 갖추고 있습니다. Orloj는 인프라 플랫폼이 서비스를 다루는 방식과 동일하게 이러한 요소들을 다룹니다: 즉, 원하는 상태(desired state), 상태(status), 컨트롤러(controllers), 임대(leases), 워커(workers), 런타임 정책(runtime policy) 및 운영 가시성(operational visibility)을 가진 버전 관리되는 리소스(versioned resources)로 취급합니다.

에이전트가 서비스라면	Orloj는 에이전트에게 매니페스트(manifests), 런타임 경계(runtime bounds), 자격 증명(credentials), 라우팅(routing), 관찰성(observability) 및 라이프사이클 관리(lifecycle management)를 제공합니다.
...

Orloj 에이전트 스택 (The Orloj Agent Stack)

Orloj는 단일 런타임 구성 요소가 아닙니다. Orloj는 팀이 에이전트 시스템을 개발, 실행, 관리 및 관찰하는 데 필요한 계층들을 아우릅니다.

스택 계층 (Stack Layer)	Orloj가 제공하는 것
인터페이스 (Interfaces)	YAML 매니페스트 (manifests), orlojctl, REST API, SDK 및 웹 콘솔.
...

스택 작동 방식 (How The Stack Operates)

선언 (Declare): 에이전트 (agents), 시스템 (systems), 도구 (tools), 모델 엔드포인트 (model endpoints), 메모리 (memory), 작업 (tasks) 및 정책 (policy)을 위한 YAML 리소스를 작성합니다.	조정 (Reconcile): 컨트롤러 (Controllers)가 리소스를 검증하고, 상태를 업데이트하며, MCP 도구를 탐색하고, 스케줄을 관리하며, 상태를 전진시킵니다.	스케줄링 (Schedule): 작업 (Tasks)은 에이전트 시스템 (AgentSystem)을 대상으로 하며, 용량(capacity)과 요구 사항에 따라 워커 (workers)에게 할당됩니다.
...

다음과 같은 경우 Orloj가 적합합니다 (Orloj Is Right For You If)

| 에이전트 데모 단계에서 소유자(owners), 정책(policies), 재시도(retries), 자격 증명(credentials), 그리고 트레이스(traces)가 필요한 시스템 단계로 넘어가고 있는 경우. |
| ... |

Orloj가 해결하는 문제 (Problems Orloj Solves)

Orloj가 없는 경우	Orloj가 있는 경우
에이전트 스크립트, 프롬프트(prompts), 도구 설정(tool configs), 자격 증명(credentials)이 여러 저장소(repos)와 머신(machines)에 걸쳐 파편화됩니다.	에이전트(Agents), 도구(tools), 모델(models), 메모리(memory), 트리거(triggers), 워커(workers), 그리고 정책(policy)이 리소스(resources)로 선언되며 하나의 API를 통해 적용됩니다.
...

스택 구성 요소 (What Is In The Stack)

계층 (Layer)	리소스 및 런타임 동작 (Resources and Runtime Behavior)
Agents	Agent 리소스는 프롬프트(prompts), 모델 참조(model refs), 폴백 모델(fallback models), 도구(tools), 역할(roles), 메모리 액세스(memory access), 실행 계약(execution contracts), 그리고 경계(bounds)를 정의합니다.
...

예시: 코드로서의 에이전트 시스템 (Example: An Agent System As Code)

에이전트 정의하기:

apiVersion: orloj.dev/v1
kind: Agent
metadata:
...

모델 엔드포인트(model endpoint)에 바인딩하기:

apiVersion: orloj.dev/v1
kind: ModelEndpoint
metadata:
...

에이전트를 그래프(graph)로 연결하기:

apiVersion: orloj.dev/v1
kind: AgentSystem
metadata:
...

태스크(task)로 실행하기:

apiVersion: orloj.dev/v1
kind: Task
metadata
...

런타임에 내장된 거버넌스 (Governance Built Into The Runtime)

Orloj에서의 거버넌스 (Governance)는 단순한 문서상의 관례가 아닙니다. 이는 작업이 실행되는 동안 실제로 평가됩니다.

AgentPolicy	허용된 모델, 차단된 도구 (tools), 토큰 예산 (token budget), 자식 깊이 (child depth), 그리고 자식 태스크 생성을 제한합니다.
...
권한이 없는 작업은 실패 처리되어 차단되며(fail closed), 태스크 트레이스 (task trace)에 나타납니다.

작동 방식 (How It Works)

구성 요소 (Component)	책임 (Responsibility)
orlojd	REST API, 웹 콘솔 (web console), 리소스 저장소 (resource stores), watch/event 엔드포인트, 컨트롤러 (controllers), 스케줄러 (schedulers), 그리고 선택 사항인 임베디드 워커 (embedded worker)를 실행합니다.
...

스크린샷 (Screenshots)

오퍼레이터 대시보드 (Operator Dashboard)

시스템 상태와 활성 워크로드 (active workload)를 한눈에 확인합니다.

시스템 토폴로지 (System Topology)

에이전트들을 연결하는 그래프를 검사합니다.

태스크 그래프 (Task Graph)

노드 레벨 (node-level)의 실행 진행 상황을 추적합니다.

트레이스 및 로그 (Trace And Logs)

모델 호출 (model calls), 도구 호출 (tool calls), 지연 시간 (latency), 오류 (errors), 그리고 출력을 디버깅합니다.

퀵스타트 (Quickstart)

CLI를 설치합니다:

brew tap OrlojHQ/orloj
brew install orlojctl

또는 바이너리를 설치합니다:

curl -sSfL https://raw.githubusercontent.com/OrlojHQ/orloj/main/scripts/install.sh | sh

임베디드 워커 (embedded worker)와 인메모리 상태 (in-memory state)로 Orloj를 시작합니다:

orlojd --storage-backend=memory --embedded-worker

파이프라인 (pipeline) 스캐폴딩 (Scaffold):

orlojctl init demo

스캐폴딩에서 요구하는 모델 시크릿 (model secret)을 생성합니다:

orlojctl create secret openai-api-key --from-literal value=sk-your-key-here

리소스(resources)를 적용하고 샘플 태스크(sample task)를 포함합니다:

orlojctl apply -f demo/ --run

자신만의 입력값으로 새로운 태스크를 실행합니다:

orlojctl run --system demo-system topic="The future of open source AI"

실행 내용을 검사합니다:

orlojctl get tasks
orlojctl trace task <task-name>
orlojctl logs task/<task-name>

http://127.0.0.1:8080/에서 콘솔을 엽니다.

프로덕션 형태 (Production Shape)

로컬 개발(Local development)은 하나의 프로세스에서 실행될 수 있습니다. 프로덕션(Production)에서는 Orloj 서버와 워커(workers)를 분리할 수 있습니다:

Local	orlojd --storage-backend=memory --embedded-worker
...

Postgres 예제를 사용하기 전에 ORLOJ_POSTGRES_DSN을 설정하십시오. NATS가 기본 로컬 주소에서 실행되지 않는 경우 ORLOJ_NATS_URL 또는 ORLOJ_AGENT_MESSAGE_NATS_URL을 설정하십시오.

orlojd \
  --storage-backend=postgres \
  --task-execution-mode=message-driven \
...

orlojworker \
  --storage-backend=postgres \
  --task-execution-mode=message-driven \
...

Orloj가 아닌 것 (What Orloj Is Not)

에이전트 프레임워크가 아님 (Not an agent framework)	Orloj는 프롬프트 스타일(prompt style)이나 추론 패턴(reasoning pattern)을 강제하지 않습니다. Orloj는 에이전트 주변의 스택을 인프라 리소스(infrastructure resources)로서 운영합니다.
...

문서 및 예제 (Docs And Examples)

5분 튜토리얼	스캐폴딩 (Scaffold)을 수행하고, 모델 키를 설정하며, 첫 번째 에이전트 시스템을 실행합니다.
...

SDKs (SDK)

REST API를 직접 사용하거나, orlojctl을 통해 조작하거나, 공식 SDK를 사용하여 애플리케이션 코드에서 Orloj을 호출할 수 있습니다.

언어 (Language)	설치 (Install)	링크 (Links)
Python	pip install orloj-sdk	PyPI
TypeScript	npm install orloj	npm

Contributing (기여)

환경 설정, 테스트 매트릭스 (test matrix), 그리고 PR (Pull Request) 라이프사이클에 대한 자세한 내용은 CONTRIBUTING.md를 참조하세요.

도움이 될 만한 시작 지점:

• Good first issue (처음 시작하기 좋은 이슈)
• Help wanted (도움이 필요한 이슈)
• Use-case contribution guide (유스케이스 기여 가이드)

License (라이선스)

Apache License 2.0. LICENSE 및 NOTICE를 참조하세요.