iop/agent-roadmap/phase/automation-runtime-bridge/milestones/cli-agent-group-grade-routing.md

Milestone: CLI Agent Group Grade Routing

위치

• Roadmap: agent-roadmap/ROADMAP.md
• Phase: agent-roadmap/phase/automation-runtime-bridge/PHASE.md

목표

CLI provider에 등록된 agent를 목적별 agent group으로 묶고, PLAN-local-G08.md, CODE_REVIEW-cloud-G07.md, DOC-local-G04.md 같은 예약어/lane/grade 파일명을 기준으로 실행 agent를 결정한다. 예약어 설정은 기본 실행자를 직접 agent id 또는 auto로 고를 수 있고, auto일 때만 선택된 agent group의 수동/자동 grade routing을 사용한다. OpenAI-compatible 호출은 파일 내용을 prompt 본문에 섞지 않고 metadata.agent_group.task_file로 절대 또는 workspace-relative task file 경로를 전달한다.

상태

[계획]

승격 조건

• 없음

구현 잠금

• 상태: 잠금
• SDD: 필요
• SDD 문서: agent-roadmap/sdd/automation-runtime-bridge/cli-agent-group-grade-routing/SDD.md
• SDD 사유: CLI provider agent catalog, agent group grade assignment, OpenAI-compatible metadata schema, config schema, request routing, usage/resource based selection, route audit log가 runtime/API 계약에 직접 닿는다.
• 잠금 해제 조건:
  • SDD 잠금이 해제되어 있다
  • SDD 사용자 리뷰가 없거나 승인/해결되었다
  • Acceptance Scenario가 Milestone 기능 Task와 연결되어 있다
  • Evidence Map이 완료 시 Roadmap Completion과 최종 검증 evidence로 검증 가능하게 연결되어 있다
• 결정 필요: 아래 체크리스트
  • 선택된 agent 실행 실패, provider quota 소진, 실행 중단, 중복 실행 위험이 발생했을 때 자동 재라우팅/재시도/중단 중 어떤 후속 정책을 적용할지 결정한다. 이번 Milestone의 schema와 routing 구현은 이 정책이 결정되기 전까지 자동 retry/fallback 동작을 확정하지 않는다.

범위

• CLI provider에 나열된 agent를 routing 가능한 실행 단위로 보고, 각 agent가 참조하는 adapter/target, native_lane, 처리 가능한 lane 목록, local/cloud provider 성격, subscription/quota/resource metric source를 config로 표현한다.
• agent group은 목적별 그룹이다. 기본 agent group은 coding이며, docs는 문서/테스트용 추가 기본 후보로 둔다. 그 밖의 목적 그룹도 확장 가능하게 둔다.
• agent group은 assignment_mode=manual|auto, purpose, benchmark profile, agent id 목록, lane별 grade coverage, overlap 정책, 수동 range 또는 자동 산출 range를 가진다.
• agent group 안에서도 local lane과 cloud lane assignment table은 분리한다. cloud-capable agent는 local lane coverage에 포함될 수 있지만, local-only agent는 cloud lane coverage에 포함될 수 없다.
• agent group의 agent id 목록 변경 감지는 순서가 아니라 contain 기준이다. 신규 auto group은 최초 자동 설정 대상이며, 기존 group은 같은 agent id 집합을 재정렬한 변경을 자동 재정렬 트리거로 보지 않고 agent id가 추가/삭제/교체된 경우에만 자동 설정 재계산 대상으로 본다. 이 비교는 group 추가/수정 저장 시점에 이전 agent id set과 현재 agent id set을 메모리에서 비교하는 방식이면 충분하며, hash/cache 기반 변경 감지를 요구하지 않는다.
• 수동 설정에서는 lane별로 G01~G10 coverage가 모두 채워져야 하며, grade range overlap을 허용한다. overlap 후보는 local device resource 여유와 cloud subscription/quota 잔여량을 포함한 route score로 선택한다.
• cloud agent는 local lane 작업 후보가 될 수 있지만, local-only agent는 cloud lane 작업 후보가 될 수 없다. 따라서 local lane coverage는 local agent와 cloud-capable agent가 함께 채울 수 있고, cloud lane coverage는 cloud-capable agent만 채운다.
• grade overlap은 group 설정으로 표현한다. 예를 들어 overlap 폭이 2이면 각 grade의 상위/하위 2개 grade까지 인접 후보가 겹쳐 처리 가능하도록 range assignment를 산출하거나 검증한다.
• 자동 설정에서는 group의 purpose에 맞는 benchmark profile, auto assignment evaluator, 사용자 설정 benchmark sorting prompt를 사용해 group 안의 agent를 정렬하고 grade range assignment schema를 생성한다. coding group은 coding benchmark, docs group은 documentation benchmark를 기준으로 삼고, evaluator가 반환한 자동 assignment 결과는 output schema 검증을 통과한 뒤 auto_ranges로 저장한다.
• 예약어 설정은 사용자 추가가 가능하며, 예약어별 default_agent, prompt_template, user_params_schema, file_payload_policy=path를 가진다. agent_group은 default_agent=auto일 때만 노출/필수인 하위 설정이다.
• 예약어의 default_agent=auto는 해당 예약어가 참조하는 agent_group routing을 사용한다는 뜻이다. default_agent가 특정 cli provider agent id이면 agent group routing을 타지 않고 해당 agent를 기본 실행자로 사용하되, 파일명 lane/grade와 agent capability가 맞지 않으면 실패한다.
• agent group routing이 걸린 요청은 task file basename에서 예약어, lane, grade를 파싱한다. 예약어 prefix는 basename에서 마지막 -{lane}-GNN.md suffix를 제거한 왼쪽 전체 값이며, 형식 불일치, 미등록 예약어, lane/grade 범위 불일치, group coverage gap은 실패로 반환한다.
• OpenAI-compatible 호출은 metadata.agent_group.task_file과 metadata.agent_group.params를 사용한다. agent_route_prefix 같은 중복 필드는 만들지 않고, 예약어/lane/grade는 task file basename에서만 얻는다.
• task file 경로는 절대 경로와 상대 경로를 모두 지원한다. 상대 경로는 OpenAI-compatible CLI route에서 metadata.workspace 기준으로 해석하고, 상대 경로인데 workspace가 없으면 routing input error로 실패한다.
• 예약어 prompt는 task file 내용을 inline으로 붙이지 않고 task file 경로와 사용자 parameter만 전달한다. provider/adapter별 renderer는 같은 의미를 유지한 채 CLI별 인자나 prompt 형태로 변환할 수 있다.
• route request log는 request/execution id, task file, parsed prefix/lane/grade, 예약어 설정, group 또는 default agent, 후보 agent, 탈락 사유, 선택 agent, resource/quota snapshot, 실패 원인을 남긴다.

기능

Epic: [config] Agent Group 설정 계약

CLI provider agent와 목적별 agent group, 예약어 설정을 runtime이 해석 가능한 config 계약으로 고정한다.

• [provider-agent] CLI provider agent catalog가 agent id, adapter, target, local/cloud provider 성격, native_lane, 처리 가능 lane 목록, subscription/quota/resource metric source를 표현한다. 검증: local-only agent가 cloud lane 후보로 들어가면 config validation이 실패하고, cloud-capable agent가 local lane 후보로 들어가는 설정은 통과한다.
• [group-schema] agent group schema가 purpose, assignment_mode, benchmark profile, auto assignment evaluator, benchmark sorting prompt, auto assignment output schema, agent id 목록, lane별 grade coverage, overlap 폭, 수동/자동 assignment 결과를 표현한다. 검증: lane별 G01~G10 coverage gap은 실패하고, 같은 agent id 집합의 순서만 바뀐 저장은 자동 재계산 트리거로 기록되지 않으며, overlap 폭이 산출 range에 반영된다.
• [prefix-schema] 예약어 설정이 사용자 추가 가능한 prefix, default_agent=auto|<agent-id>, 조건부 agent_group, prompt_template, user_params_schema, file_payload_policy=path를 표현한다. 검증: default_agent=auto인데 agent_group이 없으면 실패하고, direct default_agent가 cli provider agent catalog에 없으면 실패하며, direct mode에서는 agent_group이 필수가 아니다.
• [metadata-contract] OpenAI-compatible 계약이 metadata.agent_group.task_file과 metadata.agent_group.params를 지원하고, agent_route_prefix 없이 task file basename에서 예약어/lane/grade를 파싱한다. 검증: 절대 경로와 metadata.workspace 기준 상대 경로가 통과하고, 상대 경로인데 workspace가 없으면 실패하며, prompt 본문에만 파일명을 넣은 요청은 agent group routing 입력으로 사용되지 않는다.

Epic: [routing] Grade 기반 실행 라우팅

예약어, lane, grade, agent group assignment, resource/quota 상태를 조합해 실행 agent를 결정한다.

• [filename-parse] agent group routing 요청은 task file basename의 예약어, lane, grade 형식을 엄격히 검증한다. 검증: PLAN-local-G08.md, CODE_REVIEW-cloud-G07.md, DOC-local-G04.md는 통과하고, lane 누락, G11, 미등록 prefix, 잘못된 grade 표기는 실패하며, prefix는 마지막 -{lane}-GNN.md suffix 왼쪽 전체로 해석된다.
• [default-agent] 예약어의 default_agent가 auto이면 agent group routing을 사용하고, 특정 cli provider agent id이면 그 agent를 직접 선택한다. 검증: direct default agent가 파일명의 lane/grade를 처리할 수 없으면 routing error를 반환한다.
• [manual-routing] 수동 assignment는 lane별 grade range와 overlap을 허용하고, 겹치는 후보는 local resource 여유 또는 cloud subscription/quota 잔여량을 포함한 route score로 선택한다. 검증: 같은 grade를 처리하는 agent가 둘 이상일 때 resource/quota 상태가 더 좋은 후보가 선택된다.
• [auto-routing] 자동 assignment는 group purpose에 맞는 benchmark profile, auto assignment evaluator, 사용자가 설정한 benchmark sorting prompt를 사용해 agent 순위와 lane별 grade range를 산출한다. 검증: coding group은 coding benchmark profile, docs group은 documentation benchmark profile을 사용하고, evaluator 응답이 output schema와 lane별 coverage, cloud/local capability 규칙을 통과한 경우에만 저장된다.
• [route-log] routing 요청마다 request/execution id, task file, parsed prefix/lane/grade, 예약어, group/default agent, 후보/탈락/선택 agent, resource/quota snapshot, 실패 원인이 로그에 남는다. 검증: 성공과 routing error 모두 route log에서 같은 request id로 추적된다.

Epic: [docs-tests] 문서와 검증

구현자가 라우팅 규칙을 재현하고 운영자가 설정 오류를 고칠 수 있도록 문서와 테스트 근거를 남긴다.

• [contract-docs] OpenAI-compatible 계약 문서와 Edge 운영 문서가 metadata.agent_group.task_file, metadata.agent_group.params, 예약어 파일명 계약, path-only payload 정책을 설명한다.
• [config-examples] 기본 coding agent group, 문서/테스트용 docs agent group, manual assignment, auto assignment, PLAN, CODE_REVIEW, DOC 예약어 설정 예시가 config sample에 추가된다.
• [routing-tests] config validation, filename parsing, manual routing, auto assignment result validation, direct default agent, metadata path error, route log 테스트가 추가된다.

완료 리뷰

• 상태: 없음
• 요청일: 없음
• 완료 근거: 기능 Task가 아직 충족되지 않았고 SDD 사용자 리뷰가 남아 있어 구현 잠금이 유지된다.
• 검토 항목:
  • SDD 사용자 리뷰가 해결되고 SDD 잠금이 해제되었다
  • 모든 기능 Task와 Task 안의 검증이 충족되었다
  • OpenAI-compatible 계약 문서와 config 예시가 실제 구현과 일치한다
• 리뷰 코멘트: 없음

범위 제외

• 선택된 agent 실행 실패 후 자동 재시도, 다른 agent fallback, 중복 실행 방지 정책의 최종 동작. 이번 Milestone에서는 잠금 항목으로 남기고, 결정 전에는 자동 retry/fallback을 구현하지 않는다.
• agent benchmark를 실제로 실행해 점수를 산출하는 benchmark runner 구축. 이번 범위는 benchmark profile/prompt와 LLM 기반 assignment 결과 schema/validation이다.
• 모든 cloud provider의 subscription API 연동. MVP는 사용 가능 quota/remaining metric source가 있으면 route score에 사용하고, 없으면 설정된 fallback weight를 사용한다.
• GUI/Client 설정 화면 완성. config/API 계약과 운영 문서 예시를 우선한다.
• 원격 터미널/CLI 터널링, oto scheduler/CI-CD 자동화, 장기 기억/RAG/tool policy routing.

작업 컨텍스트

• 관련 경로: agent-contract/outer/openai-compatible-api.md, apps/edge/internal/openai, apps/edge/internal/service, apps/node/internal/adapters/cli, packages/go/config, configs, apps/edge/README.md
• 표준선(선택): 내부 실행 개념은 adapter + target을 유지하고, OpenAI-compatible 경계의 agent group routing 문맥은 metadata.agent_group 아래에 둔다. 파일명은 routing 계약의 source of truth이며 prefix/lane/grade 중복 metadata는 만들지 않는다.
• 선행 작업: CLI Automation Runtime 안정화, OpenAI Responses Input Surface, OpenAI Workspace Agent Execution Contract
• 후속 작업: CLI Agent 사용량 알림과 자동 이어받기 MVP, 운영 관측과 Provider 관리의 provider quota/usage 고도화
• 확인 필요: 선택된 agent 실패/중단/실행 중 quota 소진 시 자동 retry/fallback/중단 정책은 구현 잠금 > 결정 필요와 SDD USER_REVIEW.md로 분리한다.