Claude API: как связать несколько tool result с локальными операциями

Создавайте локальную операцию до выполнения инструмента

После проверки предложения инструмента сервер создаёт operation ID и связывает его с tenant, разрешённым именем, версией схемы, пользователем и ожидаемым состоянием. Этот ID не должен содержать prompt, email, ключ, URL медиа или бизнес-данные. Он служит внутренней точкой корреляции, даже если внешний формат сообщения позже меняется.

Tool call не является разрешением изменить заказ, отправить письмо или читать чужой документ. До side effect нужны allowlist инструмента, строгая валидация аргументов, авторизация объекта и при необходимости явное подтверждение человека. При отказе верните безопасный локальный результат, а не стек, SQL-ошибку или содержимое чужой записи.

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

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

Не используйте порядок сообщений как единственный ключ. Асинхронный worker, повторная доставка и сетевой сбой могут поменять последовательность. Храните revision операции и применяйте переход состояния атомарно. Это не обещает exactly-once со стороны поставщика, но защищает вашу доменную модель от наиболее частого двойного применения.

Разделите параллельность и права

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

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

Остановите повтор, если исход неизвестен

Timeout между worker и приложением не сообщает, был ли выполнен side effect. Не создавайте новую операцию только потому, что клиент повторил кнопку. Сначала найдите operation ID, покажите состояние unknown_outcome и запустите сверку безопасным способом. Новый запрос допустим только после явного решения приложения и защиты от дубля.

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

Не превращайте tool result в журнал данных

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

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

Покройте workflow синтетическими тестами

Минимальный набор включает разрешённый result, неверный ID, другой tenant, повторную доставку, поздний результат, неожиданное поле и timeout. Тест доказывает, что приложение не делает второй side effect, не выводит секреты и возвращает честный статус. Он должен запускаться без сетевого вызова и без реального API-ключа.

Продолжите с проверкой аргументов tool use, подтверждением действий в tool policy и function calling в совместимом API. Перед production сверяйте текущий контракт и применяйте собственные правила авторизации.

Безопасный server-side пример

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

export function applyToolResult({ operation, result, viewer }) {
  if (!operation || operation.tenantId !== viewer?.tenantId) return { ok: false };
  if (operation.status !== 'running' || result?.operationId !== operation.id) return { ok: false, state: 'stale' };
  if (result.tool !== operation.tool || !['ok', 'rejected'].includes(result.status)) {
    return { ok: false, state: 'needs_review' };
  }
  return { ok: true, nextState: result.status }; // caller persists atomically
}

Критерий готовности

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

Граница ответственности и данных

Не передавайте в браузер, обычный журнал, тикет или статью API-ключи, заголовок Authorization, cookie, ключи поставщиков, полный prompt либо персональные данные. Для расследования используйте минимальные технические метаданные и синтетические fixtures.

Контроль перед выпуском

Перед production проверьте обезличенный сценарий на staging, права tenant, границу побочного действия, понятный статус для пользователя и ручную ветку для неизвестного результата. После изменения модели, SDK, маршрута или схемы повторите проверку: старый прогон не подтверждает новый контракт.

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

Полезные материалы

Anthropic tool use documentation · OWASP Authorization Cheat Sheet

FAQ

Можно ли сопоставлять tool result по порядку сообщений?

Нет, одного порядка недостаточно. Асинхронная доставка и retry могут изменить последовательность. Используйте локальный operation ID, tenant, имя разрешённого инструмента, версию схемы и ожидаемое состояние.

Является ли tool call разрешением на side effect?

Нет. Это недоверенный вход. Сервер обязан проверить allowlist, аргументы, объект, tenant и права. Для заметного действия может потребоваться подтверждение пользователя либо оператора.

Что делать после timeout?

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

Следующий шаг

Продолжите с материалами: Проверка аргументов tool use · Подтверждение действий в tool policy · Function calling в совместимом API. Затем протестируйте интеграцию на staging до production-трафика.