Visual Studio Code Microsoft Foundry Toolkit의 에이전트 검사기를 사용하면 로컬 에이전트에 요청을 보내고, 모델 및 도구 작업을 검사하고, 코드를 디버그할 수 있습니다. 변경을 배포하기 전에 예기치 않은 응답을 조사하는 데 사용합니다.
이 워크플로는 Foundry Agent Service에서 사용자 지정 코드를 실행하는 호스트된 에이전트에 유용합니다. 로컬 검사를 통해 해당 코드를 디버그할 수 있습니다. 실제 운영 환경에 사용하기 전에 배포된 에이전트의 런타임 ID, 구성 및 네트워크 액세스 권한을 테스트하세요.
이 문서에서는 로컬 에이전트에 연결하고, 요청을 조사하고, 진단 이벤트를 저장합니다. 주 경로는 Responses 프로토콜을 사용합니다. 사용 가능한 보기는 에이전트 서버에서 제공하는 프로토콜 및 진단에 따라 달라집니다.
Prerequisites
- Visual Studio Code에 현재 공개된 Foundry Toolkit 확장 프로그램이 설치되어 있습니다. Foundry 도구 키트 설치를 참조하세요.
- 종속성, 모델 구성 및 자격 증명이 설정된 로컬 에이전트 프로젝트입니다. 샘플에서 시작하려면 로컬 테스트까지 호스팅된 에이전트 빠른 시작을 따르세요.
- 프로젝트에 필요한 디버거입니다. Python 샘플에서는 Python 확장 및
debugpy확장을 사용합니다. 다른 언어 및 샘플에는 서로 다른 요구 사항이 있습니다.
기존 프로젝트의 경우 Foundry 도구 키트 Copilot 도구를 사용하여 구성을 준비할 수 있습니다. 생성된 파일을 검토하고 프로젝트의 README.md을(를) 따르세요. 해당 실행 파일을 일반적인 구성 파일로 교체하지 마세요.
Important
로컬 에이전트는 클라우드 모델 및 라이브 도구를 호출할 수 있습니다. 중요하지 않은 테스트 입력을 사용하고, 도구 사용 권한을 확인하고, 구성된 서비스의 요금을 고려합니다. 인스펙터는 도구를 모의 개체로 대체하지 않습니다.
연결 및 디버깅
Inspector를 연결하기 전에 에이전트 서버를 시작하세요. 프로젝트에서 생성된 시작 구성을 사용하여 서버, 작업 디렉터리, 인터프리터 및 디버거를 일치시키세요.
- 에이전트를 문서에 설명된 디버그 설정으로 시작하세요. 호스팅된 에이전트 Python 샘플의 경우 Debug Local Agent HTTP Server를 선택하고 F5를 누릅니다.
- 검사기가 열려 있지 않으면 작업 표시줄에서 Foundry Toolkit을 선택한 다음 개발자 도구>빌드>에이전트 검사기를 선택합니다.
- Inspector 헤더에서 엔드포인트를 확인하세요. 현재 Python 스캐폴드는
http://localhost:8088를 사용합니다. 다른 서버 포트의 경우 엔드포인트 옆에 있는 연필 단추를 선택하고 포트를 입력한 다음 연결을 선택합니다. - 헤더에 연결됨이 표시되는지 확인합니다. Inspector는 엔드포인트에 도달 가능할 때 응답 또는 호출 프로토콜을 자동으로 감지합니다.
- 에이전트 코드에서 중단점을 설정하고 플레이그라운드에서 메시지를 보냅니다. 실행이 일시 중지되면 변수를 검사한 다음, 계속한 다음 응답을 검토하세요.
검사기만 열어서는 서버가 시작되거나 디버거가 연결되지 않습니다. 생성된 Python 구성은 디버거에 포트 5679를 사용하고 에이전트 HTTP 요청에는 포트 8088을 사용합니다. 이러한 포트는 OTLP 추적 포트와는 별개입니다.
제네릭 응답 엔드포인트에 연결
검사기는 전체 개발 진단 인터페이스 없이 로컬 제네릭 응답 엔드포인트에 연결할 수 있습니다. 서버에서 보내는 응답 이벤트를 검사할 수 있지만 워크플로 그래프와 해당 입력 및 출력 뷰는 사용할 수 없습니다.
연결이 성공한다고 해서 서버가 원본 위치, 토큰 사용 또는 추론을 제공하는 것은 아닙니다.
HTTP 호출 보내기
에이전트가 대화형 메시지 대신 사용자 지정 요청 본문을 수락하는 경우 HTTP 호출을 사용합니다. 서버의 요청 형식과 응답 프로토콜에 따라 인스펙터가 결과를 전송하고 표시하는 방식이 결정됩니다.
- 실행 중인 HTTP 호출 서버에 연결하세요. 검사기가 프로토콜을 자동으로 감지합니다.
- 에이전트에서 필요한 요청 본문을 입력합니다. 서버가 호환되는 OpenAPI 사양을 노출하는 경우 검사기가 예제를 채울 수 있습니다. 보내기 전에 내용을 검토하거나, 예시가 없는 경우 샘플 요청 형식을 따르세요.
- 입력 옆에 있는 요청 설정 기어를 선택하여 서버에서 요구하는 대로 Content-Type 및 Accept 를 설정합니다. 예를 들어
application/json을(를) JSON 본문에 사용하거나 서버가 스트리밍 응답을 지원하는 경우text/event-stream을(를) 사용하세요. - 보내기를 선택하고 응답 상태 및 본문을 검사합니다.
- 형식화된 출력을 보려면 미리 보기 모드로, 기본 응답을 보려면 원본 모드로 전환하세요. 세부 정보 창에는 I/O 및 LLM 호출도 포함됩니다. 모델, 도구 및 토큰 세부 정보는 인식된 서버 이벤트에 따라 달라지므로 모든 응답이 모든 탭을 채우는 것은 아닙니다.
인스펙터는 일반 HTTP 응답, 서버에서 전송된 이벤트 스트리밍 또는 비동기 응답을 처리합니다. 비동기 202 Accepted 응답의 경우, 완료 또는 실패할 때까지 호출을 지속적으로 확인합니다. 응답 형식을 선택하면 서버에 스트리밍 또는 비동기 지원이 추가되지 않습니다.
스트리밍 응답의 경우, 중지를 누르면 클라이언트 스트리밍 연결이 해제됩니다. 폴링된 호출의 경우 취소 는 서버에 취소 요청을 보냅니다. 두 작업 모두 에이전트 프로세스 또는 외부 도구 작업이 중지되었음을 보장하지 않습니다.
이 보기는 WebSocket 클라이언트가 아닙니다. 활동 프로토콜 샘플은 다른 환경을 사용합니다. 적절한 현지 검사 경로를 확인하려면 다른 프로토콜 또는 샘플 선택을 참조하세요.
인스펙터 사용
이해하려는 동작을 유도하는 요청으로 시작합니다. 예를 들어 날씨 도구를 사용하는 경우, 해당 도구 없이도 모델이 생성할 수 있는 일반적인 응답이 아니라, 해당 도구가 필요한 정보를 요청해야 합니다.
- 플레이그라운드에서 요청을 보내고 스트리밍 응답을 검토합니다.
- 세부 정보 탭을 사용하여 느리거나 실패한 작업을 찾습니다.
- 관련 이벤트 또는 도구 호출을 검사하고, 코드 또는 구성을 변경하고, 요청을 반복합니다.
전송하려면 Enter 키를 누르고, 줄 바꿈을 추가하려면 Shift+Enter 키를 누르세요. 이전에 입력한 내용을 불러오려면 커서를 입력 시작 부분에 놓고 위쪽 화살표 키를 누르세요. 맨 아래에 있는 아래쪽 화살표를 눌러 최신 요청으로 이동하거나 전송하지 않은 초안으로 돌아갈 수 있습니다.
회수된 요청을 보내기 전에 편집할 수 있습니다. 입력 기록은 저장된 프롬프트를 영구적으로 보관하는 저장소가 아니라 Inspector 내의 편의 기능입니다.
| 보기 | 이를 사용하여 |
|---|---|
| Overview | 지연 시간 워터폴 및 순서가 지정된 실행 타임라인을 따라가세요. 실행 결과를 모두 선택하거나 하나의 실행 결과를 선택하여 모델 및 도구 활동과 실행 간 시간 간격을 구분할 수 있습니다. |
| 토큰 | 보고된 입력 및 출력 토큰 사용량을 검토합니다. 사용량 현황 데이터가 누락된 것은 토큰 수가 0인 결과가 아닙니다. |
| Events | 오류, 함수 호출 및 결과를 포함하여 구문 분석된 응답 이벤트를 검사합니다. 이벤트 유형 또는 JSON 콘텐츠를 검색하고 범주별로 필터링합니다. |
| Tools | 상태, 호출 ID, 인수 및 결과를 포함하여 응답 실행별로 그룹화된 도구 호출을 검사합니다. |
응답 바닥글은 제공된 경우 모델, 기간, 토큰 사용량 및 타임스탬프 정보를 표시합니다. 에이전트가 추론 내용을 출력할 때, 추론 텍스트와 추론 요약은 접을 수 있는 별도의 섹션으로 표시됩니다. 검사기는 누락된 추론을 생성하거나 모델 공급자가 반환하지 않는 정보를 노출하지 않습니다.
도구 및 권한 검토
도구를 사용하여 에이전트가 예상 인수를 사용하여 예상 도구를 호출하고 결과를 받았는지 확인합니다. 성공적인 모델 응답은 도구가 실행되었다는 것을 증명하지 않습니다. 코드에서 모의 개체를 사용하는 경우 표시된 결과는 여전히 모의 결과입니다.
응답이 MCP(모델 컨텍스트 프로토콜) 승인 또는 OAuth 동의를 기다리며 일시 중지되면 보류 중인 요청이 메시지 입력 위에 표시됩니다. 허용하려는 액세스 권한만 부여합니다.
MCP 도구 호출의 경우 인수 표시를 선택하고 입력을 검토한 다음 승인 또는 거부를 선택합니다. 모두 승인 및 모두 거부는 영구 도구 승인 정책이 아닌 보류 중인 요청에 적용됩니다.
OAuth 동의의 경우 브라우저 권한 부여 및 Inspector 확인을 모두 완료합니다.
- 보류 중인 요청에 대해 동의 공개를 선택하세요.
- 브라우저에서 권한 부여를 완료하고 검사기로 돌아가 동의 완료를 선택합니다. 승인을 거부하려면 취소를 선택하세요.
- 나머지 동의 요청을 해결하세요. 열려 있는 모든 요청에 대한 권한 부여를 완료한 후에만 사용 가능한 경우 모두 완료를 사용합니다.
동의 페이지를 여는 것만으로는 요청이 재개되지 않습니다. 담당자는 각 승인 건에 대한 결정이 나올 때까지 기다린 후 서버를 다시 확인합니다. 서버에 여전히 권한 부여가 필요한 경우 요청이 다시 나타날 수 있습니다.
승인뿐만 아니라 후속 도구 결과를 확인하여 완료 여부를 확인하세요. 연결 및 인증 설정은 도구 카탈로그를 참조하세요. 진단 오류가 사라지도록 도구 자격 증명 또는 사용 권한만 변경하지 마세요.
워크플로 및 소스 코드 검사
지원되는 Microsoft Agent Framework 워크플로의 경우 개발 서버는 워크플로 진단 및 원본 위치를 제공할 수 있습니다. 인스펙터는 이 정보를 사용하여 실행 그래프를 표시하고 코드 위치로 이동할 수 있도록 도와줍니다.
- 워크플로 노드를 선택하여 사용 가능한 입력 및 출력을 검사합니다.
- 노드를 두 번 클릭하여 원본 위치를 엽니다.
- 중단점을 설정하고 요청을 반복하여 디버거에서 작업을 검사합니다.
플레이그라운드에서 LangGraph 워크플로를 테스트할 수 있지만 LangGraph 워크플로에는 워크플로 시각화가 지원되지 않습니다. 워크플로 메타데이터가 없는 서버는 여전히 유용한 응답 이벤트를 반환할 수 있습니다.
Copilot을 사용하여 오류 조사
전체 대화를 복사하는 대신 이벤트의 오류 처리 기능을 사용하여 GitHub Copilot에 대한 집중적인 요청을 준비하세요.
- 실패한 이벤트를 찾아 공유하기 전에 세부 정보를 검토하여 민감한 콘텐츠가 포함되어 있는지 확인하세요.
- 실패한 이벤트 옆에 있는 수정을 선택하여 해당 실패에 대한 프롬프트를 준비하세요. 몇 가지 오류가 발생한 경우 검색 및 범주 필터를 사용하여 목록의 범위를 좁히고 Copilot 사용하여 해결을 선택합니다. 이 조치에는 눈에 보이는 실패 사례들이 포함됩니다.
- 메시지를 보내기 전에 GitHub Copilot 채팅에서 준비된 메시지를 검토하세요. 제안된 변경 내용을 검토한 다음 원래 에이전트 요청을 다시 실행하여 결과를 확인합니다.
이러한 작업에는 OTLP 수집기가 필요하지 않습니다. 진단 프롬프트를 준비해도 에이전트가 수정되거나 실패한 작업이 다시 실행되지 않습니다.
진단 이벤트 저장
이벤트 스냅샷을 저장하여 오류를 이후 실행 결과와 비교하거나, 오류 재현에 대한 구체적인 정보를 공유할 수 있습니다.
- 이벤트에서 검색 필드 및 범주 필터를 사용하여 목록의 범위를 좁힐 수 있습니다.
- 표시되는 이벤트 복사를 선택하여 필터링된 이벤트를 JSONL로 복사합니다. 또는 표시되는 이벤트 다운로드를 선택하여 VS Code에서 내보내기 파일을 열 수 있습니다.
- 열려 있는 내보내기 파일의 경우, 문서를 닫기 전에 파일>다른 이름으로 저장을 사용하여 사용자가 지정한 위치에 사본을 저장하세요. 열어본 내보내기 파일은 임시 파일이며, 영구 다운로드 파일이 아닙니다.
스냅샷에는 실행 중인 에이전트의 이후 이벤트가 아니라 작업을 선택할 때 표시되는 이벤트가 포함됩니다. 에이전트 버전을 저장하거나, 코드를 배포하거나, 클라우드 추적 기록을 만들지 않습니다.
주의
이벤트에는 프롬프트, 응답, 도구 인수, 결과 및 오류 세부 정보가 포함될 수 있습니다. 내보내기 파일을 저장하거나 공유하기 전에 민감한 내용을 검토하고 수정하세요.
새 대화 시작
채팅 지우기를 선택하면 새 대화가 시작되고 채팅, 이벤트 및 세부 정보 상태가 지워집니다. 먼저 필요한 진단 이벤트를 내보내세요. 동일한 연결된 에이전트를 새로 고침하면 검사 상태가 유지되고 에이전트를 변경하면 오래된 상태가 지워지게 됩니다.
응답의 경우 응답이 적극적으로 스트리밍되는 동안 Clear Chat을(를) 사용할 수 없습니다. 턴이 승인 또는 동의를 위해 일시 중지되는 경우에도 여전히 사용 가능합니다. 이는 에이전트를 중지하라는 일반적인 명령이 아닙니다.
로컬 인스펙터의 업무를 신뢰할 수 있는 대화 기록 보관소로 여기지 마세요. 서버는 대화 지속성을 관리하며, 이는 로컬 개발 환경과 배포된 호스팅 에이전트 간에 다를 수 있습니다. 클리어링 인스펙터는 이미 로컬에 수집되었거나 Application Insights에 저장된 트레이스 정보를 삭제하지 않습니다.
Inspector와 추적의 차이점
Inspector는 HTTP를 통해 로컬 서버와 통신하고 응답 이벤트를 스트리밍합니다. 호환되는 개발 서버는 워크플로 세부 정보 및 원본 탐색을 위한 별도의 진단 스트림도 제공합니다. 디버거는 실행 중인 프로세스에 독립적으로 연결됩니다.
이러한 라이브 진단에는 로컬 OTLP 수집기가 필요하지 않습니다. 검사자의 추적 탭이 별도의 추적 뷰어를 엽니다. 프로토콜 이벤트를 저장된 OpenTelemetry 스팬으로 전환하지 않습니다.
추후 분석을 위해 스팬을 수집하려면 로컬 트레이싱을 구성하세요. 배포된 에이전트의 경우 호스팅된 에이전트 추적을 사용합니다.
로컬 테스트 후 호스트된 에이전트를 배포합니다. 로컬 프로세스와 ID, 환경 및 네트워크 액세스 권한이 다르므로 별도로 테스트하세요.
Troubleshooting
| Issue | 확인할 사항 |
|---|---|
| 인스펙터가 연결할 수 없습니다. | 에이전트 터미널에서 시작 시 오류를 확인하십시오. 인터프리터, 종속성 및 HTTP 포트를 확인한 다음 서버에서 보고하는 포트에 다시 연결합니다. 오프닝 인스펙터가 프로세스를 시작하지 않습니다. |
| 요청은 성공했지만 설정한 중단점에 도달하지 않았습니다. | 디버거가 요청을 처리하는 프로세스에 연결되어 있고 올바른 원본 디렉터리를 사용하는지 확인하세요. Python의 경우 디버깅 문제 해결을 참조하세요. |
| 그래프 또는 소스 탐색 기능이 없습니다. | 서버 및 워크플로가 개발 진단 및 원본 위치를 제공하는지 확인합니다. 일반 응답 검사에서는 이러한 기능을 제공하지 않습니다. LangGraph 워크플로는 워크플로 시각화 없이 플레이그라운드에서 작동합니다. |
| 도구 결과가 없습니다. | 실패 및 보류 중인 승인이 있는지 이벤트를 확인합니다. 요청에 도구가 필요한지, 그리고 해당 도구가 구성되어 있고 접근 가능한지 확인하세요. |
| 토큰 또는 추론 세부 정보가 없습니다. | 모델과 서버에서 출력되는 내용을 확인하세요. 인스펙터는 자신이 제공한 정보만 표시할 수 있습니다. |
| 원격 이미지가 차단되었습니다. | 인스펙터가 원격 호스트에서 이미지를 가져오도록 하려면 원격 이미지 로드 옵션만 선택하세요. 이 표시 권한은 도구 승인이 아닙니다. 지원되지 않는 URL 또는 콘텐츠는 여전히 로드에 실패할 수 있습니다. 누락된 이미지가 반드시 에이전트 요청이 실패했음을 의미하지는 않습니다. |
| 응답 스트림이 중단됩니다. | 부분 응답 및 실패 세부 정보를 검토합니다. 필요한 경우 다시 연결하고 다시 시도하기 전에 보류 중인 승인을 검토합니다. 재시도는 라이브 도구 작업을 반복할 수 있습니다. |
| 인스펙터에는 이벤트가 있지만 추적 뷰어는 비어 있습니다. | 프로토콜 이벤트와 OTLP 스팬은 다릅니다. 계측을 구성하고 수집기를 시작합니다. |