에디터를 떠나지 않고 Azure AI Foundry 에이전트를 디버깅하기 위한 VS Code 확장 프로그램 제작

요약 (TL;DR): 저는 Foundry Trace Inspector를 제작했습니다. 이는 Azure AI Foundry 에이전트의 트레이스 (trace)를 대화형 타임라인 형태로 에디터에 가져오는 무료 오픈 소스 VS Code 확장 프로그램입니다. 포털을 전환하거나 임시 스크립트를 작성할 필요가 없습니다.

문제점

Azure AI Foundry는 정말 훌륭한 포털을 갖추고 있습니다. 에이전트 실행, 호출된 도구 (tools), 주고받은 메시지, 심지어 토큰 사용량 분석까지 모두 깔끔한 UI에서 확인할 수 있습니다.

하지만 로컬에서 에이전트를 구축할 때 실제로 일어나는 일은 다음과 같습니다:

코드를 작성하고 실행을 트리거합니다.
브라우저로 전환하여 Foundry 포털을 엽니다.
프로젝트 → 에이전트 → 트레이스 (Traces) 탭으로 이동합니다.
적절한 실행 기록을 찾습니다.
클릭하여 어떤 일이 일어났는지 확인합니다.
수정을 위해 다시 VS Code로 전환합니다.
이 과정을 반복합니다.

이러한 컨텍스트 스위칭 (context switch)은 사소해 보일 수 있습니다. 하지만 시스템 프롬프트 (system prompt)를 수정하거나, 도구 호출 (tool call) 로직을 조정하거나, 에이전트가 왜 잘못된 하위 에이전트에게 업무를 넘겼는지 디버깅하는 등 빠르게 반복 작업을 수행할 때는 그 차이가 누적됩니다. 계속해서 주의력을 에디터에서 브라우저로, 다시 에디터로 옮겨야만 합니다.

제가 원했던 것은 간단했습니다: 작업 중인 바로 그 자리에서 트레이스 (trace)를 보는 것.

Foundry Trace Inspector가 하는 일

이 확장 프로그램은 Azure AI Foundry 프로젝트에 연결하여 모든 에이전트 실행에 대해 세 가지 뷰 (view)를 VS Code 패널 내부에서 제공합니다:

Trajectories — 전체 스팬 트리 (span tree)

전체 실행 과정을 보여주는 간트 차트 (Gantt-style) 형태의 접이식 트리입니다: 세션 (Session) → 에이전트 호출 (Invoke Agent) → 채팅 턴 (Chat turns) → 도구 호출 (Tool calls). 모든 스팬 (span)에는 지속 시간, 토큰 수, 비용이 표시됩니다. 스팬을 클릭하면 모델, 상태, 토큰 상세 내역, 원시 입력/출력 (raw input/output)이 포함된 상세 드로어 (detail drawer)가 열립니다.

이것은 제가 디버깅 중에 가장 많이 사용하는 뷰입니다. 한눈에 다음과 같은 사항을 확인할 수 있습니다: 도구 호출 (tool call)이 발생했는가? 얼마나 걸렸는가? LLM이 실제로 입력값으로 무엇을 받았는가?

사용자 뷰 (User View) — 읽기 쉬운 대화 재생

전체 대화의 채팅 버블 타임라인: 사용자 메시지와 어시스턴트 (assistant)의 답변이 사람이 읽는 방식 그대로 렌더링되며, 각 어시스턴트 턴에는 에이전트 이름과 모델이 표시됩니다. 각 어시스턴트 버블에는 사이드바의 해당 응답으로 즉시 이동하는 "View Trace" 버튼이 있어, "이 답변에 뭔가 이상한 점이 있다"고 느꼈을 때 클릭 한 번으로 원시 스팬 (raw span)으로 이동할 수 있습니다.

토큰 및 비용 차트 (Token & Cost chart)

스택형 막대 차트 (LLM 턴당 입력 vs 출력 토큰)를 통해 어떤 턴에서 가장 많은 토큰을 소모하는지 즉시 파악할 수 있습니다. 이는 멀티 턴 (multi-turn) 대화가 왜 비용이 많이 발생하는지 이해하려고 할 때 유용합니다.

소비된 입력 및 출력 토큰에 대한 스팬 (span)별 비용 상세 내역

내부 작동 원리

Azure AI Foundry 에이전트는 내부적으로 OpenAI Responses API를 사용합니다. 모든 에이전트 답변은 Foundry 포털의 Traces 탭에서 확인할 수 있는 resp_... 응답 ID를 생성합니다. 이 확장 프로그램은 동일한 API를 통해 해당 응답들을 직접 가져와 로컬에서 전체 대화 타임라인을 재구성합니다.

세션이 여러 턴(turn)에 걸쳐 진행될 때, 각 응답은 previous_response_id를 통해 이전 응답과 연결됩니다. 체인 내의 어떤 응답이든 로드하면 확장 프로그램이 자동으로 체인을 따라 이동하므로, 모든 ID를 수동으로 추적할 필요가 없습니다.

대화 ID (conv_...)는 저장된 응답에서 자동으로 검색되므로, 응답 하나만 추적하면 전체 대화가 나타납니다.

중간 서버 없음. 이 확장 프로그램은 사용자가 구성한 Azure 엔드포인트로만 API 호출을 수행합니다. API 키는 VS Code의 암호화된 SecretStorage에 저장되며, settings.json에 저장되지 않고 사용자의 기기를 절대 벗어나지 않습니다.

설정 방법

두 가지가 필요합니다:

Azure AI Foundry 프로젝트 엔드포인트 URL (Foundry 포털의 프로젝트 → 개요(Overview)에서 확인 가능)
API 키 또는 DefaultAzureCredential을 통한 Azure CLI 인증 (az login)

설정이 완료되면, 포털의 Traces 탭에서 conv_... 대화 ID를 가져와 사이드바에 붙여넣으세요. 그러면 확장 프로그램이 해당 대화의 모든 응답을 자동으로 가져옵니다.

향후 계획

v0.2 버전에 추가하고 싶은 몇 가지 기능입니다:

최근 실행 자동 검색 (Auto-discovery of recent runs) — ID를 수동으로 붙여넣는 대신, 패널에서 최근 대화를 직접 목록으로 표시
사이드 바이 사이드 차이 비교 (Side-by-side diff) — 동일한 에이전트의 두 실행을 비교하여 실행 간에 무엇이 변했는지 확인
Markdown으로 내보내기 (Export to Markdown) — PR(Pull Request)이나 장애 노트(incident note)에 붙여넣을 수 있는 읽기 쉬운 추적 보고서 생성

사용해 보기

Azure AI Foundry Agent Service를 기반으로 개발 중이라면, 설치해 보시고 의견을 들려주세요:

🔗 Foundry Trace Inspector 설치하기

설치하고 Foundry 프로젝트 엔드포인트(endpoint)를 붙여넣는 데 약 2분 정도 소요됩니다. 이 도구가 시간을 절약해 주었다면, Marketplace에서 ⭐ 별점 평점을 남겨주시는 것이 큰 도움이 됩니다.

피드백이 있거나, 버그를 발견했거나, 새로운 기능이 필요하다면 GitHub에 이슈(issue)를 생성해 주세요. 저는 이 프로젝트를 활발히 개발 중이며, 여러분의 개발 루프(dev loop)를 어떻게 하면 더 빠르게 만들 수 있을지에 대한 의견을 듣고 싶습니다.

추가 읽을거리

What is Foundry Agent Service? — 이 확장 프로그램이 연결되는 서비스에 대한 공식 개요
Use the Azure OpenAI Responses API — 확장 프로그램이 트레이스(trace) 데이터를 가져오는 기반 API
Microsoft Foundry Pricing — 에이전트 실행에 실제로 드는 비용 이해하기
VS Code Webview API — 타임라인 패널이 구축되는 방식
VS Code Extension API — 기여하거나 이를 기반으로 구축하고 싶을 경우를 위한 전체 레퍼런스