Отладка агентов с помощью Agent Inspector в Microsoft Foundry Toolkit

Инспектор агента в Microsoft Foundry Toolkit для Visual Studio Code позволяет отправлять запросы локальному агенту, проверять активность модели и инструментов и отлаживать код. Используйте его для изучения неожиданных ответов перед развертыванием изменения.

Этот рабочий процесс полезен для размещённых агентов, которые запускают пользовательский код в службе агента Foundry. Локальная инспекция помогает отлаживать этот код. Перед использованием в рабочей среде также проверьте развернутый агент с его идентификационными данными среды выполнения, конфигурацией и сетевым доступом.

В этой статье вы подключитесь к локальному агенту, изучите запрос и сохраните диагностические события. Основной путь использует протокол Responses. Доступные представления зависят от протокола и диагностики, предоставляемых сервером агента.

Prerequisites

• Visual Studio Code с текущим расширением Foundry Toolkit. См. раздел Install Foundry Toolkit.
• Проект локального агента с уже настроенными зависимостями, конфигурацией модели и учетными данными. Чтобы начать с примера, следуйте краткому руководству по размещенному агенту, включая локальное тестирование.
• Отладчик, необходимый для проекта. В примере Python используется расширение Python и debugpy. Другие языки и примеры имеют разные требования.

Для существующего проекта средства Foundry Toolkit Copilot tools могут помочь подготовить конфигурацию. Просмотрите созданные файлы и следуйте проекту README.md. Не заменяйте его файлы запуска на универсальную конфигурацию.

Important

Локальный агент может вызывать облачные модели и инструменты в реальном времени. Используйте нечувствительные тестовые входные данные, проверьте разрешения средства и учитывайте расходы от настроенных служб. Инспектор не заменяет инструменты мок-объектами.

Подключиться и отладить

Запустите сервер агента перед тем, как вы подключите Inspector. Используйте созданную конфигурацию запуска проекта для согласования сервера, рабочего каталога, интерпретатора и отладчика.

1. Запустите агент с задокументированной конфигурацией отладки. Для примера Python размещенного агента выберите Debug Local Agent HTTP Server и нажмите клавишу F5.
2. Если инспектор не открыт, выберите Foundry Toolkit на панели действий, а затем средства разработчика>>инспектор агента.
3. Проверьте эндпоинт в заголовке Инспектора. Текущий каркас Python использует http://localhost:8088. Для другого порта сервера нажмите кнопку карандаша рядом с эндпоинтом, введите порт и нажмите кнопку "Подключить".
4. Убедитесь, что заголовок отображает Подключено. Инспектор автоматически обнаруживает протокол ответов или вызовов, когда конечная точка доступна.
5. Установите точку останова в коде агента и отправьте сообщение в Playground. Проверьте переменные при приостановке выполнения, а затем продолжайте и просмотрите ответ.

Открытие инспектора не запускает сервер и не присоединяет отладчик. Созданная Python конфигурация использует порт 5679 для отладчика и порта 8088 для HTTP-запросов агента. Эти порты отделены от портов трассировки OTLP.

Подключение к универсальному эндпоинту Responses

Инспектор может подключаться к локальной конечной точке Responses endpoint без полного интерфейса диагностики разработки. Вы можете проверить события Responses, отправляемые сервером, но граф рабочего процесса и его входное и выходное представление недоступны.

Успешное подключение не означает, что сервер предоставляет местоположения источника, использование токенов или рассуждения.

Отправка вызова HTTP

Используйте вызовы HTTP, когда агент принимает пользовательское тело запроса, а не беседное сообщение. Формат запроса и протокол ответа сервера определяют, как Inspector отправляет и отображает результат.

1. Подключитесь к запущенному серверу вызовов HTTP. Инспектор автоматически обнаруживает протокол.
2. Введите тело запроса, необходимое вашему агенту. Если сервер предоставляет совместимую спецификацию OpenAPI, инспектор может подставить пример. Просмотрите его перед отправкой или следуйте формату запроса из примера, если пример недоступен.
3. Выберите значок шестерёнки Request settings рядом с полем ввода, чтобы задать Content-Type и Accept в соответствии с требованиями сервера. Например, используйте application/json для тела JSON и text/event-stream, когда сервер поддерживает потоковый ответ.
4. Выберите Отправить и проверьте состояние ответа и текст.
5. Переключайтесь между Предпросмотром для отформатированного вывода и Raw для ответа в исходном виде. Панель сведений также включает I/O и вызовы LLM. Сведения о модели, инструменте и токене зависят от распознанных событий сервера, поэтому не каждый ответ заполняет каждую вкладку.

Инспектор обрабатывает обычный HTTP-ответ, поток событий Server-Sent Events (SSE) или асинхронный ответ. При асинхронном ответе 202 Accepted он опрашивает вызов до завершения или сбоя. Выбор формата ответа не добавляет потоковую или асинхронную поддержку вашему серверу.

Для потокового ответа Stop отключает поток клиента. При опрашиваемом вызове Отмена отправляет запрос на отмену серверу. Ни одно из действий не гарантирует, что процесс агента или операция внешнего средства остановлена.

Это представление не является клиентом WebSocket. Примеры Activity Protocol используют другую песочницу. См. Выберите другой протокол или пример, чтобы выбрать подходящий способ локального тестирования.

Как использовать Инспектор

Начните с запроса, который проверяет поведение, которое вы хотите понять. Например, для погодного инструмента запрашивайте информацию, требующую этого инструмента, а не общий ответ, который модель может дать без него.

1. Отправьте запрос в Playground и просмотрите потоковый ответ.
2. Используйте вкладки сведений для поиска медленной операции или операции с ошибкой.
3. Проверьте соответствующее событие или вызов инструмента, измените код или конфигурацию и повторите запрос.

Нажмите клавишу ВВОД , чтобы отправить или SHIFT+ВВОД , чтобы добавить новую строку. Чтобы вспомнить более ранний запрос, поместите курсор в начало поля ввода и нажмите клавишу СТРЕЛКА ВВЕРХ. Нажмите клавишу Стрелка вниз в конце, чтобы перейти к новым запросам и вернуться в неотправленный черновик.

Перед отправкой запроса можно изменить отозванный запрос. Журнал входных данных — это удобная функция в Inspector, а не устойчивое хранилище сохраненных промптов.

View	Используйте его для
Overview	Проследите диаграмму задержек и упорядоченную временную шкалу запусков. Выберите все запуски или один запуск, чтобы отличить модель и действие инструмента от времени между запусками.
Токены	Просмотрите сведения об использовании входных и выходных токенов. Отсутствующие данные об использовании не являются результатом с нулевым количеством токенов.
Events	Проверьте проанализированные события Responses, включая ошибки, вызовы функций и результаты. Выполните поиск по типу события или содержимому JSON и фильтруйте по категориям.
Инструменты	Просмотр вызовов инструмента, сгруппированных по запуску ответа, включая состояние, идентификатор вызова, аргументы и результаты.

В нижнем колонтитуле ответа отображаются сведения о модели, длительности, использовании токенов и метке времени при указании. Текст и сводка по обоснованию отображаются в отдельных сворачиваемых разделах, когда агент выдает их. Инспектор не создает отсутствующее обоснование и не раскрывает информацию, которую поставщик модели не возвращает.

Проверить средства и разрешения

Используйте средства для проверки того, вызывается ли агент ожидаемым средством с ожидаемыми аргументами и получен результат. Успешный ответ модели не доказывает, что средство запущено. Если в коде используется мок, отображаемый результат по-прежнему является результатом мока.

Когда ответ приостанавливается для утверждения протокола MCP или согласия OAuth, ожидающие запросы отображаются над входными данными сообщения. Предоставьте только доступ, который вы планируете разрешить.

Для вызова средства MCP выберите "Показать аргументы", просмотрите входные данные и нажмите кнопку "Одобрить " или "Отклонить". Одобрить все и запретить все применяются к ожидающим запросам, а не к постоянной политике утверждения инструментов.

Для согласия OAuth выполните подтверждение авторизации браузера и инспектора:

1. Выберите "Открыть согласие" для ожидающего запроса.
2. Завершите авторизацию в браузере, вернитесь в инспектор и выберите Согласие получено. Чтобы отказаться от подтверждения, выберите Отмена вместо этого.
3. Устраните оставшиеся запросы на предоставление согласия. Используйте Все готово, если доступно, только после завершения утверждения для всех открытых запросов.

Само по себе открытие страницы согласия не возобновляет запрос. Инспектор ожидает принятия решения по каждому ожидающему согласию перед повторной проверкой сервера. Запросы могут повторно появляться, если серверу по-прежнему требуется авторизация.

Проверьте результат следующего инструмента, а не только подтверждение, чтобы подтвердить завершение. Сведения о настройке подключения и проверки подлинности см. в Каталоге инструментов. Не изменяйте учетные данные или разрешения средства только чтобы устранить диагностическую ошибку.

Проверьте рабочие процессы и исходный код

Для поддерживаемых рабочих процессов Microsoft Agent Framework сервер разработки может предоставлять диагностику рабочих процессов и расположение в исходном коде. Инспектор использует эти сведения для отображения графа выполнения и помогает перейти к коду.

1. Выберите узел рабочего процесса, чтобы проверить доступные входные и выходные данные.
2. Дважды щелкните узел, чтобы открыть его исходное расположение.
3. Задайте точку останова и повторите запрос для проверки операции в отладчике.

Вы можете протестировать рабочие процессы LangGraph в песочнице, но визуализация рабочих процессов для них не поддерживается. Сервер без метаданных рабочего процесса по-прежнему может возвращать полезные события ответа.

Исследуйте сбои с помощью Copilot

Используйте действия для ошибок в событиях, чтобы подготовить целенаправленный запрос для GitHub Copilot вместо копирования всей беседы.

1. Найдите событие со сбоем и просмотрите сведения о нем на наличие конфиденциального содержимого, прежде чем делиться ими.
2. Выберите Исправить рядом с событием сбоя, чтобы подготовить промпт для этого сбоя. Для нескольких сбоев сузьте список с помощью фильтров поиска и категорий, а затем выберите Устранить с помощью Copilot. Это действие включает видимые ошибки.
3. Перед отправкой просмотрите подготовленный запрос в GitHub Copilot Chat. Просмотрите все предложенные изменения, а затем повторно запустите исходный запрос агента, чтобы подтвердить результат.

Эти действия не требуют сборщика OTLP. Подготовка диагностического запроса не исправляет агент и не перезапускает неудачную операцию.

Сохранить события диагностики

Сохраните моментальный снимок события, чтобы сравнить сбой с последующим запуском или поделиться точным воспроизведением.

1. В событиях сузьте список с помощью поля поиска и фильтра категорий.
2. Выберите Копировать видимые события, чтобы скопировать отфильтрованные события в формате JSONL. В качестве альтернативы выберите Скачать видимые события, чтобы открыть экспорт в VS Code.
3. Для открытого экспортированного файла используйте Файл>, чтобы сохранить копию в месте, к которому у вас есть доступ, перед закрытием документа. Открытый файл экспорта — это временный файл, а не постоянная загрузка.

Моментальный снимок содержит события, видимые при выборе действия, а не будущие события от запущенного агента. Он не сохраняет версию агента, не развертывает код и не создает журнал облачной трассировки.

Caution

События могут включать подсказки, ответы, аргументы инструментов, результаты и сведения об ошибке. Перед сохранением или предоставлением общего доступа к экспорту просмотрите и скройте конфиденциальные данные.

Начать новую беседу

Выберите Очистить чат, чтобы начать новую беседу и очистить состояние чата, событий и сведений. Сначала экспортируйте все нужные события диагностики. При обновлении того же подключенного агента сохраняется состояние инспектирования, при этом смена агента очищает устаревшее состояние.

Для ответов Clear Chat отключена, пока ответ генерируется в реальном времени. Она остается доступной при приостановке хода для утверждения или согласия. Это не универсальная команда для остановки агента.

Не полагайтесь на локальное состояние инспектора в качестве надежного архива диалогов. Сервер владеет сохраняемостью бесед, которая может отличаться от локальной разработки и развернутого размещенного агента. Очистка инспектора не удаляет трассировки, уже собранные локально или хранящиеся в Application Insights.

Чем различаются Inspector и трассировка

Инспектор взаимодействует с вашим локальным сервером по протоколу HTTP и потоково передает события ответа. Совместимый сервер разработки также предоставляет отдельный поток диагностики для сведений о рабочем процессе и навигации по исходному коду. Отладчик подключается к вашему запущенному процессу независимо.

Для этой динамической диагностики не требуется локальный сборщик OTLP. Вкладка инспектора "Трассировка" открывает отдельное средство просмотра трассировки. Это не превращает события протокола в сохранённые спаны OpenTelemetry.

Чтобы собрать спаны для последующего анализа, настройте локальную трассировку. Для развернутых агентов используйте трассировки размещенных агентов.

После локального тестирования разверните размещенный агент. Протестируйте его отдельно, так как его идентификатор, среда и сетевой доступ отличаются от вашего локального процесса.

Troubleshooting

Issue	Что требуется проверить
Инспектор не может подключиться.	Проверьте терминал агента на наличие ошибок запуска. Подтвердите интерпретатор, зависимости и ПОРТ HTTP, а затем повторно подключитесь к порту, о котором сообщает сервер. При открытии инспектора процесс не запускается.
Запрос завершается успешно, но точки останова не срабатывают.	Убедитесь, что отладчик подключен к процессу, обслуживающему запрос, и использует правильный исходный каталог. Сведения о Python см. в отладке и устранении неполадок.
Отсутствует навигация по графику или исходному коду.	Убедитесь, что сервер и рабочий процесс предоставляют диагностику разработки и местоположения в исходном коде. Проверка Generic Responses не предоставляет эти возможности. Рабочие процессы LangGraph работают в песочнице без визуализации рабочих процессов.
Отсутствуют результаты инструмента.	Проверьте события на наличие сбоев и ожидающих согласований. Убедитесь, что для запроса требуется инструмент, и что инструмент настроен и доступен.
Отсутствуют сведения о токене или деталях обоснования.	Проверьте, что модель и сервер выдают. Инспектор может отображать только предоставленные ему сведения.
Внешние изображения заблокированы.	Выберите Загрузить удалённые изображения только если требуется, чтобы Inspector извлекал их из удалённых узлов. Это разрешение на отображение не является одобрением инструмента. Неподдерживаемые URL-адреса или содержимое по-прежнему могут не загружаться. Отсутствующее изображение не обязательно означает, что запрос агента завершился сбоем.
Поток ответов прерван.	Просмотрите сведения о частичном ответе и сведения о сбое. Повторно подключитесь при необходимости и просмотрите ожидающие утверждения перед повторной попыткой. Повторная попытка может повторить действия инструмента в реальном времени.
Инспектор имеет события, но средство просмотра трассировки пусто.	События протокола и спаны OTLP отличаются. Настройте инструментирование и запустите сборщик.

Связанные материалы

• Соберите и проверьте трассировки в Foundry Toolkit.
• Создайте рабочие процессы размещенного агента в VS Code.
• Запустите инспектор агента на основе браузера с помощью интерфейса командной строки разработчика Azure.