Устранение неполадок

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

В результате инструмента MCP код лежит в поле code, рядом с instruction. На /p/ ошибка приходит в полях error.code и error.instruction, а опрос завершённого неудачного вызова несёт error_code. API консоли отвечает полями error.code и error.request_id.

Найдите вызов

• У каждого вызова есть call_id, он начинается с sp_c_. Откройте https://my.sallyport.cloud/activity?call=<call_id>, чтобы его увидеть.
• В вызове видны «Агент», «Подключение», «Версия ключа», «Правило», «Журнал» и «Хронология» событий.
• Пишите в «Настройки», «Поддержка» и прикладывайте call_id, а для ошибки API консоли ещё и request_id.

Посмотрите, что именно отправил агент и что пришло в ответ

Откройте Историю вызовов, выберите вызов и нажмите «Открыть весь запрос и ответ». Вызов виден таким, каким он был, без скрытых частей.

• Запрос: метод, полный адрес, все заголовки и тело. Для SSH это команда, для файлов путь и содержимое, для базы данных запрос и его значения, для почты всё письмо.
• Заголовок, который агент прислал на месте ключа, например свой PRIVATE-TOKEN, остаётся в списке со своим значением, зачёркнутый, с пометкой «Заменён ключом подключения, не отправлен». Ключ, который подставил Sallyport, не показывается никогда.
• Ответ: статус, все заголовки и тело. Длинный ответ загружается целиком до 1 МиБ, а «Скачать весь ответ» сохраняет его полностью.
• Запросы хранятся столько же, сколько история вызовов, по умолчанию 180 дней. Ответы и тела запросов больше 1 МиБ хранятся 30 дней, после этого вызов так и пишет.

У агента нет инструментов нужного сервиса

• Попросите агента вызвать list_access. Он покажет все сервисы, доступные агенту, и что из них ждёт человека.
• Новый ключ получают все активные агенты его рабочего пространства и среды. Агент в тестовой среде не видит ключ рабочей среды.
• Подключение, убранное из списка «Доступ» агента, остаётся убранным. Верните его кнопкой «Добавить подключение».
• Если инструментов больше 40, инструменты удалённых MCP-серверов уходят из списка. Агент находит их через search_tools и вызывает через call.
• К хосту вне списка агент обращается через http_request. Первый вызов вернёт ссылку, по которой вы добавите ключ.

Коды ответа

Если сервис не ответил

UPSTREAM_ERROR с полем reason значит, что ответ не пришёл. side_effect равно none, если до сервиса ничего не дошло, и unknown, если могло дойти.

Ошибки запроса, которые исправляет человек

Большинство причин BAD_REQUEST исправляет сам агент, текст ответа говорит ему как. Эти требуют человека:

• not_https с console_url: адрес подключения начинается с http://. Смените его на https:// на странице подключения.
• mcp_binding, database_binding или email_binding: вызов через /p/ направлен на MCP-сервер, базу данных или почтовый ящик. Вызывайте их инструменты через MCP-адрес. sftp_operation: файловый вызов не называет одну операцию однозначно; в detail написано, что исправить.
• missing_host: подключение покрывает все хосты сервиса, поэтому вызов должен назвать один. На /p/ укажите хост сразу после ID подключения.

Ошибки API консоли

• FORBIDDEN называет нужную роль в details.required_role. Для экспорта журнала нужна роль владельца либо администратора или аудитора всей организации без более узкой роли в каком-либо рабочем пространстве.
• Ключ API не может ответить на карточку: решение принимает человек.
• VALIDATION_FAILED перечисляет неверные поля в details.fields.
• AUTH_FAILED значит, что сессия закончилась или ключ API отозван.

Замените ключ сервиса без перерыва

• Создайте у провайдера новый ключ, пока текущий ещё работает.
• Откройте ключ в разделе Ключи сервисов, нажмите «Заменить ключ сервиса», вставьте новое значение и нажмите «Сохранить новый ключ».
• Сделайте один вызов через Sallyport. Когда он пройдёт, отзовите старый ключ у провайдера.