DF-ИИ-031 · ИИ в работе команды
Свой клиент для ИИ-агента: что проверить в обвязке до запуска
- Минимальный контракт запроса к API агента: обязательные заголовки и версия
- Как отличить HTTP-ошибку от сетевого сбоя на примере fetch()
- Что писать в журнал клиента: идентификатор запроса и реакция на лимиты
- Чек-лист решений перед запуском собственного клиента
Свой клиент к API ИИ-агента обычно пишут за вечер: собрать запрос, отправить, показать ответ. А ломается он позже — на забытом заголовке версии, на ответе с ошибкой, который клиент принял за успех, или на потерянном идентификаторе запроса, без которого поддержка не найдёт след. Ниже — минимальные требования к обвязке и проверки, которые стоит пройти до запуска.
Это редакционный чек-лист Deskforge, а не отчёт об испытании продукта и не клиентский кейс: шаги нужно адаптировать к вашему стеку и вашему провайдеру. Примеры ниже опираются на документацию Claude API и MDN по Fetch API; у других провайдеров состав заголовков и коды ошибок отличаются, их нужно сверять по своей документации.
Смежная тема — из чего состоит ИИ-агент: выбор архитектуры и контроля, а варианты работ с ИИ собраны на странице автоматизации процессов.
Что клиент агента получает от API: минимальный контракт
Claude API — это RESTful API по адресу https://api.anthropic.com, который даёт программный доступ к моделям Claude и Claude Managed Agents. Для работы с ним нужен аккаунт Claude Console и API-ключ из Console либо настроенное правило Workload Identity Federation. То есть клиент — это не «чат с моделью», а HTTP-клиент с ключом, версией и форматом тела.
Отсюда первый вывод для обвязки: клиент должен уметь ровно то, что требует контракт API, — собрать запрос с нужными заголовками, отправить его, разобрать ответ и не потерять служебные поля. Всё остальное (интерфейс, история, кнопки) — надстройка, которая не спасает, если базовый запрос собран неверно.
Проверить это можно без запуска: вывести в отладочный лог полный набор заголовков и тело запроса и сверить с документацией API построчно. Если какого-то обязательного заголовка нет — клиент ещё не готов, каким бы аккуратным ни был интерфейс.
Заголовки, версия API и аутентификация: что проверить в запросе
Запросы к Claude API содержат заголовок anthropic-version с версией API, и этот заголовок обязателен. Значение версии в документации приведено как пример, поэтому актуальную версию нужно смотреть там же, а не брать из старой статьи или чужого кода.
Заголовок content-type со значением application/json тоже обязателен. Если клиент отправляет тело без него или с другим значением, сервер вправе не разобрать запрос так, как вы ожидаете, — и ошибка будет выглядеть загадочно.
Официальные клиентские SDK Anthropic автоматически отправляют заголовки аутентификации, версии и content-type. Заголовок anthropic-workspace-id при необходимости передаётся вручную. Это удобная развилка: если вы пишете обвязку сами, все эти заголовки — ваша ответственность; если берёте SDK, проверять нужно то, что SDK не делает за вас.
Практическая проверка: в отладочном выводе клиента сверить состав заголовков с документацией API. Отдельно — убедиться, что ключ не попадает в логи и в тексты ошибок, которые видит пользователь.
Ошибки и повторы: как отличить HTTP-ошибку от сетевого сбоя
Здесь чаще всего прячется настоящая ошибка. Метод fetch() возвращает Promise, который разрешается в Response, как только сервер ответил заголовками, — даже если статус ответа является HTTP-ошибкой. Проще говоря, fetch() не «падает» на ответе 4xx или 5xx: он успешно возвращает объект ответа, и если клиент не проверил статус, он обработает ошибку как нормальный ответ.
Метод fetch() принимает один обязательный аргумент — путь к ресурсу, который нужно получить. Всё остальное — опции запроса, и именно там задаются метод, заголовки и тело. Fetch API использует объекты Request и Response, а также связанные с сетевыми запросами понятия, включая CORS и семантику заголовка HTTP Origin.
Синтетический пример: два разных сбоя
Клиент отправляет запрос и получает ответ со статусом 413 и телом request_too_large — это HTTP-ошибка: сервер ответил, соединение работает, запрос слишком велик.
В другом прогоне ответа нет вовсе: соединение оборвалось или истёк таймаут — это сетевой сбой, и повторять запрос имеет смысл иначе, чем при 413. Если клиент в обоих случаях показывает одно и то же «что-то пошло не так», вы теряете главное — понимание, что именно произошло.
Проверка: подать в изолированной среде заведомо большой синтетический запрос и посмотреть, различает ли клиент ответ с ошибкой и отсутствие ответа. Это не отчёт об испытании продукта, а проверка собственной обвязки на синтетических данных.
Лимиты, токены и идентификаторы запросов в журнале клиента
Claude API применяет лимиты частоты запросов и лимиты расходов, организованные по уровням использования. В каждом уровне заданы максимальное число запросов в минуту (RPM) и максимальное число токенов в минуту (TPM). Конкретные значения зависят от уровня и в документации приведены отдельно — их нужно смотреть там, а не угадывать.
Для клиента это значит: при превышении лимита он не должен зацикливаться на повторах. Проверить это можно на синтетических данных в изолированной среде — например, искусственно ограничив число запросов и посмотрев, что клиент делает при отказе: ждёт, повторяет с паузой или бесконечно долбит сервер.
Ответы Claude API содержат заголовок request-id — глобально уникальный идентификатор запроса, который стоит указывать при обращении в поддержку по конкретному запросу. Клиент должен сохранять его в журнал вместе с запросом: без этого разбор инцидента превращается в переписку «а пришлите, что у вас было».
При превышении лимита размера запроса Claude API возвращает ошибку 413 request_too_large. Это отдельный случай, и клиент должен обрабатывать его отдельно — например, показать понятное сообщение и не повторять тот же запрос без изменений.
Чек-лист решений перед запуском клиента
Соберём проверки в один список. Он не заменяет документацию провайдера, но помогает не забыть то, что чаще всего теряется.
- Клиент отправляет обязательные заголовки запроса — версию API и content-type — и вы сверили их состав с документацией API в отладочном выводе.
- Клиент различает HTTP-ошибку и сетевой сбой: ответ со статусом ошибки обрабатывается отдельно от отсутствия ответа.
- Клиент сохраняет идентификатор запроса из ответа: request-id пишется в журнал вместе с запросом.
- Клиент учитывает лимиты запросов и токенов: на синтетических данных в изолированной среде видно, что при превышении лимита он не зацикливается.
- Клиент обрабатывает ответ об ошибке размера запроса: заведомо большой синтетический запрос даёт понятную реакцию, а не молчание.
Синтетический пример по последнему пункту. Клиент отправляет слишком большое тело и получает 413 request_too_large. Хорошая реакция — записать request-id, показать сообщение о размере и не повторять запрос автоматически. Плохая — уйти в цикл повторов или выдать «ошибка сети», хотя сеть в порядке. Разница видна только на проверке, а не в коде на глаз.
Если вы берёте официальный SDK, часть пунктов закрывается само: среди заявленных возможностей официальных SDK Anthropic — встроенная логика повторов и обработки ошибок, поддержка стриминга, таймауты запросов и управление соединениями. Но это перечень возможностей из документации, а не результаты независимого тестирования: что именно SDK делает в вашем сценарии, стоит проверить на своих синтетических запросах.
Чем этот разбор отличается от соседних материалов
Соседние статьи разбирают архитектуру агента, доступ агента к сайту, подсчёт токенов и лимитов, проверку ответов ИИ и RAG-цикл. Здесь фокус уже: обвязка собственного клиента — заголовки и версия API, различение HTTP-ошибки и сетевого сбоя, журналирование request-id, реакция на лимиты и на ошибку размера запроса.
Claude API — это RESTful API, и это утверждение относится только к нему; про других провайдеров оно ничего не говорит. Поведение fetch() описано по документации MDN и относится к браузерному Fetch API: как ваше приложение обрабатывает ошибки, стандарт не регламентирует — это ваше решение, и его стоит зафиксировать до запуска.