ИИ-агент через API: как собрать безопасный рабочий цикл

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

Что именно делает API агентным

Обычный вызов API передаёт текст модели и возвращает текст. Агентный цикл добавляет инструкции, инструменты и правило продолжения: модель выбирает действие, приложение исполняет его, возвращает результат, затем модель формирует итог. В документации OpenAI Agents SDK агент описан как модель с инструкциями и инструментами, а документация Anthropic по tool use разделяет инструменты, которые исполняет ваше приложение, и инструменты на стороне провайдера.

API здесь не отдельная нейросеть и не готовый сотрудник. Это интерфейс между вашим приложением и моделью. Память, доступ к календарю, базе или почте, проверку прав и обработку ошибок добавляет ваше приложение. Более широкий выбор архитектуры разобран в материале про разработку ИИ-агентов, а здесь фокус только на минимальном управляемом цикле.

Карта результата: что должно заработать

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

• Исходные условия: серверное приложение, ключ провайдера в переменной окружения, тестовый набор заявок и функция чтения статуса.
• Ожидаемый результат: по существующему номеру агент возвращает статус из тестового набора, а не придумывает его.
• Обязательный путь: описать функцию, принять вызов модели, проверить аргументы, исполнить функцию, связать результат с вызовом и запросить финальный ответ.
• Проверка: известная заявка проходит, неизвестная даёт контролируемую ошибку, повтор одного запроса не создаёт дополнительного действия.
• Безопасный выход: при ошибке аргументов, превышении числа шагов или недоступности сервиса остановиться и показать понятное сообщение.

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

Как выбрать способ реализации

Есть два практичных пути. Готовый Agent SDK сам ведёт цикл между моделью и инструментами. Ручной цикл через базовый API даёт больше контроля над каждым переходом, но требует самостоятельно хранить состояние и сопоставлять вызовы с результатами. Официальный OpenAI Agents SDK включает агентный цикл, инструменты, защитные проверки и трассировку.

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

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

По теме: Команда ИИ-агентов: роли, передача задач и контроль в 2026

Как собрать минимальный цикл

Ключ храните только на сервере. Официальный быстрый старт OpenAI API показывает передачу ключа через переменную окружения, а не через код страницы. Если ключ попал в браузер, любой посетитель сможет извлечь его из загруженных файлов или сетевых запросов.

1. Сформулируйте одну проверяемую задачу: «вернуть статус заявки по её номеру».
2. Опишите инструмент get_order_status: назначение, входное поле order_id, допустимый формат и результат.
3. Отправьте модели инструкции пользователя и схему инструмента. Не передавайте секреты, которые не нужны для задачи.
4. Если модель вернула вызов инструмента, сопоставьте имя с разрешённым списком и проверьте аргументы по схеме.
5. Выполните функцию на сервере и верните результат с идентификатором исходного вызова.
6. Продолжайте цикл до финального ответа, но заранее задайте предел шагов и времени.
7. Запишите технический итог: идентификатор запроса, выбранный инструмент, успех или тип ошибки. Персональные данные и ключ в журнал не помещайте.

Схема ниже намеренно не привязана к одному SDK. Названия полей ответа различаются у провайдеров, но граница ответственности остаётся той же: модель предлагает вызов, приложение проверяет и исполняет.

const allowedTools = { get_order_status };
let step = await model.start({ input, tools: toolSchemas });
for (let turn = 0; turn < MAX_TURNS; turn += 1) {
  if (step.type === 'final') return step.text;
  const tool = allowedTools[step.toolName];
  if (!tool) throw new Error('tool_not_allowed');
  const args = validate(step.arguments);
  const result = await tool(args);
  step = await model.continue({ callId: step.callId, result });
}
throw new Error('turn_limit_exceeded');

Как не допустить повторного действия

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

Разделите инструменты на чтение и изменение. Чтение можно выполнять после проверки аргументов. Изменение сначала переводите в черновик, показывайте человеку точный объект действия и просите отдельное подтверждение. После подтверждения сервер снова проверяет права и только затем исполняет операцию. Это особенно важно для писем, платежей, удаления и публикации.

По теме: Сколько стоит ИИ-агент: бюджет и расчёт в 2026 году

Проверочный чек-лист перед реальными данными

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

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

Диагностика по симптому

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

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

Инструмент получает лишние поля. Закройте схему от неизвестных свойств и проверяйте типы на сервере. Одной инструкции в тексте для этого недостаточно.

Операция выполняется дважды. Не запускайте её повторно вслепую. Найдите запись по ключу идемпотентности и верните сохранённый результат.

По теме: ИИ-агент GPT: что это и какой способ выбрать в 2026

Ограничения и доступ из России

Доступность API зависит от страны, аккаунта и правил конкретного провайдера. На актуальной странице поддерживаемых стран OpenAI API сказано, что доступ вне списка не поддерживается; России в опубликованном списке нет. Не обходите региональные ограничения. Выберите официально доступного провайдера или разверните совместимую модель на собственной инфраструктуре.

Даже при официальном доступе агент остаётся вероятностной системой. Он может выбрать не тот инструмент или сформировать неверные аргументы. Поэтому права, подтверждения, ограничения и итоговая проверка должны жить в обычном серверном коде, а не только в инструкции модели.

Когда API агента не подходит

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

Частые вопросы

Нужен ли отдельный Agent SDK?

Нет. Цикл можно написать поверх базового API, если вы готовы сами сопоставлять вызовы и результаты, хранить состояние и обрабатывать остановку. SDK сокращает эту работу.

Можно ли вызывать API прямо из сайта?

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

Чем инструмент отличается от промпта?

Промпт задаёт поведение модели. Инструмент даёт строго описанную возможность получить данные или выполнить действие через ваш код.

Нужна ли память между сообщениями?

Только если следующему шагу действительно нужен прошлый контекст. Храните минимально необходимое состояние и отдельно определите срок его удаления.