Sprix SAGE Router (wang2122/sprix-sage-router) 딥다이브
— "혼자 갈까, 팀을 부를까, 넘길까"를 수식 하나로 판정하는 에이전트 라우터

1프로젝트 한 줄 요약

SAGE는 State-Aware Graph Exchange의 약자다. 이름의 "State-Aware(상태를 아는)"가 핵심이다. 보통의 에이전트 매칭은 작업이 시작되기 전에 "이 일에 누가 제일 잘 맞나"를 고른다. SAGE는 이미 45% 진행됐고, 계획 단계는 끝났고, 한 번 실패한 적 있는 상태에서 다시 판단한다.

이 차이가 왜 중요하냐면, 진행률이 높을수록 담당자를 바꾸는 비용이 커지기 때문이다. 이미 쌓인 맥락(대화 기록·중간 산출물·시행착오)을 새 에이전트에게 완전히 옮길 수 없다면, 아무리 실력이 좋은 전문가라도 넘기는 게 손해일 수 있다. SAGE는 이 손실을 handoff_loss·switch_loss라는 이름의 페널티 항으로 수식에 직접 넣는다.

실제 코드는 놀랄 만큼 짧다. 에이전트 목록과 작업 요구사항을 넘기면 결정 객체 하나가 돌아온다.

from sprix_sage import Agent, ExecutionOutcome, Requirement, SAGERouter, Task

agents = [
    Agent("planner", {"planning": 0.92, "coding": 0.55}, cost=0.08, latency_ms=900),
    Agent("coder",   {"planning": 0.35, "coding": 0.96}, cost=0.12, latency_ms=1200),
]

task = Task(
    "build-feature",
    requirements=(
        Requirement("planning", 0.4),
        Requirement("coding", 0.6, depends_on=("planning",)),   # 의존 관계 = DAG
    ),
    value=1.0, budget=0.30, deadline_ms=4000,
    progress=0.35,        # ← 이미 35% 진행된 상태에서 판단
)

router = SAGERouter(agents, incumbent_id="planner")
decision = router.route(task)
print(decision.mode, decision.assignments, decision.topology)

저장소의 demo.py를 실제로 돌려 보면 다음이 나온다(직접 실행해 확인한 출력이다).

mode       : collaborate
agents     : incumbent-planner, security-reviewer
utility    : 0.616
p(success) : 0.814
cost       : 0.176
latency    : 1122 ms
assignments: {'planning': 'incumbent-planner', 'coding': 'security-reviewer',
              'security': 'security-reviewer'}
topology   : (('incumbent-planner', 'security-reviewer'),)
reason     : COLLABORATE via [incumbent-planner, security-reviewer]: ...
             estimated success=0.814, coverage=0.756; ...

주목할 부분은 reason 필드다. 이 라이브러리는 결정만 뱉지 않고 왜 그렇게 골랐는지를 사람이 읽을 문장으로 함께 돌려준다. 그리고 coding 요구사항이 code-specialist가 아니라 security-reviewer에게 갔다는 점도 흥미롭다 — 코딩 실력만 보면 전자가 0.97로 압도적이지만, 예산 0.30 안에서 보안까지 함께 커버하는 팀을 만들려면 후자를 넣는 편이 전체 효용이 높다고 판단한 것이다.

2왜 지금 주목받는가

2026년의 멀티에이전트 도구는 대부분 연결에 집중해 있다. MCP는 도구를 붙이고, A2A는 에이전트끼리 말을 트게 하고, 오케스트레이터는 순서를 짠다. 그런데 실제로 굴려 보면 다음 질문이 남는다 — "에이전트를 더 붙이면 더 좋아지긴 하는데, 왜 비용이 세 배가 되지?"

① 남들이 규칙으로 때우던 자리에 하나의 목적함수를 놓았다

보통의 프레임워크에서 "혼자 할지 / 넘길지"는 프롬프트나 if 문으로 흩어져 있다. SAGE는 세 모드를 같은 저울에 올린다. 담당자가 그대로 하는 것도 하나의 후보이고, 팀을 꾸리는 것도, 넘기는 것도 후보다. 전부 같은 식으로 점수를 매겨 최대값을 고른다.

가중치를 보면 설계자의 관점이 드러난다. 인수인계 손실(0.22)이 비용(0.18)보다 무겁다. "담당자를 바꾸는 건 돈보다 비싸다"는 판단이 숫자에 박혀 있는 셈이다.

② "잘하는 사람"이 아니라 "빈칸을 채우는 사람"을 뽑는다

팀을 만들 때 흔한 실수가 개별 점수 높은 에이전트만 모으는 것이다. 코딩 0.97짜리 셋을 모아도 보안 요구사항은 여전히 빈칸이다. SAGE는 중복도(redundancy)를 코사인 유사도로 계산해 감점하고, 요구사항별 커버리지를 따로 본다. 게다가 bottleneck(가장 약한 요구사항의 충족률)을 별도 특징으로 두어, 평균은 좋은데 한 항목이 치명적으로 비어 있는 팀을 걸러낸다.

③ 신뢰도를 "한 개의 별점"으로 두지 않는다

대부분의 에이전트 마켓 구상은 평판을 숫자 하나로 관리한다. SAGE는 전역 신뢰도와 요구사항별 신뢰도를 따로 학습하고 35:65로 섞는다. 코딩을 열 번 잘했다고 보안까지 잘한다고 보지 않는다는 뜻이다. 테스트 파일에도 test_contextual_reliability_does_not_bleed_across_skills라는 이름으로 이 성질이 못 박혀 있다.

④ 자기 벤치마크를 자기가 채점하지 않는다

이게 이 저장소에서 가장 정직한 부분이다. benchmark.py는 SAGE의 예측 모델과 일부러 다르게 만든 외부 시뮬레이터를 쓴다. 숨은 실제 능력치는 광고된 능력치와 다르고, 품질 함수는 비선형이고, 실제 비용·지연은 견적과 어긋난다. README는 이전 버전이 "SAGE의 확률로 SAGE의 정답을 만드는 순환 평가"였다고 스스로 밝힌다.

직접 돌려 본 결과(python3 benchmark.py, 2,500개 작업 × 5개 시드, 약 2.8초)는 README 표와 정확히 일치했다.

여기서 읽어야 할 것은 "SAGE가 이겼다"가 아니라 마감 위반이 26.4% → 0%로 떨어진 부분이다. 품질 차이(0.507→0.634)는 시뮬레이터 설계에 크게 좌우되지만, 마감·예산을 구조적으로 못 어기게 만든 건 점수가 아니라 설계의 결과다. 반대로 온라인 SAGE는 예산을 0.329→0.434로 더 쓴다 — 저자는 이 트레이드오프를 숨기지 않고 표에 남겨 뒀다.

비교 대상들과의 위치

3기술 스택 전체 지도

이 저장소의 기술 스택 지도는 그리기가 민망할 만큼 단순하다. 그리고 그게 의도다.

런타임 — 서드파티 의존성 0개

pyproject.toml에 dependencies 항목 자체가 없다. NumPy도, scikit-learn도, PyTorch도 안 쓴다. 모듈 상단의 import는 이게 전부다.

from dataclasses import dataclass, field, replace
from enum import Enum
from itertools import combinations
import math
import random
from typing import Iterable, Mapping

모델링 층 — 8개의 불변 dataclass

전부 frozen=True이고 __post_init__에서 값 범위를 검증한다. 예를 들어 Requirement는 이름이 비었거나 가중치가 0 이하면 즉시 ValueError를 던진다. Task는 한술 더 떠 요구사항 의존 그래프에 순환이 있으면 생성 자체가 실패한다.

학습 층 — 두 종류의 "믿음"

BetaBelief.update()는 딱 두 줄이다 — alpha += weight × 점수, beta += weight × (1 − 점수). 베이즈 갱신을 이보다 짧게 쓰기 어렵다. uncertainty는 베타 분포의 표준편차 공식을 그대로 쓴다.

개발·배포 인프라

4아키텍처 심화 분석

전체 그림부터 보자. SAGE는 A2A 스택에서 검색과 실행 사이에 끼는 정책 층이다.

설계 패턴 ① 하드 제약과 소프트 점수를 절대 섞지 않는다

가장 많이 배울 만한 부분이다. 권한·예산·마감은 점수가 아니라 필터다. 아무리 예측 성공률이 높아도 권한이 없으면 순위에 들어오지도 못한다.

def _eligible(self, agent: Agent, task: Task, bid: Bid) -> bool:
    return (
        agent.availability > 0
        and task.required_permissions.issubset(agent.permissions)   # 권한: 부분집합
        and self._risk_adjusted_cost(agent.agent_id, bid) <= task.budget
        and self._risk_adjusted_latency(agent.agent_id, bid) <= task.deadline_ms
    )

그런데 여기에 함정이 하나 있다. 개별 에이전트가 예산을 통과해도 둘을 합치면 넘을 수 있다. 그래서 팀이 만들어진 뒤 한 번 더 검사한다.

@staticmethod
def _team_feasible(decision: RouteDecision, task: Task) -> bool:
    return decision.cost <= task.budget and decision.latency_ms <= task.deadline_ms

이 2차 검사는 DAG 스케줄링으로 계산한 임계 경로 지연을 쓴다. 각자 1,200ms짜리 두 명을 붙였다고 지연이 2,400ms가 되는 게 아니라, 의존 관계가 없으면 병렬로 도니까 1,200ms에 가깝다 — 그 계산을 마치고 나서 마감을 검사하는 것이다.

설계 패턴 ② 커버리지는 노이지-OR로 — "여럿이면 놓칠 확률이 준다"

코딩 능력 0.9인 사람과 0.7인 사람이 함께 있으면 커버리지는 1 − (0.1 × 0.3) = 0.97이다. 단순 평균(0.8)이나 최대값(0.9)과 다르다. 다만 이 식은 두 사람의 실패가 독립이라고 가정한다 — 실제로는 같은 이유로 함께 틀릴 수 있으므로, SAGE는 그 오차를 짝 시너지(synergy)와 중복도(redundancy) 특징으로 보정한다. ALGORITHM.md도 이것들을 "주장이 아니라 특징(features rather than claims)"이라고 조심스럽게 표현한다.

설계 패턴 ③ 신뢰도를 두 겹으로 쪼갠다

두 번째 줄이 특히 영리하다. 믿을 수 없는 에이전트가 "나 99% 자신 있어요"라고 해도, 그 자신감이 0.5(모름) 쪽으로 끌려간다. 신뢰(t)가 낮으면 자기 신고 값의 영향력이 자동으로 줄어드는 구조다. 세 번째 줄의 0.65 + 0.35t·0.70 + 0.30b̃도 마찬가지 — 계수 하한이 0이 아니라 0.65/0.70이라, 실적이 하나도 없는 신규 에이전트도 완전히 배제되지는 않는다(콜드 스타트 대응).

설계 패턴 ④ 팀 탐색은 빔 서치 — 욕심쟁이보다 넓게, 전수보다 싸게

가능한 팀 조합을 전부 세면 조합 폭발이다. 반대로 매번 제일 좋은 한 명씩만 붙이는 그리디는 "혼자는 별로지만 셋이 모이면 최고인 조합"을 못 찾는다. SAGE는 그 사이를 택했다.

frontier = [(incumbent,)]                     # 담당자 1명에서 출발
for _ in range(max_collaborators):            # 기본 2회
    expanded = {}
    for team in frontier:                     # 살아남은 팀 후보들
        for agent_id in pool:                 # 모든 동료를 하나씩 붙여 봄
            quoted = sum(비용 for 팀원 in 후보팀)
            if quoted > task.budget: continue # 예산 초과면 확장 자체를 포기
            expanded[frozenset(후보팀)] = self._evaluate(COLLABORATE, ...)
    ranked = sorted(expanded.values(), key=효용, reverse=True)
    frontier = [item.agents for item in ranked[:self.beam_width]]   # 상위 8개만 유지

복잡도는 동료 n명, 빔 폭 B, 협력자 상한 k, 요구사항 |R|에 대해 대략 O(B·k·n·(|R| + k²))다. ALGORITHM.md는 이게 근사라는 점을 분명히 한다 — "전체 목적함수가 열등모듈러(non-submodular)이므로 전역 최적을 주장하지 않는다."

설계 패턴 ⑤ 요구사항 DAG를 실제로 스케줄링한다

_schedule()은 운영체제 수업에 나오는 리스트 스케줄링을 그대로 한다. 위상 정렬로 순서를 정하고, 각 작업의 시작 시각을 "선행 작업이 끝난 시각"과 "그 에이전트가 비는 시각" 중 늦은 쪽으로 잡는다.

for item in self._topological_requirements(task, state):
    agent_id = assignments[item.name]
    dependency_ready = max((finish[name] for name in item.depends_on), default=0.0)
    start = max(dependency_ready, agent_ready[agent_id])       # 자원 제약 + 의존 제약
    duration = 위험보정지연(agent_id) * item.weight / total_weight
    finish[item.name] = start + duration
    agent_ready[agent_id] = finish[item.name]                  # 같은 사람 일은 직렬화
    for dependency in item.depends_on:
        if assignments.get(dependency) != agent_id:
            topology.add((assignments[dependency], agent_id))  # 다른 사람이면 통신선

마지막 두 줄이 재미있다. 의존 관계가 있는 두 요구사항이 서로 다른 에이전트에게 배정되면, 그 순간 통신 간선이 하나 생긴다. 즉 팀의 통신 구조가 사람이 그린 게 아니라 역할 배정에서 자동으로 유도된다. 그리고 간선 수만큼 지연에 조율 오버헤드가 곱해진다(latency *= 1 + coordination_overhead × 간선수) — "회의가 많아지면 느려진다"를 수식으로 옮긴 셈이다.

설계 패턴 ⑥ 증거의 등급을 나눠 학습한다

실행이 끝나면 record_outcome()으로 결과를 먹인다. 여기서 SAGE는 얼마나 확실한 증거인가에 따라 갱신 가중치를 다르게 준다.

팀 전체 결과 하나만 있을 때 모든 팀원에게 똑같이 만점을 주는 것이 흔한 실수다. SAGE는 그걸 "약한 증거"로 낮춰 잡는다. 짝 시너지 갱신은 한 발 더 나간다.

individual_mean = (개인점수_왼쪽 + 개인점수_오른쪽) / 2
pair_credit = clip(0.5 + overall - individual_mean)   # 개인 실력으로 설명되지 않는 '잔차'
pair_weight = 0.70

둘 다 원래 잘하는 사람이면 팀 성과가 좋아도 시너지 점수는 0.5(중립) 근처에 머문다. 개인 실력으로 설명되지 않는 초과분만 궁합으로 인정하는 방식이다. 다만 ALGORITHM.md는 이것도 "아직 인과적 공로 배분은 아니다"라고 선을 긋는다.

설계 패턴 ⑦ 견적을 믿되 검증한다

에이전트가 "0.1달러, 1초"라고 견적을 냈는데 실제로 0.2달러가 나왔다면? SAGE는 그 에이전트의 견적 신뢰도를 깎고, 다음부터 그 사람의 견적을 부풀려서 자격 심사한다.

def _risk_adjusted_cost(self, agent_id, bid):
    return bid.quoted_cost * (1.0 + 0.20 * (1.0 - self.cost_fidelity[agent_id].mean))

def _risk_adjusted_latency(self, agent_id, bid):
    agent = self.agents[agent_id]
    quote = bid.promised_latency_ms * (1.0 + 0.20 * (1.0 - self.latency_fidelity[agent_id].mean))
    return quote * (1.0 + 0.50 * agent.load) / max(agent.availability, 0.10)   # 부하·가용성 반영

지연 쪽에는 현재 부하까지 곱해진다. 부하 100%인 에이전트는 견적의 1.5배로 계산되어 마감 심사를 받는다. 현실의 큐잉 지연을 아주 단순하게 근사한 것이다.

설계 패턴 ⑧ 톰슨 샘플링을 "한 번만" 뽑는다

exploration=True로 켜면 신뢰도의 평균 대신 베타 분포에서 표본을 뽑아 쓴다(탐색). 그런데 여기 미묘한 버그 지점이 있다 — 후보를 비교할 때마다 새로 뽑으면, 같은 에이전트가 후보 A에서는 운 좋게 0.9, 후보 B에서는 0.3이 되어 비교 자체가 무의미해진다. SAGE는 라우팅 이벤트 하나마다 캐시를 비우고, 같은 믿음에 대해서는 한 번 뽑은 값을 재사용한다.

def _belief_value(self, key, belief):
    if not self.exploration:
        return belief.mean
    if key not in self._draw_cache:            # 이 라우팅 이벤트에서 처음이면
        self._draw_cache[key] = belief.draw(self.rng)   # 한 번만 뽑고
    return self._draw_cache[key]               # 이후엔 재사용 (일관된 비교)

5디렉토리 구조 해부

정직하게 말하면 이 저장소에는 해부할 디렉토리가 없다. 파일 15개, docs/assets/와 .github/ 말고는 전부 루트에 평평하게 놓여 있다.

그래서 진짜 해부 대상은 sprix_sage.py 안의 층 구조다. 749줄이 뚜렷한 5개 층으로 나뉜다.

공개 API는 딱 두 개다. route()와 record_outcome(). 나머지 16개 메서드는 전부 _로 시작하는 내부 함수다. 클래스 하나에 메서드 18개면 큰 편이지만, 공개 표면이 2개로 좁다는 점이 이 설계를 구해 준다 — 밖에서 볼 때는 "결정 요청 / 결과 보고" 두 동작밖에 없다.

테스트 12개가 곧 사양서다

테스트 이름만 읽어도 이 라이브러리가 무엇을 보장하려는지 다 나온다. 직접 실행해 보면 12개 전부 0.003초에 통과한다.

6학습 포인트

① 제약 최적화를 코드로 옮기는 법

"제약이 있는 최적화"를 배울 때 가장 헷갈리는 게 제약을 페널티로 넣을지, 필터로 넣을지다. SAGE는 이 둘을 명확히 갈랐다 — 어기면 안 되는 것은 필터(권한·예산·마감), 덜한 게 좋은 것은 페널티(비용·지연·위험). 실무에서 이 구분을 흐리면 "예산을 조금 넘겨도 성공률이 높으니까"라는 결정이 나오고, 그건 보통 사고로 이어진다.

② 베이즈 온라인 학습을 25줄로 구현하기

BetaBelief는 켤레 사전분포(conjugate prior)의 가장 깨끗한 예제다. 관측이 들어오면 α와 β에 더하기만 하면 사후분포가 나온다 — 적분도, 최적화도 없다. 여기에 불확실성까지 공짜로 딸려 온다(uncertainty 프로퍼티). 이 불확실성은 효용 함수에서 감점 항인 동시에 탐색 모드에서는 보너스 항으로 쓰인다.

③ "손으로 쓴 공식"을 "학습되는 모델"로 승격시키는 법

이 저장소에서 가장 실용적인 교훈일 수 있다. v0.1은 성공률을 손으로 쓴 공식으로 계산했다. v0.2는 그걸 로지스틱 회귀로 바꿨는데, 기존 공식의 계수를 초기 가중치로 넣었다.

bias: float = -1.15
weights = {
    "coverage": 2.35, "bottleneck": 1.35, "trust": 0.80, "synergy": 0.35,
    "redundancy": -0.45, "coordination_loss": -0.55,
    "handoff_loss": -0.70, "switch_loss": -0.55, "load": -0.35,
}

즉 사람이 만든 휴리스틱이 그대로 모델의 사전 지식이 된다. 데이터가 0개일 때는 예전 공식처럼 동작하고, 관측이 쌓일수록 데이터 쪽으로 서서히 옮겨 간다. 학습률도 0.08 / sqrt(1 + updates/50)로 감쇠시켜, 초반엔 빨리 배우고 나중엔 흔들리지 않게 했다. 규칙 기반 시스템을 ML로 마이그레이션할 때 그대로 훔쳐 쓸 만한 패턴이다.

④ DAG 스케줄링과 임계 경로

_schedule()이 하는 일은 프로젝트 관리에서 말하는 임계 경로(critical path) 계산과 같다. 위상 정렬, 자원 제약(같은 사람은 동시에 두 일 못 함), 의존 제약(선행 작업이 끝나야 시작)을 함께 다룬다. 운영체제나 컴파일러 수업에서 배운 개념이 에이전트 팀 편성에 그대로 적용되는 걸 볼 수 있는 흔치 않은 예제다.

⑤ 파이썬 dataclass로 "잘못된 상태를 만들 수 없게" 하기

frozen=True + __post_init__ 검증 조합은 그 자체로 좋은 파이썬 교재다. 특히 Task._validate_dag()는 DFS 색칠 기법으로 순환을 잡는다 — visiting(회색)과 visited(검정) 두 집합으로 재귀 중 다시 만난 노드를 순환으로 판정하는 교과서적 구현이다.

def visit(name):
    if name in visiting:                 # 아직 탐색 중인 노드를 다시 만남 = 순환
        raise ValueError("requirement dependencies must form a DAG")
    if name in visited: return           # 이미 끝난 가지는 재방문 안 함
    visiting.add(name)
    for dependency in graph[name]:
        visit(dependency)
    visiting.remove(name); visited.add(name)

⑥ 한계를 문서에 쓰는 기술

기술 외적이지만 중요한 학습 포인트다. ALGORITHM.md 10절은 자기 벤치마크에 대해 이렇게 쓴다 — "이 합성 수치는 학습과 제약을 시험하지만, 실세계 우월성의 증거는 아니다. 출판 가능한 평가에는 실제 실행에 대한 신뢰구간, 강한 학습형 베이스라인, 마켓플레이스 트레이스 재생, 보정 분석, 적대적 조건이 필요하다."

자기 프로젝트의 약점을 이렇게 구체적으로 적는 README는 드물다. 무엇을 증명했고 무엇을 증명하지 않았는지 구분해 쓰는 것은 오픈소스든 사내 문서든 그대로 가져갈 만한 습관이다.

7하드웨어 · 시스템 요구사항

이 항목은 짧게 끝난다. 필요한 건 파이썬 3.10 이상뿐이다.

git clone --depth 1 https://github.com/wang2122/sprix-sage-router.git
cd sprix-sage-router
python demo.py            # 결정 하나 출력
python -m unittest -v     # 테스트 12개
python benchmark.py       # 2,500개 작업 비교 (약 2.8초)

8직접 해볼 수 있는 실습 과제

9관련 기술 심화 학습 로드맵

1주차 — 코드와 수식을 나란히 놓고 읽기

2주차 — 배경 이론 채우기

3주차 — 프로토콜과 생태계

4주차 — 만들어 보기

10핵심 키워드 사전

11참고 링크