제품 지향점, 아키텍처 경계, 통합 테스트 매트릭스¶
공식 엔지니어링 정렬 초안 · 2026-10-16 · 출시 기능이나 검증된 성능을 주장하는 문서가 아님. 기존 아키텍처, 설계 원칙, 제품 정의, 설계·실험 이력, 오픈소스 비교 위키, 동결된 에이전트 평가, 외부 자격 검증 #1346을 연결한 현재 시점의 판단 기록입니다. 예전 사전 등록 프로토콜이나 정답 레이블을 바꾸지 않으며 새로 측정한 점수도 없습니다.
1. 존재 목적과 제품 경계¶
목적: AI 에이전트가 필요로 하는 정보와 작업을 실제로 등록된 타입 기반 기능 계약으로 연결합니다. 여러 API·도구·데이터 시스템에서 검증 가능한 실행 계획을 수립하고, 원본 스키마·로컬 호스트의 권한·실행 바인딩에 따라 실행을 검증한 다음, 최소한의 검증된 결과와 출처를 반환하는 계층입니다.
이 프로젝트가 하지 않는 일: 일반 대화/에이전트 반복 루프·메모리·그래프·체크포인트, LLM 비용·모델 라우팅, 단순 임베딩 순위표, 일반 RAG 답변 생성기, MCP 전송 계층 대체, 자격증명 프록시, 모델이 실행 권한을 스스로 부여하는 분류기는 제품 목적이 아닙니다.
실제로 확인할 제품 가치: - 정상 요청에 필요한 전체 작업 단계와 출력 필드를 유지하고, 주변 에이전트가 끝까지 과제를 완료할 수 있어야 합니다. 한 개의 높은 점수 도구만 맞혔다고 성공이 아닙니다. - 금지된 작업, 등록 기능으로 불가능한 요청, 정보 부족이나 모호한 요청, 실행 중 원본 스키마·권한 변경을 정확히 처리하고 허가되지 않은 호출을 실행하지 않아야 합니다. 이 상태들을 서로 다른 결과로 식별해야 합니다. - 모델에 보여 주는 스키마와 데이터 필드를 줄이되 숨겨진 작업 성공률 하락 없이 총 컨텍스트·실행 비용을 줄여야 합니다. - 최소 EN/KO/JA 입력, 서로 다른 제공자 및 어댑터에서도 원본이 증명하는 동일한 계약을 유지해야 합니다. 의미 모델은 검색에 도움을 줄 수 있어도 존재하지 않는 도구나 권한을 만들면 안 됩니다. - 대화·에이전트 루프·상태 보존은 상위 프레임워크 담당입니다. SchemaRouter는 타입 기반 기능 검색·필드/인자 의미·스키마 일치·호스트 실행 검증을 담당하고, 신뢰된 invoker/제공자는 실제 전송과 데이터 반환을 담당합니다.
절대로 양보할 수 없는 불변 조건¶
- 원본 등록 권한: 모델이 도구·엔드포인트·필드·권한·동작 부작용·invoker 바인딩·자격증명·제공자·사용자 승인을 지어내면 안 됩니다.
- 필요 정보가 명확하면 필드 우선: semantic ID, 타입, 단위, 물리적 한정 조건, 출처를 계약으로 다룹니다. 필드가 모호하면 재현율을 유지할 수 있어도 실행 권한을 새로 주지 않습니다.
- 검색 전과 실행 직전 최소 권한: RBAC/ABAC·데이터 가시성·가용성·부작용 정책·원본 fingerprint를 신뢰합니다. 검색·모델 판단은 신뢰하지 않는 제안이며 호스트 권한 영수증이 될 수 없습니다.
- 고정된 비용 경계: K·도구 호출 수·스키마/토큰 예산을 명시합니다. 필수 도구가 K를 초과하면 예산 부족을 보고해야 하며, 두 단계 작업을 한 개 도구만으로 성공했다고 주장하면 안 됩니다.
- 미지원·정보 부족·금지를 구분: 등록 기능 부재, 필요한 매개변수 미제공, 작업 자체의 모호함, 허가되지 않은 요청은 내부적으로 다른 상태입니다. 외부 공개 메시지는 숨겨진 도구 정보를 누설하지 않아야 합니다.
- 동결된 연구 보존: 이미 노출된 #432/ServiceNow/Open-Meteo 결과를 보고 사후 임계값을 조절하거나, 가변 K 합집합을 K=5 결과라고 표시하거나, 합성 다국어 문장 테스트를 실제 언어 성능으로 설명해서는 안 됩니다.
- 검증 실패 차단과 감사 가능성: 스키마·권한의 최신성이 불분명하거나 단위 호환이 증명되지 않으면 실행을 차단합니다. 도구 선택 이유는 관찰 가능한 사실만 표시하고 chain-of-thought·자격증명·숨겨진 목록은 노출하지 않습니다.
2. 기존 증거 정렬: 완료한 것과 입증하지 못한 것¶
| 영역 | 실제 확인된 상태 | 아직 입증하지 못한 주장 | 기존 근거 |
|---|---|---|---|
| 타입 기반 Registry, 어댑터, 필드 우선 계획, 스키마 검증, 실행 정책 | 제품 구조와 회귀 검증 다수 구현 | 모든 외부 API 방언과 동적 제공자의 완전한 검증 | 아키텍처, 설계 원칙 |
| 프레임워크 연결 | Pydantic AI ToolSearch·OpenAI Agents SDK 동적 MCP 통합 E0; LangChain·LangGraph·LlamaIndex 어댑터 | 상위 에이전트 최종 성공·외부 프로젝트 채택·자체 실행 승인 대체 | Pydantic AI, Agents SDK |
| 권한·원본 일관성 | #1466, #1470, #1472에서 원본 fingerprint, 허용된 필드, Top-K 이전 후보 수, 실행 도중 관찰되는 소스 변경 차단 보강 | 동시 ABA·객체 내부 변경에 대한 완전 원자성, 독립적 외부 공격 증명 | #1450 |
| 미지원 요청·거부 판단 | 선택적 abstention 기구와 합성 안전성 테스트는 있음; 과거 ADB·conformal·고정 원시 코사인은 정상 요청 거부 심각 | 제공자 간 보정된 no-fit·정상 요청을 유지하는 낮은 오거부율 | 선행연구, 기각된 CPU 결과 |
| 다국어 검색 | 원본 Open-Meteo DEV K5: E5 26/27, Lexical 18/27; ServiceNow 영어 DEV: E5 15/20, Lexical 17/20. 미지원 모두 후보 반환 | 제공자에 일반화되는 EN/KO/JA, E5의 전역 기본값, 입력 인자 정확성 | OSS 위키, #1339 |
| 실제 에이전트 | 동결된 780개 과제에서 SR-5 성공 29.19%, FULL 49.62%, ORACLE 70.98%; 일부 구간 KO/JA 첫 필수 도구 재현율 0/160 | SR-5의 작업 성공 비열등성·완전한 최종 답·상용 수준 | #432, #1339 |
| 제3자 독립 검증 | 제공자 원본 수집, DEV 평가·증거 사전검증 구조 존재 | 제공자·작성자 분리 정답, 외부 승인된 실제 에이전트 E2, 출시 적합성 | #1346, #1228 |
실패 원인 단정 금지: #432는 기존 배포 가능 후보가 게이트를 통과하지 못했음을 입증하지만, 전부 초기 검색 때문임을 뜻하지 않습니다. ORACLE도 성공률이 100%가 아니었고, progressive에서 누적 도구 재현율이 첫 재현율보다 크게 증가해도 작업 완료율은 낮았습니다. Recall@5 단독 최적화로 제품 목표를 대신하지 않습니다. 과거 로드맵의 '진행 중' 표기는 당시 기록이므로 현재 GitHub 이슈 상태와 이 문서의 작성 날짜를 우선 확인합니다.
3. 하나의 통합 파이프라인 초안 — 독립 검증 전 기본값 변경 금지¶
신뢰된 Principal과 원본 사용자 요청
→ Registry·원본 버전 증인과 권한에 따라 볼 수 있는 기능 목록
→ Lexical/BM25 및 선택형 다국어 Dense 후보 탐색
→ 원본 도구 ID로 후보 통합, 고정 K·스키마/토큰 예산 확인
→ 작업 종류·필수 입력 인자·출력 필드·단위·부작용 적합성 검사
→ 상태 구분: 검증된 지원 | 모호함 | 추가 인자 필요 |
독립적으로 보정된 미지원 | 권한 없음
→ 현재 사용자에게 공개 가능한 원본 스키마만 제한 공개
→ 에이전트가 인자와 필요한 멀티스텝 순서를 결정
→ 실행 직전 fingerprint·권한·필수 인자·승인·부작용·출력 스키마 재검증
→ 검증된 최소 결과·출처 반환 → 에이전트 실제 작업 완료 평가
이는 구조 제안입니다. 위 기능 가운데 하이브리드 후보 결합, 검증된 no-fit 분류기, 완전한 원자적 스냅샷이 이미 제품에 구현되어 있다는 뜻은 아닙니다. #432의 평가 조건과 점수를 변경하지 않습니다. K를 넘는 복수 도구가 필요한 과제는 다른 방식에만 K를 올려 주지 말고 명시적인 확장 비용 또는 예산 실패로 측정해야 합니다.
4. 통합 테스트 목록 — 단계가 아니라 실제 과제 전체를 평가¶
우선순위: P0 = 진입 조건·안전·원본 정확성, P1 = 상용 성능 비교의 핵심, P2 = 확장성·생태계. 아래 표의 각 행을 별도 PR이나 소형 연구 스크립트로 만들라는 뜻이 아닙니다. 동일한 버전의 하나의 통합 평가 하네스에서 여러 과제 유형을 측정하고 최종 의사결정도 하나로 정리합니다.
| ID / 우선 | 테스트 과제 또는 공격 조건 | 평가 지표와 통과 판단 |
|---|---|---|
| G01 P0 | 실제 제공자 원본, 허용 라이선스, Git blob·스키마·도구·필드 해시, 정확한 설치 wheel/커밋 | 입력·아티팩트 재현, 원본 변경·정답 누락 시 차단 |
| G02 P0 | 제공자와 과제 작성자 모두 분리한 학습·DEV·보정·확인 데이터. EN·KO·JA 각 원어 요청 | 점수 확인 전에 독립성·중복·유출 검증 |
| S01 P0 | Viewer/Admin/거부된 주체, 숨겨진 필드, 전체 숨겨진 도구, 신뢰 원본 위조 | 권한 없는 경로·필드 노출 0, 숨겨진 개수 누설 금지 |
| S02 P0 | Registry·스키마·프로토콜 변경, 권한 철회, 도구 가용성 변동, 모델 추론 전후 변경 | 최신 근거 없는 결과·호출 차단, 오래된 권한 영수증 불허 |
| S03 P0 | 읽기/쓰기·삭제 형제 작업, 모델 위조 인자·ID, 원본 설명 내 프롬프트 주입, 승인 거부, ABA·동시성 | 무권한 호출 관측 0, 미해결 원자성은 #1450에 기록 |
| R01 P1 | EN→EN, KO/JA→영어 원본 도구, 반대 언어 방향, 다국어 ID·별칭 | 전체 필수 도구 집합 Recall@K·완전 포함율과 언어별 실패 |
| R02 P1 | 같은 리소스의 목록/조회/수정/삭제, 검색/상세 등 유사 엔드포인트 | 정확한 원본 작업 유형, 위험한 형제 작업 혼동 0 |
| R03 P1 | 이름만 같고 타입·단위·조건이 다른 필드, required 인자와 출력 필드 | 필수 입력·필수 출력·단위/한정 조건 각각 분리 평가 |
| R04 P1 | 같은 분야의 미지원 요청, 완전 OOD, 빠진 기능, 허가 없는 유사 도구 | 미지원 오선택율·실제 호출 차단·미노출 증명 |
| R05 P1 | 필수 인자 부족, 모호한 지시 대상, 다중 작업, 제약 모순 | 정상 요청 오거부율, needs-input·ambiguous 정확성 |
| R06 P1 | no-fit·작업 적합성 모델을 별도 보정 집합으로 보정 후 독립 확인 | 미지원 오선택과 정상 오거부를 동시에 측정; 단순 코사인 컷오프 금지 |
| A01 P1 | 단일 도구·형제 도구의 작업 및 정확한 인자 조합 | 최종 과제 성공, 함수·인자 일치, 실패 원인 |
| A02 P1 | 2·3단계 상태 의존 작업, 식별자 전달, 격리된 실제 순차 실행 | 올바른 상태 전이·최종 답, 후보 검색만으로 성공 인정 금지 |
| A03 P1 | 복구 가능한 도구 실패, 제공자 fallback, 재시도, 점진적 재검색 | 정답 사전 지식 없이 복구하는지, 추가 호출·부작용 기록 |
| A04 P1 | 사실·숫자 결과, 단위·출처, 사용자에게 숨긴 응답 필드 | 최종 답의 사실·단위·출처·권한 일관성 |
| E01 P1 | FULL 대 Lexical SR-5, Dense SR-5, Hybrid SR-5, Typed+No-fit, 분석용 ORACLE | 동일 과제의 최종 성공률 차이와 신뢰구간, 동일 모델·권한·예산 |
| E02 P1 | 고정 공개 K=5, 실제 도구 스키마 입력/출력 byte·token, 100/250/500개 카탈로그 | 공개 도구·필드, 스키마/전체 토큰, CPU p50/p95/p99, 전체 지연, RAM |
| I01 P2 | Pydantic AI, OpenAI Agents, LangChain/LangGraph/LlamaIndex, MCP/OpenAPI | 도구 공개·승인·검증·실행 경계 유지, 기존 #644/#645 중복 금지 |
| I02 P2 | 1,000개 도구, 동적 등록/삭제, 색인 캐시 무효화, 여러 Principal 동시 조회 | 인덱스·전수조사 동등성, 사용자 간 정보 누출 방지 |
반드시 포함할 차원: EN/KO/JA 원어 요청, 다른 언어로 작성된 도구 설명, 정상/근접 미지원/OOD/모호함/정보 부족/권한 없음, 도구 집합과 필드, 읽기/변경, 1/2/3+ 호출, 100/250/500개 엔드포인트 및 가능하면 1,000개 검색 전용 스트레스. 모든 교차 셀마다 새 과제를 만드는 것은 아닙니다. 샘플링 방식과 비어 있는 셀을 평가 전에 명시하고, 같은 과제를 여러 규모에서 실행한 횟수를 독립 과제로 부풀리지 않습니다.
5. 평가·제품 채택 계약¶
- 최우선 지표: 의미상 서로 독립적인 과제의 최종 완료율, 언어별·과제 유형별 분리 결과. 동일 에이전트·동결된 요청·실제 통제된 도구 실행·동일한 원본 권한에서 짝비교합니다. 기존 #432 게이트는 FULL 대비 과제 클러스터 신뢰구간 하한 -2%p 이상, 필수 도구 집합 재현율 97% 이상, 도구 스키마 토큰 FULL의 40% 이하, 전체 입력 토큰 감소, 무권한 파괴적 실행 0건 등을 요구했고 통과하지 못했습니다. 그 기준을 사후 수정하지 않습니다. 새로운 통합 연구의 성공 마진·표본·통계 정밀도는 새 결과 확인 전에 사전 등록해야 합니다.
- 보조 지표: 전체 필수 도구 집합, 정확한 엔드포인트, 필수 인자, 출력 필드·단위, 정상 오거부/미지원 오선택, 스키마 byte와 실제 tokenizer 토큰, CPU warm/cold p50/p95/p99·RSS·cache, 제공자·모델 호출 횟수, 최종 사실·출처 일치.
- 비교군: 권한 범위가 같은 기존 Lexical, 원본 모델 고정 Dense, 고정 K Hybrid, 필드·작업 적합성+독립 보정된 거부, FULL, 분석 전용 ORACLE. 각 비교군의 공개 후보 K와 스키마·토큰 예산은 같아야 합니다. 예산 초과는 명시적인 실패로 세고, 정답을 보고 후보를 보강하지 않습니다.
- 기존 DEV 개선만으로 출시하지 않기: 제공자 출처와 사용 권한, 분리된 정답 작성자, 점수 전 동결한 연구 조건, 실제 에이전트 경로 기록, 부정적 결과, CI 및 별도 안전성 리뷰 없이는 기본값을 바꾸지 않습니다.
- 안전성 우선: 개인정보·무권한 실행 회귀가 발견되면 모델 성능이 좋아도 적용을 중단합니다. 모든 정상 요청을 거부해서 OOD 거부율만 높인 방법은 실패입니다. 모델 점수는 결코 실행 승인이나 사용자 권한이 아닙니다.
6. 추진 순서와 반복 방지 규칙¶
단계 0 — 지금 정렬: 본 문서, 기존 선행연구, 오픈소스 위키, 현재 이슈 #200/#1339/#1346/#1450을 확인해 단일 현황표를 만듭니다. 10월 15일 이미 기각한 코사인·CrossEncoder 실험, #644의 동일 합성 과제, 공개된 ServiceNow/Open-Meteo DEV를 새로운 독립 성능처럼 반복하지 않습니다.
단계 1 — 독립 평가 준비가 선결 과제: 실제 원본 도구를 정당하게 이용할 수 있는 조건과 제공자 또는 다른 작성자가 확인한 필수 작업·필드·권한·미지원 정답을 확보합니다. 데이터 분할, 원본 해시, 모델 버전, 오차·비용 상한을 실행 전에 고정합니다. 외부 사례를 확보하지 못하면 허구의 독립 결과를 만들지 말고 BLOCKED_EXTERNAL로 정확히 기록합니다.
단계 2 — 선택형 통합 파이프라인 한 개: Lexical/Dense→고정 K→타입 기반 적합성→거부·정보 부족·모호함 판단을 안전한 실험 API 아래 통합합니다. 표의 G/S/R 테스트와 기존 회귀를 통과해야 합니다. 현행 제품 기본값은 유지합니다.
단계 3 — 하나의 짝비교, 하나의 결정: G/S/R/A/E 조건을 묶어 실행합니다. 검색 실패 / 작업 종류 혼동 / 필수 인자·필드 누락 / 실행·권한 오류 / 에이전트 추론·최종 답변 오류를 구분합니다. ServiceNow 악화·Open-Meteo 개선은 과거 DEV 근거로만 인용하며 새 정답을 고르는 데 사용하지 않습니다.
단계 4 — 독립 검증 후 채택 또는 기각: 안전하고 실제 작업 완료율이 개선되며 GitHub Linux CPU 예산 안에서 재현될 때에만 제품 적용을 심사합니다. 그렇지 않다면 어느 단계에서 실패했는지 밝히고 중단합니다. K·허용 임계값을 사후 완화하지 않습니다. v0.18 PR #1356은 계속 출시 보류, #1339/#1346/#1450은 실제 독립 증거와 권한 경계가 해결되기까지 열린 상태입니다.
진행을 평가하는 기준: 이전에 실패한 실제 과제 한 건을 올바른 도구·필드·권한·최종 답으로 완료하고, 새로운 미지원 오선택·무권한 호출이 없다는 것을 증명하는 일입니다. 신규 스크립트 수, PR 수, 모델 순위표, 합성 테스트 통과 자체는 준비 작업이지 제품 성공이 아닙니다.