AI 튜토리얼

Sprix SAGE Router로 AI 에이전트 작업 라우팅하기

Sprix SAGE Router 설치 방법, 에이전트와 작업 종속성 모델링, 실행 가능한 경로 선택, 할당 결과 확인, 실행 증거를 활용한 향후 의사결정 개선 방법을 알아보세요. 또한 이 튜토리얼에서는 A2A 통합, 제약 조건, 벤치마킹, 초기 연구 프리뷰 단계에서의 실용적인 지침을 설명합니다.

2026년 8월 20일약 15분 소요

Sprix SAGE Router란?

Sprix SAGE Router는 작업이 이미 시작된 후 AI 에이전트가 작업을 어떻게 실행해야 하는지 결정하기 위한 오픈 소스 Python 연구 프로젝트입니다. SAGE는 State-Aware Graph Exchange의 약자입니다. 이 라우터는 에이전트 탐색과 작업 실행 사이에서 작동하며, 현재 진행 상황, 역량, 권한, 비용, 지연 시간, 종속성 및 컨텍스트 전송 손실을 고려해 실행 가능한 에이전트 구성을 선택합니다.

라우터는 세 가지 실행 모드를 비교합니다.

SELF: 역량과 축적된 컨텍스트가 충분한 경우 기존 에이전트가 혼자 계속 작업합니다.
COLLABORATE: 기존 에이전트가 소유권을 유지하고, 보완적인 에이전트가 부족한 요구 사항을 담당합니다.
HANDOFF: 전문 에이전트의 이점이 컨텍스트 전송 비용보다 큰 경우 동료 에이전트가 전체 소유권을 넘겨받습니다.

SAGE는 Agent2Agent 프로토콜 상위 계층에서 작동하도록 설계되었습니다. A2A는 상호 운용 가능한 Agent Card, 작업, 메시지, 아티팩트, 인증 및 전송 방식을 정의합니다. SAGE는 다른 질문을 다룹니다. 즉, 작업을 실행할 수 있는 구성은 무엇이며, 어떤 모드로, 어떤 이유로 실행해야 하는가입니다.

현재 프로토타입은 라우팅 결정만 반환합니다. 에이전트에 작업을 전송하지 않으므로, 선택된 경로를 실행하려면 A2A 클라이언트나 다른 실행 계층이 필요합니다.

주요 라우팅 기능

SAGE는 라우팅, 스케줄링 및 온라인 학습을 하나의 검토 가능한 의사 결정 과정으로 결합합니다. 주요 기능은 다음과 같습니다.

세 가지 모드 라우팅: SELF, COLLABORATE 및 HANDOFF 후보가 동일한 효용 목표 아래에서 경쟁합니다.
진행 상황을 반영한 재계획: 누적 진행 상황, 활성 실행자, 실패, 완료된 작업 노드 및 전송 가능한 컨텍스트에 따라 전환의 가치가 달라질 수 있습니다.
보완적 팀 선택: 팀은 순위가 높은 중복 에이전트를 모으기보다 요구 사항 범위를 추가로 충족할 때 보상을 받습니다.
컨텍스트 기반 신뢰도: 신뢰도는 하나의 전역 평판 점수로 축소되지 않고, 각 에이전트와 요구 사항별로 학습됩니다.
작업 DAG 스케줄링: 요구 사항은 실행자에게 할당되고, 종속성 간선은 실행 순서, 통신 토폴로지 및 임계 경로 지연 시간을 결정합니다.
제한된 탐색: 빔 탐색은 단일 탐욕적 선택을 하는 대신 여러 협업 팀 접두사를 평가합니다.
제약 조건 우선 필터링: 적격하지 않은 에이전트는 예상 품질과 관계없이 순위를 매기기 전에 제거됩니다.
증거 기반 학습: 요구 사항 점수, 실제 비용 및 실제 지연 시간이 신뢰도, 시너지, 성공 모델 및 입찰 충실도를 업데이트할 수 있습니다.
감사 가능한 결과: 결정 결과에는 선택된 모드, 할당, 토폴로지, 예상 성공률, 커버리지, 비용, 지연 시간, 위험, 효용 및 근거가 표시됩니다.

알고리즘의 경로 평가 방식

SAGE는 각 작업 요구 사항에 대해 전역 신뢰도와 요구 사항별 신뢰도를 결합하여 에이전트의 보정된 역량을 추정합니다. 팀 구성원이 유용하고 중복되지 않는 역량을 제공하면 팀 커버리지가 높아집니다. 이후 남은 각 요구 사항은 보정된 팀 구성원 중 가장 강한 구성원에게 할당됩니다.

스케줄러는 요구 사항 DAG를 준수합니다. 한 에이전트에 할당된 작업은 순차적으로 실행되고, 서로 다른 에이전트에 할당된 독립적인 작업은 병렬로 실행될 수 있습니다. 후보 팀을 구성한 후 SAGE는 팀 수준의 비용과 임계 경로 지연 시간이 작업의 예산과 마감 시간을 충족하는지 확인합니다.

실행 가능한 후보는 예상 성공 가치와 비용, 지연 시간, 위험, 컨텍스트 전송 손실, 조정 오버헤드 및 불확실성 사이의 균형을 맞추는 효용 함수로 순위가 매겨집니다. 이를 통해 더 강력한 전문 에이전트라도 핸드오프 시 유용한 컨텍스트를 너무 많이 잃는다면 기존 에이전트에 질 수 있습니다. 또한 보완적인 팀이 명성은 높지만 중복되는 에이전트 집합을 앞설 수도 있습니다.

프로젝트 설치 및 확인

사전 요구 사항

참조 구현에는 Python 3.10 이상이 필요합니다. 프로젝트 README에 따르면 런타임 종속성이 없습니다.

저장소 복제

git clone https://github.com/wang2122/sprix-sage-router.git
cd sprix-sage-router
python demo.py

demo.py 스크립트는 처음부터 끝까지의 예제를 읽기 쉬운 형태로 제공합니다. 저장소가 sprix_sage.py를 통해 구현을 직접 노출하므로, 빠른 시작을 위해 별도의 패키지 설치 명령을 실행할 필요가 없습니다.

테스트 및 벤치마크 실행

python -m unittest -v
python benchmark.py

단위 테스트는 라우터가 예상대로 동작하는지 확인합니다. 벤치마크는 결정론적 시드를 사용해 외부 비선형 시뮬레이터를 실행하며, SAGE의 정적 버전과 온라인 버전을 더 단순한 라우팅 전략과 비교할 수 있습니다.

첫 번째 라우팅 시나리오 만들기

1단계: 핵심 타입 가져오기

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

이 예제에서는 Agent로 후보를 설명하고, Requirement와 Task로 작업을 정의하며, SAGERouter로 경로를 선택하고, ExecutionOutcome으로 실행 후 증거를 반환합니다.

2단계: 사용 가능한 에이전트 정의

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,
    ),
]

각 에이전트에는 식별자, 역량 벡터, 비용 추정치, 지연 시간 추정치가 있습니다. 여기서 planner는 계획 수립에 강하고, coder는 코딩에 더 강합니다. 이러한 차이 때문에 SAGE는 에이전트를 하나의 종합 점수로 순위를 매기기보다 협업이나 작업 인계를 고려할 수 있습니다.

3단계: 요구 사항과 종속성 모델링

task = Task(
    "build-feature",
    requirements=(
        Requirement("planning", 0.4),
        Requirement(
            "coding",
            0.6,
            depends_on=("planning",),
        ),
    ),
    value=1.0,
    budget=0.30,
    deadline_ms=4000,
    progress=0.35,
)

이 작업에는 가중치가 적용된 두 가지 요구 사항이 포함됩니다. 코딩 요구 사항은 계획 수립에 종속되므로, 계획 수립이 코딩보다 먼저 완료되어야 하는 작은 DAG가 생성됩니다. 또한 작업에는 제약 조건이 있는 라우팅에 필요한 값이 제공됩니다.

value는 성공적인 완료의 가치를 나타냅니다.
budget은 허용 가능한 비용을 제한합니다.
deadline_ms는 예약된 지연 시간을 제한합니다.
progress는 실행이 이미 35퍼센트 진행되었음을 라우터에 알립니다.

진행률이 중요한 이유는 실행 중 소유권을 변경하면 컨텍스트 전달 손실이 발생할 수 있기 때문입니다. 따라서 전문 에이전트의 역량 우위가 항상 작업 인계를 최선의 경로로 만들지는 않습니다.

4단계: 작업 라우팅

router = SAGERouter(
    agents,
    incumbent_id="planner",
)

decision = router.route(task)

print(decision.mode)
print(decision.assignments)
print(decision.topology)

기존 담당 에이전트는 현재 작업을 담당하고 있는 에이전트입니다. route를 호출하면 실행 가능한 SELF, COLLABORATE, HANDOFF 후보를 비교합니다. 반환된 결정은 다음과 같은 필드를 통해 확인할 수 있습니다.

선택된 실행 모드를 나타내는 decision.mode.
요구 사항과 에이전트 역할의 할당을 나타내는 decision.assignments.
종속성으로 인해 형성된 통신 구조를 나타내는 decision.topology.

이 특정 시나리오가 항상 하나의 특정 모드를 생성한다고 가정하지 마세요. 결과는 라우터의 보정된 추정치, 제약 조건, 진행률 및 학습된 상태에 따라 달라집니다.

실행 결과에서 학습하기

라우팅은 워크플로의 전반부일 뿐입니다. 선택된 에이전트가 작업을 실행한 후에는 이용 가능한 가장 강력한 증거를 라우터에 전달하세요.

router.record_outcome(
    decision,
    ExecutionOutcome(
        success=0.9,
        requirement_scores={
            "planning": 0.95,
            "coding": 0.86,
        },
        actual_cost=0.19,
        actual_latency_ms=1450,
    ),
)

전체 성공 값은 작업 수준의 결과를 라우터에 제공합니다. 요구 사항별 점수는 더 정확한 기여도 할당을 가능하게 하여 모든 팀원이 동일한 기여를 한 것으로 처리되지 않도록 합니다. 실제 비용과 지연 시간은 향후 예측과 제공업체 견적을 보정하는 데 도움이 됩니다.

반복적인 라우팅과 피드백을 통해 온라인 SAGE는 컨텍스트별 신뢰도, 에이전트 쌍 효과, 성공 예측 및 견적 충실도를 개선할 수 있습니다. 유용한 학습을 위해 결과를 일관되게 기록하고, 이용 가능한 경우 대략적인 성공 레이블보다 측정된 증거를 우선하세요.

A2A 시스템에 SAGE 통합하기

프로덕션 통합에서는 프로토콜 및 마켓플레이스 신호를 SAGE의 내부 표현으로 변환할 수 있습니다.

AgentCard.skills를 역량 벡터로 정규화합니다.
보안 요구 사항을 엄격한 권한 필터로 사용합니다.
점수를 계산하기 전에 지원되는 입력 및 출력 모드의 호환성을 확인합니다.
작업 상태, 아티팩트, 완료된 DAG 노드 및 실패를 현재 실행 상태와 전달 손실 추정치에 매핑합니다.
제공업체 견적을 비용, 지연 시간 및 신뢰도를 포함하는 입찰로 표현합니다.
완료된 작업 평가를 사용하여 컨텍스트별 신뢰도, 에이전트 쌍 잔차, 성공 예측 및 견적 충실도를 업데이트합니다.

SAGE가 결정을 반환하면 A2A 클라이언트는 메시지 전송, 스트리밍, 작업 폴링 또는 취소와 같은 프로토콜 작업을 사용하여 이를 실행할 수 있습니다. 경계를 명확히 유지하세요. SAGE는 경로를 선택하고 설명하며, A2A 계층은 통신과 실행을 처리합니다.

고급 사용 팁

작업을 의미 있는 DAG로 모델링하기

모든 요구 사항을 평면 목록에 넣는 대신 종속성을 사용하여 실제 실행 순서를 나타내세요. 정확한 종속성을 사용하면 SAGE가 순차 작업과 병렬 작업을 구분하고 더 유용한 임계 경로 지연 시간 추정치를 생성할 수 있습니다.

상호 보완적인 역량 설명을 우선하기

에이전트를 요구 사항 수준의 역량으로 설명하세요. 하나의 광범위한 점수만 사용하면 계획 수립, 코딩, 연구 또는 기타 기술 간의 차이가 가려지고 컨텍스트별 신뢰도와 역할 할당이 약화됩니다.

권한을 엄격한 제약 조건으로 다루기

예측 품질을 사용하여 접근 규칙을 무시하지 마세요. SAGE의 권한 우선 설계는 부적격 에이전트를 후보 순위 지정 전에 제외하도록 합니다. 호환성, 인증 및 정책 검사도 실행 전에 수행해야 합니다.

현실적인 예산과 기한 사용하기

SAGE는 후보 구성 중과 팀 수준에서 제약 조건을 다시 확인합니다. 작업별 예산과 기한을 제공하여 개별적으로는 매력적인 에이전트 조합이라도 총비용이나 임계 경로가 실행 불가능한 경우 선택되지 않도록 하세요.

모드만 사용하지 말고 결정 내용 확인하기

할당, 토폴로지, 커버리지, 예측 성공률, 비용, 지연 시간, 위험, 효용 및 근거를 검토하세요. 감사 추적을 통해 경로가 실제 상호 보완성, 기존 담당자의 컨텍스트 유지, 낮은 전달 손실 또는 제약 조건 충족 가능성 때문에 선택되었는지 확인할 수 있습니다.

견적 충실도 측정하기

실행 후 실제 비용과 지연 시간을 반환합니다. 관측된 값이 없으면 라우터가 인용된 신뢰도, 가격, 시간이 신뢰할 수 있는지 판단할 근거가 줄어듭니다.

공통 효용으로 트레이드오프 평가

포함된 합성 벤치마크에 따르면 온라인 SAGE는 나열된 기준선보다 더 높은 시뮬레이션 품질과 공통 효용을 달성하지만, 정적 SAGE보다 더 많은 비용을 사용합니다. 이러한 가시적인 트레이드오프는 중요합니다. 라우팅이 역량만을 기준으로 한 점수 뒤에 비용을 숨겨서는 안 되기 때문입니다.

이 벤치마크는 합성 환경에서 수행되었으며 실제 환경에서의 우월성을 입증하지 않습니다. 실제 배포 평가에는 대표성 있는 실행, 강력한 라우팅 기준선, 보정 분석, 마켓플레이스 추적 재생, 이기종 에이전트, 적대적 조건이 필요합니다.

연구 프리뷰의 한계 이해

SAGE는 초기 단계의 연구 프리뷰이며, 프로덕션 서비스 수준 보장이나 동료 심사를 거친 결과가 아닙니다. 경량 학습 정책이 실제 추적 데이터에 대한 학습이나 인과적 오프폴리시 평가를 대체하지는 않습니다.

프로덕션에 배포하기 전에 README는 보정된 평가기, 인증된 ID, 서명된 역량 메타데이터, 개인정보 보호 및 보안 검토, 지속적인 이벤트 기반 복구, 모니터링, 작업별 검증을 권장합니다. A2A 검색, 실행, 스트리밍, 취소를 위한 실제 어댑터는 분산 서비스 운영 및 사람 승인 게이트와 마찬가지로 아직 로드맵 항목으로 남아 있습니다.

저장소 리소스

sprix_sage.py에는 컨텍스트 기반 라우터, DAG 스케줄러, 빔 검색, 온라인 업데이트가 포함되어 있습니다.
demo.py는 엔드투엔드 예제를 제공합니다.
benchmark.py에는 외부 시뮬레이터와 공통 효용 기준선이 포함되어 있습니다.
test_sprix_sage.py에는 동작 단위 테스트가 포함되어 있습니다.
ALGORITHM.md에는 형식적 목표, 검색 과정, 기여도 할당, 한계가 설명되어 있습니다.
GitHub 저장소에는 기여, 보안, 거버넌스, 라이선스 정보가 포함되어 있습니다.

결론

Sprix SAGE Router는 상태를 인식하는 에이전트 매칭을 위한 실용적인 참조 구현을 제공합니다. 작업을 요구사항 DAG로 표현하고, 공유 제약 조건 아래에서 SELF, COLLABORATE, HANDOFF를 비교하며, 실행 증거를 라우터에 다시 반영함으로써 예측 품질과 운영 비용을 모두 고려하는 감사 가능한 멀티 에이전트 의사결정을 실험할 수 있습니다.

demo.py부터 시작해 최소 예제를 재현하고, 모든 라우팅 결정을 살펴본 다음 테스트와 합성 벤치마크를 실행하세요. 실제 A2A 배포를 위해서는 별도의 실행 어댑터를 추가하고, 환경에 필요한 인증, 보안, 관측성, 복구, 검증 작업을 완료하세요.