이 페이지는 영어 문서의 번역입니다. 명령, 식별자, 예제는 그대로입니다. 런타임 7.24.4 · SDK 2.6.7. 영어 원문

자동 경로(Auto-Route)

상태: 활성 범위: 현재 상태 최종 검토: 2026-10-10 담당: ax-code 런타임

Auto-route는 ax-code 안에서 서로 독립된 두 가지 라우팅 동작을 제어합니다.

키워드 라우팅 — 기본적으로 활성입니다. 메시지가 전문가의 키워드나 패턴과 맞으면 에이전트를 전환합니다. 1ms 미만에 발화하며 LLM 호출이 필요 없습니다. 라우팅이 명시적으로 꺼져 있거나, 사용자가 에이전트를 명시적으로 지목하거나, 현재 에이전트를 유지하는 합성 연속이면 건너뜁니다.
복잡도 라우팅 — 선택 사항이며, auto-route 전환으로 켭니다. 가벼운 LLM 호출이 각 메시지를 low, medium 또는 high 복잡도로 분류합니다. low 복잡도 메시지는 명시적으로 구성한 small_model가 자동으로 처리하므로, 간단한 질문의 지연이 줄어듭니다.

기본적으로 auto-route는 꺼짐입니다. 복잡도 라우팅은 비활성입니다. 키워드 라우팅은 이 전환과 별개이며, 구성으로 끄거나 명시적인 에이전트 선택이 우회하지 않는 한 기본적으로 활성입니다.

빠른 시작

TUI에서 전환합니다.

프롬프트에 /smart-llm를 입력하거나
Ctrl+P를 누르고 “auto-route”를 검색하거나
상태 표시줄의 Auto-route On/Off 표시를 클릭합니다

상태 표시줄이 현재 상태를 보여 줍니다.

Auto-route On(보라색 글자) — 복잡도 라우팅이 활성입니다
Auto-route Off(흰색 글자) — 복잡도 라우팅이 꺼져 있습니다(기본값)

설정은 세션을 넘어 ax-code.json에 유지됩니다.

동작 방식

기준 원천

이 페이지는 사용자가 보는 동작을 요약합니다. 동작이 바뀌면 문서를 다음과 대조하여 확인합니다.

packages/ax-code/src/agent/router.ts에서 키워드 라우팅 규칙과 classifyComplexity()를 확인합니다.
키워드 라우팅을 건너뛰는 시점과 복잡도 분류가 실행되는 시점은 packages/ax-code/src/session/prompt.ts를 보십시오.
기본값, 환경, 구성, 지속 동작은 packages/ax-code/src/server/routes/smart-llm.ts를 보십시오.
라우팅 구성 필드와 폐기 메모는 packages/ax-code/src/config/schema.ts를 보십시오.
슬래시 명령 이름, 별칭, 레이블, 상태 표시줄 동작은 packages/ax-code/src/cli/tui/app.tsx를 보십시오.
기대하는 활성화 동작은 packages/ax-code/test/agent/router.test.ts와 TUI 동기화 테스트를 보십시오.

키워드 라우팅과 빠른 모델 복잡도 라우팅을 하나의 기능으로 설명하지 마십시오. 둘은 의도적으로 분리되어 있습니다.

키워드 라우팅(기본 활성, 1ms 미만)

사용자 메시지는 각 전문가 에이전트(security, architect, debug, perf, devops, test)의 키워드 및 정규식 패턴과 맞춰 봅니다. 일치 점수가 신뢰도 0.4 이상이면 에이전트가 즉시 전환될 수 있습니다. LLM 호출은 하지 않습니다. 이 경로는 auto-route 전환과 무관하지만, 라우팅이 꺼져 있거나, 사용자가 에이전트를 명시적으로 지목하거나, 현재 턴이 합성 연속을 위해 기존 에이전트를 유지할 때는 건너뜁니다.

복잡도 라우팅(auto-route 전용, 약 200–500ms)

auto-route가 켜지면 각 메시지는 classifyComplexity()를 통해 빠르고 저렴한 모델로 보내집니다. 이 LLM 호출은 복잡도 추정(low / medium / high)을 반환합니다.

low 복잡도 메시지는 명시적으로 구성한 small_model을 자동으로 사용합니다
medium 메시지와 high 메시지는 평소처럼 기본 모델을 사용합니다
small_model가 없거나 사용할 수 없으면 건너뜁니다
시간 제한은 1.5초입니다. LLM이 느리거나 사용할 수 없으면 조용히 돌아갑니다
모든 오류는 조용히 잡힙니다. 사용자를 막지 않습니다

복잡도 라우팅은 에이전트 라우팅과 무관합니다. 어떤 전문가 에이전트를 쓸지는 분류하지 않습니다. 그 선택은 전적으로 키워드 라우팅이 처리합니다.

Auto-Route가 도움이 되는 경우

시나리오	Auto-Route 없음	Auto-Route 있음
“이 변수는 무엇을 합니까?”	전체 모델을 사용	`low` 복잡도 → 빠른 모델
“이 파일의 내보내기를 모두 나열합니다”	전체 모델을 사용	`low` 복잡도 → 빠른 모델
“취약점을 검사합니다”	키워드가 security로 라우팅	같음 — 키워드 라우팅은 항상 발화합니다
“8개 파일에 걸쳐 인증 모듈을 리팩터링합니다”	기본 모델	`high` 복잡도 → 기본 모델
“이 함수가 느립니다”	키워드 일치 없음, 경로 없음	`low`/`medium` → 올바른 모델 등급

키워드 라우팅은 기술 키워드에 대해 전문가 에이전트를 고릅니다. 복잡도 라우팅은 답에 필요한 추론의 양에 따라 적절한 모델 등급을 고릅니다.

단점과 고려 사항

지연

복잡도 라우팅은 분류 호출을 일으키는 메시지에 200–500ms를 더합니다. 항상 활성인 키워드 라우팅은 영향을 받지 않습니다. 어느 경우든 1ms 미만에 반환합니다.

작은 모델이 필요합니다

복잡도 라우팅에는 명시적인 small_model 구성이 필요합니다. AX Code는 모델 이름에서 도우미를 추론하거나, 사용할 수 없는 고정을 다른 공급자로 옮기지 않습니다. 쓸 수 있는 도우미가 없으면 분류를 건너뛰고 선택한 기본 모델을 유지합니다. 모델 복구를 보십시오.

토큰 사용량

각 분류 호출은 대략 입력 토큰 100–200개와 출력 토큰 10–20개를 사용합니다. 이어지는 주 LLM 호출에 비하면 무시할 수 있습니다.

명시적 선택을 대체하지 않습니다

Auto-route는 자동 모델 등급 선택을 개선하지만, 자연어만으로 전문가 에이전트에 라우팅하지는 못합니다. 올바른 전문가가 중요한 핵심 작업에서는 에이전트 선택기나 @agent 멘션으로 에이전트를 명시적으로 고르는 편이 더 신뢰할 수 있습니다.

구성

TUI에서 전환

/smart-llm 또는 명령 팔레트(Ctrl+P → “Turn auto-route on/off”)를 사용합니다. 변경은 즉시 적용되고 프로젝트의 ax-code.json에 저장됩니다.

구성 파일

{
  "routing": {
    "llm": true
  }
}

환경 변수

AX_CODE_SMART_LLM=true ax-code

환경 변수는 구성 파일 설정을 덮어씁니다.

Auto-Route와 다른 설정

설정	상호 작용
자율 모드	Auto-route는 독립적으로 동작합니다. 에이전트 라우팅과 복잡도 분류는 권한 검사보다 먼저 일어납니다.
샌드박스 모드	상호 작용이 없습니다. Auto-route는 어떤 에이전트와 모델 등급을 고르는지만 바꾸며, 에이전트가 할 수 있는 일은 바꾸지 않습니다.
모델 선택	auto-route가 켜져 있고 모델을 명시적으로 고정하지 않았으면, `low` 복잡도 메시지는 명시적으로 구성한 `small_model`를 사용합니다.
실행 모드	하이브리드 배치(`modes.default: "hybrid"`)는 별개입니다. 로컬과 클라우드 중 어디를 쓸지 고릅니다. 실행 모드를 보십시오.

Auto-Route를 켤 때

켜는 경우:

간단한 질문을 더 저렴하고 빠른 모델로 자동 라우팅하고 싶을 때
복잡도가 낮은 주고받기의 토큰 비용을 줄이고 싶을 때
안정적인 소형 모델이나 flash 모델이 있는 공급자를 쓸 때

꺼 두는 경우:

모든 메시지에 추가 지연이 없기를 원할 때
오프라인으로 일하거나 네트워크가 불안정할 때
토큰 사용을 최소화하고 싶을 때
항상 모델을 명시적으로 고정할 때