agents-debug

AWS AgentCore agents-debug — это диагностический навык для случаев, когда агент или окружение работает неправильно: возвращает ошибку или неверный ответ, не укладывается в timeout, не выполняет tool call, не видит логи или не запускается AgentCore CLI. Источник прямо отделяет его от соседних задач: ошибки deployment относятся к agents-deploy, создание проекта — к agents-get-started, измерение качества и настройка мониторинга — к agents-optimize. Поэтому карточку стоит открывать после появления симптома, а не как универсальное руководство по развёртыванию или оценке агента. Входной аргумент необязателен. Без него навык предлагает интерактивно описать проблему; дополнительные варианты уточняют направление: traces для разбора последних трасс, logs для поиска ошибок, memory для проблем с воспоминаниями, doctor для проверки prerequisites. Такой выбор полезен тем, что диагностический маршрут начинается с симптома, а не с предположения о причине. Перед разбором поведения инструкция требует проверить версию командой agentcore --version: навык рассчитан на CLI 0.9.0 или новее, а устаревший CLI следует обновить. Основной процесс читает данные напрямую. Сначала определяется, относится ли проблема к CLI и окружению или к поведению агента. Затем навык просит не пересказывать логи вручную, а получить traces и записи CloudWatch командами agentcore traces list, agentcore traces get и agentcore logs с фильтрами по уровню или запросу. Если имя runtime неизвестно, его можно взять из agentcore/agentcore.json. Источник отмечает задержку примерно десять секунд между появлением span и доступностью trace или eval; сразу после вызова нужно учитывать это окно, а не объявлять данные отсутствующими. Для ошибок доступа к модели проверяются несколько независимых причин. Модель могла быть не включена в Bedrock Model access для нужного региона; роль исполнения может не иметь bedrock:InvokeModel; географический inference profile может требовать доступ во всех регионах, куда он маршрутизирует запрос. Инструкция различает префиксы us., eu., apac. и global. и предупреждает, что поддержка профиля зависит от конкретной модели. Это не разрешает угадать нужный регион: доступ и список целевых регионов нужно подтвердить в AWS. Для failing tool call навык предлагает сначала найти ошибку в trace, затем проверить gateway и доступ через agentcore status и agentcore fetch access. Локальный agentcore dev может не иметь gateway URL до deployment — это ожидаемое ограничение, которое агент должен обработать. Для auth failure проверяется credential, для Lambda — её логи, для policy denial — журнал решения policy engine. Если ответ агента неправильный или бесполезный, trace помогает проверить выбор инструментов, результат tool call и системный prompt; отдельно рассматриваются неподходящая модель и неожиданный формат данных. Разделы про memory, timeout, quota и локальный запуск продолжают тот же принцип: сначала подтверждается конкретный симптом и его след в trace или log, затем проверяются prerequisite и ограничение платформы. Для LTM нужно убедиться в стратегиях и статусе memory, после завершения сессии дать время асинхронному извлечению и использовать UUID-подобные session ID. Для cold start, maxVms, connection refused, 424, streaming disconnects, merged traces и отсутствующих CloudWatch logs источник предлагает отдельные диагностические проверки. Навык не исправляет инфраструктуру автоматически: его результатом является объяснение причины и следующий проверяемый шаг, поэтому permissions, регион, квоты, runtime и фактические логи должны быть подтверждены в конкретном окружении.