Типизированные инструменты закрывают слепые зоны API

Агент должен выбирать, что делать. Он не должен придумывать, в каком виде API ожидает запрос. Это разделение кажется очевидным, пока модель не отправит customer_id туда, где конечная точка ждет accountId, не превратит предварительный просмотр в обновление или не заполнит неизвестное перечисление правдоподобным словом. В журнале диалога запрос может выглядеть убедительно и при этом оставаться недействительным, двусмысленным или опасным.

Типизированные инструменты переносят эту двусмысленность из промпта в контракт, который система может исполнить. Модель получает ограниченный набор операций, каждая с машиночитаемой формой входных данных. Приложение проверяет вызов до того, как он затронет бизнес-логику, а затем просит человека согласовать любую операцию, меняющую состояние. Модель по-прежнему рассуждает о намерении. Код отвечает за синтаксис, полномочия и выполнение.

Я видел, как команды принимали подробный системный промпт за определение интерфейса. Это разные вещи. Текст может объяснить правило, но он не отклонит лишнее поле, не обеспечит дискриминируемое объединение, не сравнит номер версии и не помешает повторной попытке списать деньги дважды. Если агент получает доступ к производственному API, такие средства контроля должны находиться в коде.

Промпт описывает намерение, контракт инструмента задает полномочия

Промпт может велеть агенту обновлять данные клиента только после подтверждения. Контракт инструмента точно определяет доступное обновление, принимаемые поля и смысл подтверждения. В разговоре эти задачи пересекаются, но сбои у них разные. Текст подводит из-за трактовки. Контракт дает явную ошибку проверки, которую можно воспроизвести, протестировать и учесть в эксплуатации.

Допустим, внутренний API открывает одну широкую конечную точку execute_action. Ее аргументы action, resource и payload имеют строковый тип. В промпте перечислены разрешенные действия и приведены примеры. Такой вариант кажется гибким, потому что новое действие не требует менять схему. Заодно он прокладывает обходной путь вокруг всех ограничений, которые API уже умеет применять. Модель может ошибиться в названии действия, отправить сериализованный JSON внутри payload или сочетать ресурс с действием, которое для него не предназначалось.

Типизированная поверхность должна открывать узкие операции, например get_customer, preview_address_change и commit_address_change. Каждое имя несет одну возможность. Каждая входная схема ограничивает модель полями, которые нужны этой операции. Если модели требуется неподдерживаемое действие, вызов должен завершиться соответствующей ошибкой. Отклоненный вызов безопаснее угаданного, а еще он показывает, где стоит дополнить каталог инструментов.

Здесь же команды часто путают безопасность типов с форматированием промпта. Просьба отвечать в JSON упрощает разбор. Она не делает JSON допустимым для вашего бизнеса. Синтаксис подтверждает, что скобки совпадают. Контракт инструмента подтверждает, что country содержит разрешенный код, customer_id указывает на нужный тип записи, а запись требует согласованного предложения. Нужны оба уровня.

Оставьте описания, но сузьте их задачу. Описание объясняет, когда применять инструмент и что означают его термины. Схема решает, что может пересечь границу. Если ограничение сохраняет силу после окончания генерации текста, закрепите его там, где исполнитель сможет его проверить.

Хорошие схемы мешают выразить недопустимое состояние

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

Этот фрагмент JSON Schema дает модели однозначный выбор и запрещает придуманные поля объекта:

{
  "type": "object",
  "additionalProperties": false,
  "required": ["customer_id", "destination"],
  "properties": {
    "customer_id": {"type": "string", "minLength": 1},
    "destination": {
      "oneOf": [
        {
          "type": "object",
          "additionalProperties": false,
          "required": ["kind", "address_id"],
          "properties": {
            "kind": {"const": "saved"},
            "address_id": {"type": "string"}
          }
        },
        {
          "type": "object",
          "additionalProperties": false,
          "required": ["kind", "line1", "city", "country"],
          "properties": {
            "kind": {"const": "new"},
            "line1": {"type": "string"},
            "city": {"type": "string"},
            "country": {"type": "string", "pattern": "^[A-Z]{2}$"}
          }
        }
      ]
    }
  }
}

Поле kind выступает дискриминатором. Оно не дает идентификатору сохраненного адреса попасть в вариант нового адреса и помогает точно указать место ошибки проверки. additionalProperties: false имеет значение, потому что модели часто добавляют поля, которые выглядят полезными. Если молча игнорировать их, все привыкнут к расхождению между журналом и реально выполненным действием. Отклоняйте их.

Не кодируйте факты из живых данных в статических перечислениях. Список идентификаторов складов, пользователей или текущих тарифов устаревает. Стабильные значения вроде draft, approved и cancelled можно закрепить в схеме. Изменяемые идентификаторы получайте инструментом чтения, а при выполнении сверяйте с системой учета.

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

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

Проверяйте до и после бизнес-логики

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

Запрос с customer_id: "C-1842" может соответствовать всем правилам JSON и ссылаться на удаленную запись либо на клиента за пределами арендатора оператора. Положительная quantity может превышать доступный остаток. Предложение со статусом approved могло истечь. Адаптер инструмента не должен считать успешную проверку схемы ни авторизацией, ни подтверждением фактов предметной области.

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

{
  "ok": false,
  "error": {
    "code": "VERSION_CONFLICT",
    "message": "Customer changed after the proposal was created",
    "retryable": false,
    "field": "expected_version"
  }
}

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

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

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

Чтению и записи нужны разные наборы возможностей

Классифицируйте инструменты по эффекту до того, как их увидит модель. Чтение возвращает сведения, не меняя долговременное состояние. Запись создает, обновляет, удаляет, отправляет, публикует, оплачивает, развертывает или запускает другую систему, выполняющую одно из этих действий. HTTP-глагол не дает надежной классификации. Конечная точка GET может пометить сообщение прочитанным, а POST может выполнить чистый поиск. Оценивайте бизнес-эффект.

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

Записи также требуют более узкой формы. Универсальный инструмент update_record заставляет агента понимать каждую таблицу и изменяемый столбец. Открывайте бизнес-операции вроде suspend_invoice_delivery или change_shipping_address. Тогда сервис сможет обеспечить инварианты, сформировать понятный предварительный просмотр и привязать правило согласования к конкретному эффекту.

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

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

Согласование должно закреплять точную предлагаемую запись

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

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

{
  "proposal_id": "p_7f31",
  "tool": "commit_address_change.v2",
  "arguments_sha256": "8be7...a91c",
  "target": {"type": "customer", "id": "C-1842", "version": 17},
  "effect": "Replace the shipping address for customer C-1842",
  "expires_at": "2026-08-14T16:30:00Z",
  "approved_by": "user_291"
}

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

Правило согласования должно зависеть от последствий, а не от количества инструментов. Черновик с низким риском в изолированной рабочей области может не требовать решения человека. Отправка этого черновика клиенту требует. Массовое изменение, платеж, удаление, смена учетных данных, развертывание в производственной среде или внешнее сообщение должны получать уровень согласования, соразмерный охвату. Храните правило в таблице политик, которую оценивает среда выполнения. Не распределяйте его по промптам.

Экран согласования должен показывать конкретные различия: поля до и после, получателей, сумму и валюту, среду, число затронутых записей и необратимые последствия. Не просите человека согласовать run tool call. Усталость от согласований начинается, когда экран скрывает эффект и вынуждает оператора доверять пересказу агента.

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

Сбой записи несколько минут может выглядеть как успех

Рассмотрим агента, который меняет адрес доставки. Он читает версию клиента 17, предлагает новый адрес и получает согласование. Запрос фиксации доходит до сервиса, тот записывает адрес и подтверждает транзакцию. До получения ответа агентом соединение обрывается. Среда выполнения видит тайм-аут. Она не знает, состоялась ли запись.

Наивная повторная попытка снова отправляет то же логическое изменение. Если конечная точка добавляет адреса или выпускает событие обработки заказа, второй запрос может дублировать работу. Если среда вместо этого сообщит о сбое, оператор может повторить изменение вручную. В журнале инструмент завершился ошибкой, хотя производственная система изменилась. Такая неоднозначность характерна для распределенных систем и не связана с особенностями модели.

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

Среда выполнения должна обрабатывать тайм-аут по фиксированной схеме:

1. Запросить состояние операции по ключу идемпотентности.
2. Если сервис зафиксировал успех, вернуть агенту этот типизированный результат.
3. Если сервис зафиксировал окончательный сбой, вернуть сохраненную ошибку.
4. Если состояние неизвестно, приостановить процесс и передать оператору, не придумывая результат.

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

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

Результат инструмента должен содержать доказательства

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

Для изменения адреса полезный результат может выглядеть так:

{
  "ok": true,
  "operation_id": "op_a812",
  "customer_id": "C-1842",
  "previous_version": 17,
  "new_version": 18,
  "changed_fields": ["shipping_address"],
  "committed_at": "2026-08-14T16:22:11Z"
}

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

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

Удаляйте закрытые данные в адаптере до попадания результата в контекст модели. Разрешение вызвать get_customer не дает права раскрыть все столбцы клиента. Определите представление результата для конкретной задачи и исключите из схемы секреты, внутренние флаги и посторонние персональные данные. Проверка выхода затем защитит это представление от регрессий.

Для долгих операций возвращайте ресурс операции с конечным перечислением состояний, например queued, running, succeeded, failed или cancelled. Опрос выполняйте инструментом чтения. Не держите вызов модели открытым на время развертывания или миграции и не позволяйте агенту выводить успех из прошедшего времени.

Повторы, отмена и конкурентность требуют объявленной семантики

Реестр инструментов должен описывать эксплуатационное поведение наряду со входной и выходной схемами. Как минимум укажите, читает инструмент или записывает, безопасно ли повторять идентичные вызовы, поддерживает ли он идемпотентность, какое правило согласования действует и как работает отмена. Это правила исполнителя, а не текстовые подсказки модели.

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

Ограничения конкурентности нужны на нескольких уровнях. Ограничьте вызовы на один запуск, чтобы цикл планирования не затопил API. Ограничьте вызовы на арендатора, чтобы один загруженный процесс не вытеснил остальные. Добавьте сериализацию на уровне ресурса, если две согласованные записи в один объект конфликтуют. Существующий сервис по-прежнему отвечает за транзакции и блокировки; среда агента не заменяет корректность базы данных.

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

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

Контрактные тесты находят сбои, пропущенные тестами промпта

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

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

Компактный контрактный тест может выглядеть так:

GIVEN proposal p_7f31 targets customer C-1842 version 17
AND the current customer version is 18
WHEN commit_address_change.v2 executes with idempotency key run9:p_7f31
THEN no address is changed
AND the result code is VERSION_CONFLICT
AND the proposal remains unconsumed

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

Проверяйте диспетчер как враждебную границу. Запросите незарегистрированный инструмент, инструмент записи в запуске только для чтения, старую версию схемы, слишком большой объект аргументов и строки с инструкциями для среды выполнения. Диспетчер должен разобрать данные, применить ограничения и вызвать только зарегистрированный обработчик. Он не должен исполнять созданный моделью код или динамически собирать имя метода.

Сохраняйте и небольшой набор полных трасс. Записывайте каталог инструментов, запрос модели, предложенные вызовы, решения проверки, согласования, результаты сервисов и итоговый ответ после удаления чувствительных значений. Воспроизводите трассы после изменений схемы. Точные формулировки могут различаться, но разрешенные эффекты и инварианты должны оставаться прежними.

Контрактные тесты должны фиксировать и сам каталог. Храните ожидаемый список имен инструментов, версий, классов эффекта и правил согласования для каждой роли среды. Тогда вновь зарегистрированная запись не пройдет проверку, если кто-то забудет добавить политику, а роль только для чтения не пройдет ее, если в каталоге появится операция фиксации. Так вы поймаете дрейф полномочий до случайного выбора нового инструмента оценочным промптом.

Систематически создавайте недопустимые случаи, но работайте в понятных границах схемы. Для обязательной строки попробуйте отсутствие, пустой текст, слишком большое значение и неверный примитивный тип. Для объединения совместите поля обеих ветвей и передайте неизвестный дискриминатор. Для чисел проверьте точные пределы и ближайшие значения за ними. Цель состоит в доказательстве, что каждая объявленная граница имеет исполнимый путь отказа.

Телеметрия производства должна отвечать на конкретные вопросы без хранения чувствительных нагрузок. Считайте вызовы по инструменту и версии, ошибки проверки по коду и полю, решения о согласовании, конфликты, неоднозначные исходы, повторы по объявленному классу и ошибки выхода. Резкий рост неизвестных полей обычно означает, что промпт или клиент опередил реестр. Частые конфликты версий могут указывать на слишком долгую жизнь предложений или слишком раннее чтение. По этим сигналам решайте, менять ли схему, описание инструмента или последовательность.

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

Внедряйте сбои вокруг исполнителя. Разрывайте соединение после фиксации сервисом, возвращайте неправильно сформированное успешное тело, задерживайте согласование до истечения, сталкивайте два предложения за одну версию и временно отключайте конечную точку статуса. Убедитесь, что при недостатке доказательств среда сообщает о неизвестном исходе. Выдуманный успешный ответ может хорошо выглядеть в оценке, поэтому сравнивайте с сохраненным состоянием сервиса, а не только с последним предложением.

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

Безопасный вариант по умолчанию имеет меньшую поверхность

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

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

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

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

Типизированные инструменты превращают агента из интерфейса чата вокруг привилегированных учетных данных в управляемый программный компонент. Оставьте рассуждение модели. Полномочия и истина должны оставаться на границе.