[기능] AMDC 읽기 전용 진단 Tool Core를 구축한다

[worud8457]

목적

AMDC 진단 에이전트가 관측 대상별 도구를 필요할 때만 선택하고, 서버가 등록한 읽기 전용 실행 정의를 통해 재현 가능한 근거를 수집하도록 공통 Tool Core를 구축합니다.

LLM은 도구와 구조화된 입력값만 선택합니다. 실행 명령, SQL, HTTP 경로와 환경 연결 정보는 서버가 관리하며 모델이 임의 실행 내용을 생성하지 않습니다.

확인된 현재 상태

• LangChain 에이전트는 select_plugin으로 플러그인을 lazy loading 합니다.
• 도구 정의와 입력 스키마, 고정 실행 내용은 YAML 카탈로그에 둘 수 있습니다.
• Tool Runtime은 입력·환경 검증, timeout, 출력 크기 제한과 정제된 오류 반환을 담당합니다.
• MySQL 직접 조회 도구를 통해 processlist, transaction과 InnoDB lock wait를 로컬에서 검증했습니다.
• 현재 작업 브랜치에는 system 1개, MySQL 12개, Prometheus 12개, ProxySQL 13개 도구가 연결되어 있습니다. Loki는 미구현 후속 작업입니다.

범위

• 플러그인과 도구를 YAML 카탈로그에서 선언합니다.
• 에이전트에는 최초에 플러그인 선택 도구만 노출하고 선택된 플러그인의 도구만 제공합니다.
• 고정된 읽기 전용 SQL·HTTP·로컬 실행 정의만 허용합니다.
• Tool Core가 입력 스키마, 실행 환경, timeout, 호출 결과 크기와 오류 정제를 검증합니다.
• 원본 관측 결과와 적용된 필터, 수집 시각, truncation 여부를 반환합니다.
• 플러그인별 구현과 실제 데이터 소스 검증은 별도 하위 이슈로 추적합니다.

하위 작업

• MySQL 읽기 전용 진단 도구
• Prometheus 읽기 전용 진단 도구 — 12개, 작업 브랜치 구현·로컬 검증 완료; develop 병합 전
• Loki 읽기 전용 진단 도구
• ProxySQL 읽기 전용 진단 도구 — 13개, 작업 브랜치 구현·로컬 검증 완료; develop 병합 전
• 필요한 후속 관측 대상 플러그인

제외 범위

• LLM이 생성한 임의 SQL, shell 명령 또는 HTTP 경로 실행
• SSH 및 운영 변경 작업
• 세션 종료, 재시작, 배포, 데이터 수정과 같은 mutation
• 최종 리포트 영속화 및 Discord 표현 형식
• 특정 장애 테스트에 맞춘 진단 결론 또는 계산 로직

의존성과 경계

• 이 이슈의 도구 실행 결과는 #4의 순서 및 tool_call_id 보존 출력이 소비할 관측 근거입니다.
• 자동화 검증은 #9의 현재 코드 전용 Node 테스트 기반과 정합성을 유지합니다.
• 정본 리포트 영속화와 Discord 전달은 #7의 범위입니다.
• 플러그인별 하위 이슈는 공통 실행 계약을 재구현하지 않고 이 이슈의 Tool Core를 사용합니다.

검증 방법

• npm test
• npm run typecheck
• npm run build
• 가짜 Provider와 가짜 Tool을 사용하는 기본 자동화 테스트
• 플러그인별 격리된 로컬 데이터 소스 실행 검증
• 잘못된 입력, timeout, 권한 오류, 출력 초과와 민감정보 노출 위험 주입

완료 조건

• 에이전트가 등록되지 않은 도구나 실행 내용을 사용할 수 없습니다.
• 플러그인을 선택하기 전에는 개별 도구가 노출되지 않습니다.
• 선택된 플러그인의 읽기 전용 도구만 실행할 수 있습니다.
• 입력·환경·timeout·출력 크기 검증이 모든 실행 경로에 적용됩니다.
• 원본 관측과 정제된 오류가 안정적인 공통 계약으로 반환됩니다.
• MySQL, Prometheus와 Loki 플러그인별 검증 이슈가 연결됩니다.
• 자동화 테스트, 타입 검사와 빌드 결과가 구현 PR에 기록됩니다.

2026-09-18 도구 브랜치 업데이트

• 커밋: 3dd4b33 (feature/jaekyung/langchain-tool), 기존 PR #11에 반영했습니다. develop에 병합한 상태는 아닙니다.
• Prometheus: target·metric name·metadata·series·instant·range 및 instance/database 범위 조회. 임의 PromQL/URL은 받지 않습니다.
• ProxySQL: stats-only Admin 조회로 pool·frontend session·user connection·digest·error·command·global status를 제공합니다. reset 테이블과 쓰기 실행은 거부합니다.
• 로컬 추적은 opt-in/dev-only입니다. 동일 진단의 같은 도구·입력 재실행은 거부하므로, 같은 입력의 재관측도 제한되는 현재 동작에 유의해야 합니다.
• 커밋 대상만 별도 디렉터리에 추출하여 npm test 49개, npm run typecheck, npm run build 통과를 확인했습니다(macOS, Node v26.5.0). 이번에는 live 장애 주입과 LLM 호출을 다시 실행하지 않았습니다.
• 이전 로컬 live 검증 범위와 재현 명령은 docs/prometheus-proxysql-tools.md에 기록했습니다. 운영/장기 부하/메모리 증가 검증을 완료한 것은 아닙니다.
• 진단 조사형 출력, Discord 표시 변경과 tool_call_id 인계는 이 커밋에서 제외했습니다. [작업] LangChain 진단 출력의 순서와 tool_call_id 참조를 보존한다 #4/[기능] 정본 리포트를 조립·영속화한 뒤 Discord로 전달한다 #7 완료를 의미하지 않습니다.
• MySQL #13의 병렬 상세 조회 실패, Loki 구현 및 플러그인별 이슈 연결은 미완료로 유지합니다.