Division Swarm

자율 다중 에이전트 시스템을 위한 운영체제입니다.

Swarm은 LLM 에이전트의 플릿(fleets)을 내구성 있고 상태를 유지하는 시스템으로 실행합니다. 사용자는 YAML 파일에 이를 선언하고, 결정론적 엔진(deterministic engine)이 이를 실행하며, 상태 관리, 라우팅, 격리, 비용 책정, 복구 기능을 담당합니다. LLM은 절대 시스템을 직접 구동하지 않습니다: 에이전트들은 제한된 세션(scoped sessions)에서 추론하고 이벤트를 방출하며, 결정론적 코드(deterministic code), 모델 자체가 아닌 것이 각 결과가 무엇을 변경할지 결정합니다.

단순히 다음에 어떤 에이전트를 실행할지 결정하는 오케스트레이터(orchestrator) 이상의 역할을 합니다. Swarm은 그 주변으로 시스템 전체를 구동합니다. 작업(Work)은 선언된 상태 기계(state machine)를 통해 이동하는 엔티티(개별 주문, 티켓, 후보 비즈니스 등)로 모델링됩니다: 런타임(runtime)이 한 번에 수백 개의 작업을 예약하고, 이들을 격리하며, 사용 비용을 측정하고, 상태를 영속화하며, 타이머나 사람이 기다리게 하여 크래시 후에도 나중에 재개합니다. 모든 실행은 로그로부터 재생되거나 포크(forked)될 수 있습니다. 결정론적 라우팅은 그 일부일 뿐이며, 나머지는 운영체제입니다.

단일 Go 바이너리이며, 기본적으로 local/dev용 SQLite를 사용하고 프로덕션 환경에서는 Postgres를 선택할 수 있습니다. 오늘날 여러 LLM 백엔드가 제공됩니다: Anthropic API, Claude CLI, OpenAI 호환 Chat Completions 엔드포인트, 네이티브 OpenAI 응답, 그리고 자격 증명 없는 결정론적 Python 모의 실행 시간(mock runtime)입니다.

장기 방향: 전체 부서(엔지니어링, 지원, 운영)가 자율적인 Swarm 흐름으로 작동합니다. 판단이 필요한 곳에만 인간이 개입하며, 나머지 모든 곳에는 에이전트와 결정론적 시스템 노드가 배치됩니다.

설계 원칙 (Design positions)

Swarm은 소수의 확고한 선택을 하고 이를 고수합니다.

• 작업(Work)은 지속 가능한 상태 기계(durable state machine)입니다. 모든 작업 단위는 보호된 전이(guarded transitions)를 통해 선언된 상태들을 거치는 개체입니다. 런타임은 상태를 영속화하므로, 상태가 충돌에도 살아남고 수백 개의 개체가 간섭 없이 독립적으로 진행됩니다.

• 제어 루프는 결정론적입니다. 어떤 LLM도 다음에 무엇이 실행될지 결정하지 않습니다. 라우팅은 선언된 구독(subscriptions)에서 파생되며, 모든 이벤트는 고정된 핸들러 파이프라인을 거칩니다. 조건문에는 CEL을 사용합니다: 강력하게 타입 지정되고, 튜링 완전하지 않으며, 환각 현상이 없는 라우터입니다.

• 모든 전이는 하나의 트랜잭션입니다. 가드(Guard), 축적(accumulate), 계산(compute), 커밋(commit), 방출(emit): 모두 성공하거나 아니면 아무것도 하지 않습니다. 핸들러 도중 충돌이 발생해도 부분적인 상태가 남지 않습니다.

• 흐름(Flows)은 조합 가능한 단위입니다. 흐름 패키지는 자신의 식별자, 상태 기계, 시스템 노드, 이벤트, 에이전트, 도구 및 정책을 선언합니다. 타입 지정된 입력 및 출력 핀은 구성 과정을 리팩토링이 아닌 기계적인 과정으로 만듭니다. 전문화된 흐름을 만들고 다른 Swarm 프로젝트에서 가져와 사용할 수 있습니다.

• 실행은 재생 가능합니다(replayable). 모든 이벤트와 모든 상태 변화는 영구 저장됩니다(persisted). 어떤 실행이든 턴 단위로 재구성되거나, 처음부터 끝까지 감사(audited)할 수 있고, 충돌 후 마지막 일관된 체크포인트에서 다시 시작할 수 있습니다. 감사 기능은 기본적으로 내장되어 있습니다(native).

• 실행은 포크 가능합니다(forkable). 어떤 실행이든 그 역사상의 어느 지점에서 다른 정책 값(policy value), 수정된 에이전트 의도(agent intent), 또는 완전히 새로운 계약 번들(contract bundle)과 같은 반사실적 시나리오를 적용하여 재실행하고, 결과를 원래 것과 비교할 수 있습니다. 지난주에 실패했던 실행을 이번 주에 고친 계약에 대해 다시 재생할 수 있습니다. 흐름(flow)을 반복 개선하는 비용이 실행을 포크하는 비용으로 떨어지므로, 지속적인 개선이 배포-관찰 주기(deploy-and-watch cycle)가 아닌 일반적인 엔지니어링 루프가 됩니다.

• 인간이 일급 행위자(first-class actor)로 참여합니다. 승인, 거부, 연기는 나머지 런타임과 동일한 이벤트 모델을 사용하여 영구 메일박스(durable mailbox)를 통해 흐릅니다. 보류 중인 결정은 단지 핸들러가 기다리는 또 다른 이벤트일 뿐입니다: 이 경우 인간의 핸들러가 됩니다. 자율성은 스위치가 아니라 다이얼입니다.

• 명세 기반이며 에이전트 작성에 적합합니다(agentic authoring). 플랫폼 명세는 단일 머신 판독 가능 YAML 파일이며, 정적 분석기(static analyzer)의 오류는 체크 ID와 정확한 필드 경로를 인용하고 LLM이 직접 처리할 수 있으며, 200개 이상의 검증 컨포먼스 번들(verifying conformance bundles)은 따라 할 작업 패턴을 제공합니다. 에이전트 작성자용를 참조하십시오.

트레이드오프는 이겁니다: Swarm 흐름은 런타임에서 LLM에 의해 재배선될 수 없습니다. 그 경직성이 바로 핵심입니다.

사용해보기(Try it)

# 플랫폼 명세에 대해 정적 분석기를 실행합니다
swarm verify ./my-flow

...

흐름은 계약입니다(A flow is a contract)

핸들러는 YAML로 선언됩니다. 엔진이 이를 읽고 실행합니다. 제품별 코드 후크가 없습니다.

# nodes.yaml
ticket-orchestrator:
  event_handlers:
...

실행 순서는 의존성 그래프(dependency graph)에 의해 고정됩니다:

guard ──▶ accumulate ──▶ compute ──▶ {advances_to, sets_gate, data_accumulation} ──▶ emit ──▶ action
│
atomic commit

조건문은 CEL을 사용하며, 이는 강력한 타입(strongly typed)을 가지지만 튜링 완전하지 않습니다 (non-Turing-complete).

빠른 시작 (Quickstart)

바이너리를 빌드한 후, docs Quickstart를 따라가면 끝까지 실행할 수 있는 4개 파일 흐름을 구성할 수 있습니다:

git clone https://github.com/division-sh/swarm && cd swarm
go build ./cmd/swarm

단순 로컬 실행은 데이터베이스 서비스가 필요하지 않습니다 (기본값은 .swarm/stores/dev.db의 SQLite). 또한 LLM 자격 증명(credential)도 필요 없습니다 (에이전트가 없는 흐름도 별도의 설정 없이 부팅됩니다). Postgres, 에이전트 작업 공간 이미지, 그리고 LLM 백엔드 설정을 보려면 설치(Installation)와 구성(Configuration)를 참조하십시오. 로컬 배포 설정을 위해서는 비(非)비밀 참조 파일인 swarm.example.yaml을 사용하십시오. Swarm은 현재 디렉터리의 .swarm/swarm.yaml 파일을 읽거나, 해당 파일이 없을 경우 내장된 기본값을 사용합니다. --config <파일> 옵션은 이 선택을 완전히 대체합니다. SWARM_CONFIG 환경 변수는 --config가 없을 때 동일한 파일을 선택하며, 두 가지 모두 설정되었을 때는 --config가 우선합니다. Swarm은 루트의 swarm.yaml이나 사용자 전역 구성 파일(user-global config files)을 검색하지 않으며, 리포지토리의 .env 파일도 로드하지 않습니다. 계약 자격 증명(contract credentials)의 경우 swarm secrets set을 사용하고 swarm secrets check으로 유효성을 검사하십시오.

로컬 웹훅 개발을 위해 swarm serve --dev --expose는 임시 공개 콜백 URL을 소유하며, 구성된 채널 바인딩에 의해 선언된 등록 정보를 조정합니다. 관리형 노출(Managed exposure)에는 cloudflared 2021.7.0 이상 버전이 필요합니다 (brew install cloudflared). 퀵-터널(Quick-tunnel) URL은 일시적이며 가용성 SLA가 없습니다. 대신 외부에서 관리하는 HTTPS 오리진을 사용하려면 --public-webhook-base-url과 명시적인 루프백 --public-webhook-listen 두 가지를 모두 제공해야 합니다. 이 명시적 외부 오리진 모드는 개발용 serve와 일반 유지(plain retained) serve 모두에서 작동하며, 관리형 퀵 터널만 개발 전용입니다. 공개 리스너는 /webhooks/*만을 노출하고 API, MCP, health 또는 기타 제어 평면(control-plane) 경로를 절대 노출하지 않습니다.

자격 증명 없는 시나리오(credentialless scenarios)의 경우 swarm test를 사용하고 각 에이전트에게 contracts-root-relative Python 성능을 제공합니다. 이 명령어는 새로운 사설 런타임(private runtime)을 소유하며, 실행 중인 서버나 배포 구성이 필요하지 않습니다. swarm serve와 swarm serve --dev는 더블(doubles)이 존재하더라도 항상 라이브 실행을 선택합니다:

# agents.yaml
reviewer:
  id: reviewer
...

모듈은 handle(input)을 내보내고, text, calls 또는 둘 다를 포함하는 하나의 JSON 호환 객체를 반환합니다. 목(Mock) 턴은 일반 세션, 도구(tools), 라우팅, 영속성(persistence), 그리고 리드백(readbacks)을 사용하지만, 런타임은 실행 전에 모든 외부 효과를 거부합니다. 컴파일된 생성(generation)은 모듈 바이트와 다이제스트(digest)를 캡처하며, 실행 중에는 소스 파일을 다시 읽지 않습니다.

핵심 개념 (Core concepts)

Handler는 이벤트에 연결되는 실행 단위입니다. guard, accumulate, advances_to, sets_gate, emit, action으로 구성됩니다.
Event는 events.yaml에 선언된 페이로드 스키마를 가진 타입 지정 메시지입니다.
Gate는 handler가 설정하는 이름 있는 불리언(boolean) 값이며, 다른 handler들은 이를 guard할 수 있습니다.
...
권위 있는 참조: platform-spec.yaml. 생성되는 공개 API 아티팩트는 openrpc.json입니다.

CLI

swarm CLI는 v1 RPC를 기반으로 하는 클라이언트이며, 전체 명령어 참조는 docs.division.sh/reference/cli에서 확인할 수 있습니다.

아키텍처

flowchart TB
    ING["ingress: RPC / API / MCP"] -->|events| BUS(["event bus"]) 
BUS -->|"routed by subscription"| SN["system nodes<br/>deterministic, own state"] 
...

시스템 노드만이 상태를 쓰기(write)하며, 이를 하나의 트랜잭션으로 수행합니다. 에이전트들은 오직 노드가 처리하는 이벤트를 방출함으로써 간접적으로 스토어에 도달합니다. 루프 아래에는 설계상의 위치들을 강제할 수 있게 만드는 기본 원시 요소들(primitives)이 있습니다:

• 계약(contracts)을 위한 정적 분석기(static analyzer). 이벤트가 발생하기 전에 모든 계약은 수십 가지 구조적 검사를 거칩니다: 상태 도달 가능성(state reachability), 페이로드 완전성(payload completeness), 에이전트 라우팅(agent routing), 타이머 수명 주기(timer lifecycle), CEL 구문 분석(CEL parse), 그리고 에이전트 의도 유효성 검사(agent-intent validation). 부팅된 번들(bundle)은 이 분석을 통과했음을 의미합니다.
• 2계층 이벤트 소스 기반 영속성(event-sourced persistence). 모든 이벤트는 선택된 런타임 스토어에 기록되며, 모든 엔티티 상태 변경(entity state mutation)은 전후 차이점(before/after diffs)이 포함된 별도의 변경 로그(mutation log)에 기록됩니다. 로컬/개발 환경 실행 시 기본적으로 SQLite를 사용하며, Postgres는 명시적인 외부/운영 환경 옵션으로 유지됩니다. '재생(Replay)'은 "무슨 일이 일어났는지 보여준다"고 말하고, 변경 로그는 "정확히 무엇이 바뀌었는지 보여준다"고 합니다. 누산기 프로젝션(Accumulator projections)은 스트림으로부터 읽기 모델(read-models)을 계산하여, 핸들러와 외부 리더가 원시 로그를 스캔하지 않고도 집계된 상태를 쿼리할 수 있게 합니다.
• 역할 기반 라우팅 권한(Role-based routing authority). 에이전트 격리는 엔티티 상태별로 어떤 에이전트 역할이 다른 어떤 역할을 호출할 수 있는지 결정하는 권한 계층(authority layer)에 의해 강제됩니다. "모든 에이전트가 모든 에이전트와 대화할 수 있다"는 것은 런타임이 제공하는 기본 기능이 아닙니다.
• 신뢰성 원시 요소(Reliability primitives). 전달할 수 없는 이벤트는 지수 백오프(exponential backoff)를 사용하여 재시도되며, 소진되면 데드 레터 스토어(dead-letter store)에 저장됩니다. 데드 레터는 인덱싱되고 재생이 가능합니다.
• 실시간 예산 추적(Live budget tracking). 토큰 사용량은 엔티티별 및 액터별로 실시간으로 추적됩니다. 선언된 임계값(thresholds)은 스로틀(throttle) 상태와 긴급(emergency) 상태로 격상되며, 런타임이 긴급 상태에 도달하면 사용자에게 메일함 항목(mailbox item)이 전송됩니다.
• 포괄적인 JSON-RPC API. 생성된 메서드 카탈로그는 실행(runs), 이벤트, 에이전트, 대화(conversations), 엔티티, 메일함, 런타임 제어 등을 아우르며, 실시간 추적(live traces), 이벤트 스트림, 로그 테일, 건강 상태에 대한 WebSocket 구독 기능도 제공합니다. 이 표면은 기계가 읽을 수 있는 OpenRPC 문서로 게시되므로, 클라이언트를 직접 코딩하는 대신 생성할 수 있습니다. swarm CLI는 그러한 클라이언트 중 하나이며, 누구나 자신만의 것을 구축할 수 있습니다.
• MCP 게이트웨이. Swarm은 모델 컨텍스트 프로토콜(Model Context Protocol)을 노출하고 소비합니다.

외부 도구들은 MCP 위에서 런타임을 구동할 수 있으며, 에이전트들은 코드 변경 없이 상위 MCP 서버로부터 도구 정의를 가져옵니다.

Swarm 사용 시점

Swarm은 의견이 강합니다(opinionated). 작업은 내구성 있는 상태 기계(durable state machine)이며, 라우팅은 결정론적(deterministic)이고, 영속성(persistence), 격리(isolation), 비용 제어는 추가 기능이 아니라 기반 구조입니다. 이러한 깊이는 재현성(reproducibility), 충돌 복구(crash recovery), 감사(audit)를 제공하며, 런타임 시작 전에 YAML과 정적 분석기(static-analyzer) 통과가 필요합니다. 이는 일부 워크로드에는 적절한 트레이드오프이지만 다른 워크로드에는 부적절할 수 있습니다.

정적 분석기가 미완성된 계약에 대해 부팅을 거부하는 것은 프로덕션 환경에서는 기능이지만 탐색(exploration) 단계에서는 마찰입니다. 이에 맞춰 계획하십시오.

적합한 경우