ИИ агент API — внутренний контракт, через который система принимает задачу с идентификатором и правами, показывает её состояние, возвращает результат с источниками и ждёт допуска к значимому действию. Такой контракт позволяет отделить повтор запроса от новой задачи и сохранить след решения. Здесь предмет статьи — серверный маршрут задачи между приложениями компании. Вызов отдельного инструмента моделью разобран в материале про function calling; у внешнего по отношению к модели API иные обязанности: авторизация, идемпотентность, статус и журнал.
Граница контракта
У внутренней агентной задачи есть идентификатор, состояние, проверяемый результат и отдельный допуск к действию. Повтор запроса с тем же ключом должен вести к прежней задаче, а право подтверждения проверяет сервер.
Пользователь может попросить агента подготовить ответ по документам, сверить заявку или предложить изменение карточки. Во всех случаях приложение сначала отправляет структуру задачи, а затем читает её состояние. Приём запроса означает только регистрацию работы. Готовый текст означает подготовленный результат. Запись во внешнюю систему требует собственного разрешённого перехода. Эти различия должны читаться из ответа API, чтобы интерфейс показывал черновик именно как подготовленный результат.
В официальной документации LangGraph checkpointer сохраняет состояние потока для продолжения после прерывания, а store хранит данные вне отдельного потока. Это пример механизма сохранения состояния. Контракт корпоративного API требует отдельного проектирования. Предложенная ниже схема запроса, статусов, идемпотентности и допуска относится к проектированию собственного сервиса. Правила доступа компании задают отдельно от выбранного фреймворка.
Ближайшая тема — вызов инструментов агентом. Там модель выбирает функцию и формирует аргументы внутри своего рабочего цикла. Здесь клиентская система передаёт задачу серверу, получает стабильный идентификатор и по нему проверяет результат. Граница особенно важна при нескольких повторах из CRM или интерфейса: одинаковый пользовательский клик должен вести к прежнему task_id.
Вход и полномочия
Предложение для пилота начинается с таблицы полей. Клиент передаёт тип задачи, ссылку на разрешённый объект, версию этого объекта, входные параметры по схеме и ключ идемпотентности. Сервер сам устанавливает субъект, организацию и доступные операции из проверенной сессии. Текст запроса модели остаётся данными задачи. Полномочия сервер получает из проверенной сессии. При несовпадении роли, объекта и операции сервис отвечает отказом до запуска вычислений.
| Поле | Зачем нужно | Кто проверяет |
|---|---|---|
| task_id | Связывает запрос, состояния, результат и журнал | Сервер создаёт и хранит |
| object_ref и версия | Привязывают результат к конкретной записи источника | Сервер сверяет видимость и версию |
| idempotency_key | Связывает повтор доставки с прежней задачей | Сервер сопоставляет ключ и состав запроса |
| result_ref | Ведёт к разрешённому результату и доказательствам | Человек сверяет содержимое и ссылки |
| approval | Фиксирует отдельное решение по действию | Сервер проверяет роль, человек подтверждает |
Ключ идемпотентности связывают с организацией, субъектом, типом операции и отпечатком входных данных. Повтор с тем же ключом и тем же запросом возвращает существующий task_id. Тот же ключ при другом содержимом даёт конфликт, который разбирает клиент. Так сервис защищает маршрут от дублирования при повторной доставке. Хранилище ключей и состояния должно переживать перезапуск процесса; запись ключа и новой задачи требуется согласовать в одной транзакционной границе выбранного хранилища.
Входные данные ограничивают до предмета задачи. Секреты, чужие документы и персональные поля без разрешённой цели отсеиваются до обращения к модели. Для сложной проверки доступа полезен материал о правах и секретах агентов. Правила в промпте помогают агенту объяснять рамки, но реальный отказ обеспечивает сервер.
Состояния и результат
Контракт состояния удобнее описать как конечный набор переходов с закреплёнными именами, понятными клиенту. Например, принятая задача попадает в очередь, затем выполняется, после чего получает статус ожидания проверки. Ошибка сохраняется отдельно от отказа в допуске: первая говорит о сбое обработки, второй выражает решение человека или сервера по правам. Набор статусов команда утверждает вместе с владельцем процесса и закрепляет в документации API.
- Клиент отправляет задачу с ключом повтора и получает task_id. Повтор того же запроса возвращает прежний идентификатор.
- Исполнитель читает разрешённые источники. Парсер или скрипт проверяет полные выгрузки и вычисляет точные сравнения; модель формулирует объяснение и гипотезы по отдельным исключениям.
- Сервер сохраняет черновой результат, версии источников, ссылки на фрагменты и код причины сомнения. Клиент читает состояние по task_id.
- Проверяющий открывает исходные записи, исправляет спорные выводы и подтверждает либо отклоняет предложенное действие. Сервер фиксирует решение и повторно сверяет право.
- Разрешённый обработчик выполняет действие с отдельным ключом идемпотентности и сохраняет ссылку на фактический результат. Клиент видит итоговый статус и журнал.
Результат должен различать текст для чтения и структурированное предложение действия. В первом полезны ссылки на документы и пометки уверенности. Во втором нужны объект, желаемое изменение, версия исходной записи и основание. Формат результата проверяет код по схеме; корректная структура оставляет фактическую правоту модели предметом проверки. Если источник изменился после подготовки черновика, задача возвращается на проверку по актуальной версии.
Из такого маршрута естественно следует вопрос о текущих правах, статусах и доказательствах в системе читателя.
Хотите описать контракт задач для вашего агента?
Повтор и допуск
Идемпотентность при создании задачи и защита самого действия решают разные задачи. Первый ключ предотвращает повторную регистрацию при повторе входящего запроса. Второй контролирует применение уже подтверждённого изменения. Между ними возможны смена роли, правка исходного объекта и отзыв согласования. Поэтому сервер перед исполнением сверяет версию объекта, действующее разрешение, подтверждённый состав изменения и ранее записанный результат применения.
Для действий с последствиями предварительное согласие связывают с конкретной версией предложения. Человек должен видеть точный diff или состав операции, исходные доказательства и адрес назначения. После подтверждения агент сохраняет тело действия без изменений; новая версия требует нового черновика. Полномочие проверяют на сервере по роли и объекту, а событие подтверждения пишут в журнал. Доступ модели к кнопке либо инструменту даёт технический вызов, а допуск выдаёт сервер.
При сетевой ошибке клиент может повторить чтение статуса и запрос с прежним ключом. Для самого действия сервер определяет, был ли применён результат, прежде чем отвечать повторно. Если внешняя система работает без поддержки идемпотентности, интеграция хранит собственную запись попытки и проверяет фактическое состояние через разрешённый интерфейс. Пределы такой гарантии надо описать честно: при потере ответа исход зависит от поведения внешней системы и доступности сверки.
Журнал связывает инициатора, проверяющего, ключи, версии, переходы статуса, ссылки на источники и результат внешней операции. Тексты с секретами туда исключают. Для диагностики модель может суммировать причину остановки по обезличенным событиям, а контроль полноты записей делает код. Схема сохраняет возможность отказа при чужой роли и отдельную проверку отзыва допуска.
Проверка пилота
Будущий пилот разумно проводить на тестовом источнике и безопасном действии, например создании черновой заметки в изолированной системе. Владелец процесса заранее перечисляет роли, допустимые операции и ожидаемые переходы. Команда готовит запрос с корректными данными, его повтор, конфликт ключа, потерю ответа, изменение версии источника и попытку подтверждения чужим пользователем. Для каждого сценария указан ожидаемый статус и запись аудита. Такой набор описывает критерии будущей проверки пилота.
Приёмка требует открыть задачу по task_id, восстановить входную версию, увидеть черновой результат с источниками и получить отказ при чужой роли. Проверяющий сравнивает вывод модели с исходным объектом. Парсер отдельно сверяет полную выгрузку и обнаруженные расхождения. Затем в разрешённом тестовом контуре проверяют повтор подтверждённого действия: журнал должен показывать одну логическую операцию и понятный фактический статус. Если доказательство отсутствует, сценарий остаётся открытым для исправления.
Стоимость зависит от числа источников, зрелости прав, сложности внешних действий и требований к аудиту. Состав работ обсуждают после инвентаризации объектов и переходов. Для такого разговора подходит страница об ИИ-агентах для бизнес-процессов: команда может принести схему запроса, таблицу ролей и перечень действий, требующих ручного допуска. Это помогает обсуждать конкретный контракт и границы автономии.