Azure-Samples/Legacy-Modernization-Agents

이 오픈 소스 마이그레이션 프레임워크는 COBOL과 같은 레거시 코드를 Java 또는 C# .NET으로 변환하는 AI 에이전트의 기능을 시연하기 위해 개발되었습니다. 각 에이전트는 원하는 결과에 따라 수정할 수 있는 페르소나를 가지고 있습니다.
마이그레이션은 Microsoft Agent Framework와 다중 공급자 아키텍처(multi-provider architecture)를 사용하며, Azure OpenAI (Responses API + Chat Completions), GitHub Copilot (PAT 또는 CLI 기반 SDK), 그리고 직접적인 OpenAI를 지원하여 COBOL 코드와 그 의존성을 분석한 후 Java Quarkus 또는 C# .NET 중 하나(사용자 선택)으로 변환합니다.

웹 포털을 통해 마이그레이션 진행 상황, 의존성 그래프, AI 기반 Q&A를 실시간으로 시각화할 수 있습니다.

중요 사항

모델을 호출하는 어떤 작업도 실행하기 전에 반드시 로그인해야 합니다. 이 프레임워크는 로컬 로그인에서 토큰을 가져오므로 별도로 요청하지 않습니다.

유효한 로그인(또는 Config/ai-config.local.env 파일의 API 키) 없이는 첫 모델 호출에서 변환 및 역공학(reverse engineering)이 실패합니다. ./doctor.sh rekt-full, ./doctor.sh estate, 그리고 ./doctor.sh jcl은 모델을 호출하지 않으므로 로그인할 필요가 없습니다.

팁

여기서 시작하세요: 빠른 실행. 이 명령어들을 저장소 루트에서 순서대로 실행하세요:

예시 명령어:

Estate Mission Control은 source/에서만 구축됩니다.
포털의 채팅 및 리포트 페이지는 최소한 한 번 실행(./doctor.sh reverse-eng, convert-only 또는 run)이 필요합니다.

JCL 작업: .jcl 파일을 (.proc, .prc, .inc 멤버와 함께) source/에 넣은 다음, 다음을 수행합니다:

자세한 내용은 JCL을 참조하세요.

doctor 스크립트는 종속성을 확인하고 필요한 서비스를 시작합니다.

flowchart LR
A[📁 COBOL, copybook,<br/>BMS, JCL을 source/에 복사] --> B[⚙ ./doctor.sh setup<br/>provider, models, passwords]
B --> C[⌎ ./doctor.sh rekt-full<br/>parse + load graph<br/><i>모델 없음</i>]
...

flowchart LR
subgraph HOST[🍞 귀하의 컴퓨터]
direction TB
...

모델을 제외한 모든 것이 로컬에서 실행됩니다. 소스 코드는 구성한 제공업체(provider)로 전송되는 프롬프트 내부에만 기기 외부로 나갑니다.

두 개의 Neo4j 인스턴스.
REKT 그래프 (파싱 트리 및 제어 흐름, :7688)와 마이그레이션 그래프 (실행 중 발견된 종속성, :7687)가 있습니다. 포트 및 컨테이너 이름은 Config/ai-config.local.env에서 변경할 수 있습니다.

포털은 호스트에서 실행됩니다 (dotnet run --project McpChatWeb).
만약 컨테이너로 사용하고 싶다면, docker-compose.yml에도 portal 서비스를 추가할 수 있습니다.

Estate Mission Control 및 모델이나 Docker가 필요하지 않습니다.

flowchart TB
S["선택된 프로그램<br/>(--program, --job, 또는 단계별 슬라이스)"] --> FACTS["REKT 파싱에서 가져온 프로그램 사실,<br/>카피북 및 호출 계약<br/>(결정론적, 모델 없음)"]
FACTS --> ANALYZE["CobolAnalyzerAgent<br/>구조 및 로직"]
...

Java 출력물에는 아직 컴파일 게이트가 없습니다. mvn compile로 빌드하여 출력 폴더에서 확인할 수 있습니다. 패리티 검사(parity check)는 보고서를 생성하고 실행을 중지시킬 수 있습니다 (ON_LOW_SCORE=stop), 하지만 복구하지는 않습니다. 'Conversion parity' 및 'Using the generated output'를 참조하십시오.

여기에 표시된 내용은 source/에 있는 공개 IBM Bank-of-Z 샘플을 사용한 것입니다.

Estate 개요: 비즈니스 기능별로 그룹화된 모든 프로그램, 트랜잭션, 화면, 테이블 및 카피북입니다.

Carve-out 계획: 리스크 티어(risk tier), 응집도(cohesion) 및 carve 점수로 순서가 지정된 웨이브(waves) 클러스터링입니다.

단계별 슬라이스 (Stage slice): 변환해야 할 프로그램, 필요한 추가 요소, source/에서 누락된 항목, 그리고 실행할 명령어를 포함합니다.

• 구성 방식
• 빠른 시작
• 사용법: doctor.sh
• 포털
• 리버스 엔지니어링 보고서
• 폴더 구조
• 에이전트 동작 사용자 정의
• 파일 분할 및 명명 규칙
• 아키텍처
• 스마트 청킹(Smart Chunking) 및 토큰 전략

이 프로젝트는 모델 기능 자동 감지 기능을 통해 네 개의 AI 제공업체를 지원합니다:

모델 인식 추론(Model-Aware Reasoning) — 이 프레임워크는 모델 ID에서 모델 기능을 자동으로 감지하고 그에 맞춰 추론 전략을 조정합니다:

할당량이 높을수록 마이그레이션 속도가 빠릅니다. 이 도구는 여러 파일과 청크를 병렬로 처리하므로, TPM(Tokens Per Minute)이 높을수록 대기 시간이 줄어듭니다.

할당량을 늘리려면: Azure Portal → 사용자의 OpenAI 리소스 → 모델 배포(Model deployments) → 편집(Edit) → 분당 토큰 수(Tokens per Minute)

속도 제한(429 에러)을 피하려면 다음 공식을 사용하여 안전한 병렬 작업 한도를 계산하세요:

TPM × 안전 계수 (SafetyFactor)
MaxParallelJobs = ─────────────────────────────────
토큰당 요청 수 (TokensPerRequest) × 분당 요청 수 (RequestsPerMinute)

여기서:

TPM = 사용자의 Azure 할당량 (분당 토큰 수)
안전 계수 (SafetyFactor) = 0.7 (권장, 아래 참조)
토큰당 요청 수 (TokensPerRequest) = 입력 + 출력 토큰 (~코드 변환의 경우 30,000)
분당 요청 수 (RequestsPerMinute) = 60 / 초당 요청 수 (SecondsPerRequest)

안전 계수(SafetyFactor) 이해하기 (0.7 = 70%):

안전 계수는 할당량 한도 아래에 여유 공간을 확보하여 다음 사항들을 처리합니다:

예시 계산:

| 사용자의 할당량 | 요청당 토큰 수 | 요청 시간 | 안전한 병렬 작업 수 (Safe Parallel Jobs) |
|---|---|
| 300K TPM | 30K | 30초 | (300,000 × 0.7) / (30,000 × 2) = 3-4개 작업 |
| ... |

appsettings.json에 설정:

{

이 프로젝트는 Semantic Kernel 대신 **Microsoft Agent Framework** (`Microsoft.Agents.AI.*`)를 사용합니다.

Semantic Kernel 대신 Agent Framework를 사용하는 이유?

• IChatClient 추상화: Responses API와 Chat Completions API 모두에 대한 네이티브 지원을 제공하여 LLM API 측면에서 미래 지향적(future proof)입니다.
• 더 나은 스트리밍 및 비동기 패턴
• 가벼운 의존성 구조 (Lighter dependency footprint)

git clone https://github.com/Azure-Samples/Legacy-Modernization-Agents.git
cd Legacy-Modernization-Agents
./doctor.sh setup # 1. AI 공급자 및 자격 증명 구성
...

설정 마법사 없이 수동으로 설정하기

# 1. Azure OpenAI 구성
cp Config/ai-config.env.example Config/ai-config.local.env
# 수정: _MAIN_ENDPOINT (필수), _CODE_MODEL / _CHAT_MODEL (선택)
...

마이그레이션을 실행할 때는 항상 dotnet run을 직접 사용하지 말고 ./doctor.sh run을 사용하세요.