🚀 기술 브리핑: 이 튜토리얼은 Gate of AI의 에이전트 워크플로우(Agentic Workflows)에 대한 심층 분석 시리즈 중 일부입니다. 전체 기술 분석, 인터랙티브 코드 샌드박스 및 네이티브 아랍어 번역을 보려면 원문 기사 바로가기를 방문하십시오.
튜토리얼 · 고급
적응형 코드베이스 리서치 에이전트 구축
코드 지식 그래프(code knowledge graph)를 사용하여 검색 기능을 개선하고, 유용한 에이전트 트레이스(agent traces)를 재사용 가능한 인간 승인 스킬로 전환하며, 모델 자체를 조정하는 것이 적절한지 평가하는 세 가지 증거 기반 아이디어를 중심으로 코드베이스 리서치 에이전트를 설계합니다. 이 가이드에서는 또한 디버깅 에이전트가 Python의 PDB와 Java의 JDB와 같은 런타임 도구를 어떻게 사용할 수 있는지 설명합니다.
검증된 연구가 지원하는 내용
적응형 코드베이스 에이전트는 전체 리포지토리를 자동으로 이해하는 마법의 챗봇으로 제시되어서는 안 됩니다. 검증된 자료는 보다 구체적인 설계 방향을 지적합니다. 'Building Adaptive AI Agents'라는 짧은 과정에서는 세 가지 기술을 설명합니다: 에이전트 트레이스를 인간 승인을 받는 재사용 가능한 스킬로 변환하는 것; 대규모 코드베이스의 검색 기능을 개선하기 위해 코드 지식 그래프를 구축하는 것; 그리고 모델 자체를 조정해야 할 시기를 고려하는 것입니다. 이들은 상호 교체 가능한 기능이 아니라 보완적인 접근 방식입니다.
별도의 Microsoft Research 논문인 “Supercharging Coding Agents with Interactive Debugging Capabilities”는 전용 디버그 서브에이전트(Debug Subagent)와 권장되는 디버깅 워크플로우 추가를 연구합니다. 보고된 도구에는 Python의 내장 PDB 디버거와 PyTest 기반 테스트 실행이 포함됩니다. Java의 경우, 이 연구는 JDB와 Maven 및 Gradle 지원을 설명하며, 빌드 시스템은 프로젝트 파일에서 감지하고 증분 빌드 설정이 사용됩니다. 해당 논문은 일부 사례에서 기준선 대비 20% 이상의 개선을 보고합니다. 그 결과는 평가된 접근 방식에 속하는 것이므로 다른 에이전트나 리포지토리에 대한 보장된 결과로 간주해서는 안 됩니다.
따라서 이 튜토리얼은 테스트되고 복사하여 실행할 수 있는 OpenAI 애플리케이션을 제공한다고 주장하기보다는, 소스에 맞춰진 설계 및 구현 계획을 명시합니다. 검증된 출처는 특정 OpenAI Python SDK 워크플로우, 코드 인덱서(code indexer), 저장 계층(storage layer), 프롬프트(prompt) 또는 API 구성을 확립하지 않습니다. 이러한 결정들은 사용자의 환경에서 검증해야 할 엔지니어링 작업으로 간주하십시오.
1단계: 리서치 과제와 증거 경계 정의 (Define the research task and the evidence boundary)
좁은 엔지니어링 질문부터 시작하십시오. 예시로는 보고된 결함(defect)과 관련된 코드를 찾는 것, 동작 변경에 관련 있는 테스트를 식별하는 것, 또는 제안된 수정 전에 검사해야 할 모듈을 찾는 것이 있습니다. 전체 애플리케이션 설명을 요청하는 것보다 검증 가능한 답변을 가진 질문이 더 나은 출발점입니다.
검색(retrieval)을 구축하기 전에 유용한 결과가 무엇인지 문서화하십시오. 리서치 질문의 경우, 그 결과는 관련 저장소 요소(repository elements)를 식별하고 그것이 왜 중요한지 설명할 수 있습니다. 디버깅 작업의 경우, 테스트나 디버거로 확인할 수 있는 가설을 포함할 수 있습니다. 이것들은 언어 모델이 보장하는 기능이 아니라 프로젝트 수준의 인수 기준(acceptance criteria)입니다.
설계에서 리서치와 실행(execution)을 별개의 단계로 유지하십시오. 먼저 증거를 식별하고, 그런 다음 가설을 조사하거나 테스트합니다. 나중에 코드를 변경하는 액션(action)을 추가한다면, 그것을 자체적인 검토 및 검증 요구 사항이 있는 별도의 기능으로 취급해야 합니다. 검증된 리서치는 디버깅 지원과 에이전트 워크플로우를 설명할 뿐이며, 에이전트가 개발자의 작업 트리(working tree)에 검토되지 않은 변경을 가해야 함을 확립하지는 않습니다.
증거 경계(evidence boundary)를 명확히 하십시오. 에이전트가 검토할 수 있는 저장소 또는 프로젝트 자료를 결정하고, 팀이 결론의 근거가 된 증거를 어떻게 검토할지 결정해야 합니다. 이 검증된 소스는 개인 정보 보호(privacy), 보존(retention), 또는 비밀 처리 구현을 규정하지 않으므로, 이러한 설계에 의해 이미 제공되는 안전장치로 어떤 것도 간주해서는 안 됩니다. 해당 요구 사항은 환경에 적용되는 정책 및 인프라를 통해 확립하십시오.
단계 2: 코드 지식 그래프를 중심으로 검색 설계하기
코드 지식 그래프(code knowledge graph)는 대규모 코드베이스에서 검색을 개선하기 위한 검증된 전략 중 하나입니다. 제공된 소스는 그래프 스키마, 파서, 데이터베이스 또는 순위 지정 알고리즘을 구체적으로 명시하지 않습니다. 이러한 선택 사항들은 확립된 기능으로 추론되기보다는 프로젝트를 위해 직접 결정되고 평가되어야 합니다.
설계 단계에서 팀이 기대하는 질문에 어떤 관계가 중요한지 기술하십시오. 그래프 기반 접근 방식은 그것이 나타내는 관계가 관련 증거를 찾는 데 도움이 되는 범위 내에서만 유용합니다. 예를 들어, 팀은 코드 요소와 연구 질문 사이의 어떤 연결이 의미 있는지 결정한 다음, 그 연결을 통해 검색했을 때 예상된 자료가 나타나는지 테스트할 수 있습니다. 선택된 인덱싱 프로세스가 실제로 추출하고 검증하지 않는 한, 특정 관계가 지원된다고 주장해서는 안 됩니다.
검색 튜닝 전에 평가 세트(evaluation set)를 구축하십시오. 대표적인 질문들을 수집하고 엔지니어들이 관련성이 있다고 예상하는 저장소 증거를 식별하도록 하십시오. 그래프 기반 검색을 팀이 선택한 기준선(baseline)과 비교하십시오. 예상된 증거가 결과에 나타나는지 기록하고, 실패 사례는 수동으로 검토하십시오. 이는 “그래프가 검색을 개선한다”는 가정을 선택된 코드베이스에 대해 확인할 수 있는 주장으로 바꿉니다.
관리 가능한 코드베이스나 더 큰 코드베이스의 제한된 부분을 시작합니다. 그래프의 출력물과 알려진 질문에 대해 반환되는 증거를 검사하십시오. 예상되는 자료가 누락되었다면, 모델 탓으로 돌리기 전에 인덱싱 및 검색(retrieval) 설계를 조사해야 합니다. 검증된 과정은 코드 지식 그래프(code knowledge graphs)를 검색 개선 기법(retrieval-improvement technique)으로 식별하지만, 보편적인 이득이나 특정 정확도를 약속하지 않으며 모든 프로그래밍 언어를 지원한다고 주장하지는 않습니다.
3단계: 유용한 트레이스를 인간 승인 스킬로 전환하기
적응형 에이전트 과정은 에이전트의 실행 기록(agent traces)을 인간의 승인을 거쳐 재사용 가능한 스킬로 변환하는 파이프라인을 설명합니다. 이 맥락에서, 트레이스란 사람들이 무슨 일이 일어났는지 이해하고 재사용할 수 있는 교훈이 추출될 수 있는지 고려하는 에이전트 실행 기록에 대한 설명입니다. 검증된 출처는 트레이스의 형식을 정의하거나 특정 데이터 저장소(data store)가 필요하다고 말하지 않습니다.
스킬 수명 주기(skill lifecycle)를 명시적으로 설계해야 합니다. 먼저, 유용하고 반복 가능한 연구 패턴을 보여주는 트레이스를 식별합니다. 다음으로, 그 경험을 바탕으로 간결한 스킬을 제안합니다. 그런 다음, 나중에 실행에 사용할 수 있도록 만들기 전에 사람이 검토하도록 합니다. 제안(suggestion)과 승인된 스킬(approved skill) 사이의 구분을 유지하는 것이 중요합니다. 이 과정은 단순히 무분별하게 자동 축적되는 것을 아니라, 인간이 승인한 스킬을 구체적으로 설명합니다.
각 후보에 대해, 이것이 연구나 검색을 개선하는 반복 가능한 방법을 포착했는지, 그리고 이를 사용할 사람들에게 이해하기 쉬운지 질문해야 합니다. 단지 검증되지 않은 답변을 반복하거나 유용한 이전 경험과 연결될 수 없는 후보는 거부하십시오. 팀이 도움이 되지 않는 스킬을 어떻게 수정하거나 폐기할지 결정해야 합니다. 이는 검증된 인간 승인 아이디어를 적용하기 위한 권장 거버넌스 질문이며, 출처가 특정 승인 인터페이스나 수명 주기 스키마를 규정하는 것은 아닙니다.
승인된 스킬의 효과를 평가합니다. 비교 가능한 연구 질문을 사용하고 해당 스킬이 엔지니어가 기대하는 증거 검색에 도움이 되는지 검토해야 합니다. 평가는 에이전트를 개선한다는 가정보다는 실제 작업에 초점을 맞춰야 합니다. 인간의 승인은 설명된 접근 방식의 일부이지만, 그 자체만으로는 스킬이 정확하거나 유용하다는 것을 증명하지 못합니다.
4단계: 모델 적응 여부 결정하기
검증된 과정에서는 에이전트가 여러 실행에 걸쳐 개선되도록 돕는 세 가지 방법 중 하나로 모델 자체를 적응시키는 방법을 제시합니다. 이 과정은 특정 모델, 적응 기술(adaptation technique), 학습 방식, 비용 또는 성능 결과를 명시하지 않습니다. 모델 적응을 이미 구현된 기능으로 보기보다는 조사해야 할 결정 사항으로 간주하십시오.
먼저 대표적인 작업을 사용하여 기준선(baseline)을 설정합니다. 해결하려는 반복적인 실패를 식별하고, 그것이 실제로 모델 동작 문제인지 판단해야 합니다. 누락된 리포지토리 관계는 검색 설계(retrieval design)를 가리킬 수 있고, 품질이 낮은 재사용 가능한 연구 절차는 스킬 설계(skill design)를 가리킬 수 있으며, 또 다른 패턴은 모델 적응 조사를 촉발할 수 있습니다. 이러한 비교는 인용된 과정에서 보고된 결과가 아니라 실질적인 의사 결정 프레임워크입니다.
적응 접근 방식을 채택하기 전에, 이를 기준선과 어떻게 비교할지 정의해야 합니다. 동일한 작업을 사용하고 관련성과 정확성 측면 모두에서 결과를 검토하십시오. 보고되는 결론의 범위는 실행한 평가에 묶여 있어야 합니다. 제공된 맥락만으로는 모델을 적응시키는 것이 특정 에이전트를 개선하거나 그래프 검색 또는 재사용 가능한 스킬보다 우수할 것이라고 약속할 근거가 없습니다.
OpenAI 기반 시스템을 구축하는 팀의 경우, 특정 모델 및 API 선택은 공식 문서를 그리고 팀의 배포 요구 사항과 대조하여 확인해야 합니다. 검증된 자료는 OpenAI SDK 버전, API 메서드, 모델 식별자 또는 작동 코드 샘플을 검증하지 않으므로, 이 글은 의도적으로 이를 만들어내지 않습니다.
Step 5: 작업에 필요할 경우 디버깅 워크플로우 추가
리서치와 디버깅은 중첩되지만, 디버깅은 런타임 조사(runtime investigation) 단계를 추가합니다. Microsoft Research 논문에서는 전용 Debug Subagent를 설명하며 버그 수정 작업을 위한 워크플로우를 권장합니다. 해당 연구에서 보고된 Python 지원은 Python의 표준 라이브러리 일부인 PDB를 사용하며, PyTest 기반 테스트 실행을 포함합니다. Java 지원은 JDB를 사용하고 Maven 및 Gradle을 포함하며; 빌드 시스템은 프로젝트 파일로부터 자동으로 감지되고 증분 빌드 설정이 사용됩니다.
이 세부 사항들을 이 튜토리얼의 에이전트가 이미 통합 기능을 가지고 있다는 증거로 사용하는 것이 아니라, 디버깅 역량을 설계하기 위한 참고 자료로 활용하십시오. 프로젝트는 자신이 지원하는 언어와 테스트 워크플로우를 확립해야 하며, 해당 환경에서 디버거와 테스트 실행이 예상대로 작동하는지 검증해야 합니다. 원문은 모든 프로그래밍 언어나 빌드 시스템에 대한 보편적 지원을 설명한 것이 아니라 Python과 Java에 대해 기술하고 있습니다.
전반적인 설계에서 Debug Subagent의 역할을 명확하게 유지하십시오. 인용된 논문에서 이 서브 에이전트의 목적은 대화형 디버깅(interactive debugging) 기능을 통해 버그 수정을 지원하는 것입니다. 연구 요약에서는 또한 정적 코드 분석에만 국한된 서브 에이전트는 실제 런타임 값 없이 불완전한 정보를 제공할 수 있다고 경고합니다. 이 관찰 결과는 버그가 발생했을 때 정적 검사(static inspection)와 런타임 조사(runtime investigation)를 구별해야 하는 이유이며, 모든 질문에 디버거가 필요하다는 주장은 아닙니다.
디버깅 가설이 지지되는지 여부를 확인하는 데 도움이 되는 테스트를 선택하십시오. 해당 논문은 Python 작업에서 특히 PyTest 기반 테스트 실행을 식별합니다. Java의 경우, 제공된 요약에서는 JDB와 Maven 또는 Gradle 지원을 식별합니다. 따라서 모든 저장소에 대해 단일 테스트 명령어 또는 완전한 설정 절차를 확립하는 것이 아니므로, 프로젝트 자체의 빌드 및 테스트 문서를 따르십시오.
Step 6: 결과를 평가하고 한계를 명시하기
평가(evaluation)를 대신하여 자신감 있게 들리는 답변을 사용해서는 안 됩니다. 리서치 작업의 경우, 검색된 증거를 엔지니어가 사전에 식별한 자료와 비교해야 합니다. 디버깅 작업의 경우, 워크플로우가 조사를 지원하는지, 그리고 런타임(runtime) 증거가 결론을 변경시키는지 평가해야 합니다. 시스템 검토자들에게는 평가 예시, 예상 증거, 관찰된 결과가 항상 제공되어야 합니다.
Microsoft Research 논문은 자체 Debug2Fix 프레임워크가 일부 사례에서 기준선(baseline) 수치 대비 20% 이상 성능을 향상했다고 보고합니다. 이 두 가지 한정 조건('기준선에 대한 상대적'이며 '일부 사례에 적용됨')을 모두 보존해야 합니다. 이를 일반적인 약속, 자체 구현을 위한 벤치마크 결과, 또는 디버거 추가로 인한 보장된 개선 사항으로 변환해서는 안 됩니다.
논문에서 명시한 한계점은 어느 정도까지 일반화할지 결정하는 데 중요합니다. 해당 평가는 Python과 Java를 다루었으며, 각 언어에 대해 하나의 벤치마크를 사용했습니다. 저자들은 C, C++, C#, Rust를 포함하여 성숙한 생태계를 가진 다른 언어에서는 이 접근 방식을 시도하지 않았다고 언급합니다. 그들은 추가적인 언어와 벤치마크를 향후 연구 과제(future work)로 지정합니다. 따라서 이 접근 방식을 다른 언어에 적용하는 팀은 보고된 결과가 전이된다고 가정하기보다는 자체 평가를 수행해야 합니다.