Перейти к содержимому
TelegramGitHub

Claude AI Bible, глава 19: Tool use, computer use и зрение

Главная мысль: сама по себе модель только пишет текст. Tool use даёт ей руки, computer use — мышь и экран, а зрение (vision) — возможность читать картинки. Это не магия, а точные механизмы с понятными пределами.

Автор сравнивает модель с умным мозгом в запертой комнате: он рассуждает, но не может ничего найти, тронуть ваши данные или увидеть мир. Три возможности главы прорезают в комнате окна и превращают чат-бота в систему, которая делает работу. В главе 18 Agent SDK скрывал эти механизмы, а здесь мы смотрим на них без обёртки: цикл вызова инструмента, описание инструментов, параллельные вызовы и ошибки, computer use, зрение и их связку.

Схема цикла tool use: запрос со списком tools, блок tool_use, выполнение функции вашим кодом, tool_result и ответ Claude

Схему читают по кругу: Claude только просит, а выполняет всегда ваш код.

Вызов инструмента (tool use, или function calling) — это структурированные переговоры. Вы сообщаете Claude, какие инструменты есть. Модель просит запустить нужный и называет аргументы, ваш код выполняет функцию и возвращает результат, а Claude встраивает его в ответ.

Главное — кто что делает. Claude ничего не запускает: модель только пишет текст, а tool use — строгий формат этого текста. Поэтому контроль всегда у вас: Claude может попросить удалить запись, но удалит её только ваш код. Автор называет это разделение главным свойством безопасности.

Технически в запрос кладут список tools: имя, описание и input_schema (схема параметров) каждого инструмента. Модель отвечает блоком tool_use, ваш код шлёт блок tool_result с тем же tool_use_id, и Claude либо просит следующий инструмент, либо отвечает. Пример в книге — курс валют: вместо того чтобы вспоминать курс иены, модель просит get_exchange_rate. Все agentic-сценарии в книге — этот же цикл, только повторённый много раз.

Качество tool use зависит от описаний больше, чем от силы модели: Claude выбирает инструмент и аргументы почти исключительно по именам, описаниям и схеме. По мнению автора, писать описания — самое важное умение в теме, и это скорее работа с текстом, чем программирование.

Описание пишут для толкового коллеги, который не видел вашу систему и не может переспросить. Оно говорит, что делает инструмент, когда его звать и когда не звать. Инструмент называют глаголом (search_orders), каждому параметру дают описание, для фиксированных значений задают enum, для даты — формат. Где схема неясна, модели приходится угадывать. Наш вариант примера из книги:

{
"name": "run_backfill",
"description": "Перезагрузить таблицу за период. Используй ТОЛЬКО если пользователь явно назвал таблицу и даты. НЕ используй, чтобы проверить свежесть данных: для этого есть check_freshness. НЕ запускай для дат в будущем.",
"input_schema": {
"type": "object",
"properties": {
"table": {"type": "string", "enum": ["orders", "payments", "sessions"], "description": "Таблица в хранилище."},
"start_date": {"type": "string", "description": "Первый день периода, формат YYYY-MM-DD."},
"end_date": {"type": "string", "description": "Последний день периода, формат YYYY-MM-DD."}
},
"required": ["table", "start_date", "end_date"]
}
}

Если инструмент вызывают не вовремя, не вините модель: допишите в описание «НЕ используй, когда…». По опыту автора, так исправляется 90% таких сбоев.

Ещё один приём даёт надёжный структурированный вывод. Задайте один инструмент, чья input_schema — нужная вам структура, и заставьте модель его вызвать через tool_choice. По умолчанию модель решает сама, а {"type": "tool", "name": ...} требует именно этот инструмент. Вы получаете объект с вашими полями вместо прозы, которую пришлось бы разбирать регулярными выражениями.

Если модели нужны независимые данные, например остаток и цена трёх товаров, она возвращает несколько блоков tool_use за один ход. Ваш код выполняет их одновременно и отдаёт все результаты одним сообщением, поэтому ждать приходится только самый медленный вызов. Зависимые вызовы идут по очереди, и Claude обычно сам выбирает порядок.

Инструменты ломаются: база недоступна, SKU нет, сервис молчит. Автор советует не обрывать работу, а вернуть ошибку модели как tool_result с флагом is_error. Текст пишут для модели: «Error 500» бесполезен, а «нет SKU X-9921: в каталоге SKU из шести цифр, а здесь пять» подсказывает, как исправиться.

Но если инструмент записи получил отказ из-за прав доступа, цикл надо остановить и позвать человека, а не дать агенту обойти запрет.

Схема: исправимая ошибка возвращается Claude как tool_result с is_error, опасная останавливает цикл и уходит человеку

У многих программ нет API: старая система расходов, портал поставщика 2014 года. Для них есть computer use: Claude смотрит на скриншот, решает, куда кликнуть и что напечатать, ваша среда выполняет действие и присылает новый скриншот. Это цикл агента из главы 18, где инструмент — мышь и клавиатура. На нём же построен Claude in Chrome.

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

Поэтому правила жёсткие. Computer use запускают только в изолированной песочнице (sandbox). Покупку, удаление и отправку подтверждает человек (human-in-the-loop). Текст на экране может оказаться prompt injection, поэтому всё увиденное — данные, а не команды. Если для задачи есть API, берите tool use: так быстрее, дешевле и надёжнее. Computer use — последнее средство.

Схема: есть API — tool use; нет API — computer use с песочницей и подтверждением человека

Случай из книги: агентство в Лиссабоне подтверждало брони на порталах без API. На одном портале кнопки «отменить» и «подтвердить» стояли рядом и меняли место в зависимости от типа брони, и агент отменил бронь вместо подтверждения. Ошибку поймал человек на шаге одобрения. Агентство как раз хотело убрать этот шаг «для скорости».

Claude читает картинки, PDF, графики и скриншоты вместе с текстом. Риск здесь низкий: видеть — не значит действовать. Изображение кладут в сообщение блоком в base64 (картинка, закодированная текстом) или ссылкой, а рядом пишут инструкцию.

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

Для извлечения задайте точную форму JSON и правило для пустых полей, чтобы модель не гадала. PDF отправляют блоком document: Claude читает и текст, и вёрстку, что важно для таблиц и вложенных пунктов договора. Если по документу задают много вопросов, добавьте prompt caching из главы 17.

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

Зрение читает мир, а tool use действует по прочитанному. Пример автора — оплата счетов. Зрение извлекает из PDF поставщика, сумму и строки, lookup_vendor и check_purchase_order сверяют их с системой, а расхождение уходит человеку через flag_for_review.

Схема: счёт в PDF, зрение извлекает поля, сверка суммы строк, tool use проверяет заказ, расхождение уходит человеку

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

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

  • Claude только просит вызвать инструмент, а выполняет его ваш код.
  • Качество вызовов зависит от описаний, особенно от того, когда инструмент не звать.
  • tool_choice с одним инструментом даёт надёжный структурированный вывод.
  • Исправимые ошибки возвращают модели с is_error, опасные останавливают цикл.
  • Computer use — последнее средство: песочница и человек на важных шагах.
  • Числа, извлечённые зрением, проверяют арифметикой.
  • Лучшие процессы соединяют зрение и инструменты, а человек проверяет исключения.
ТерминЗначение
tool useМодель просит запустить функцию, ваш код её выполняет
tool_use, tool_resultПросьба модели и результат, связанные одним id
tool_choiceТребует вызвать заданный инструмент
is_errorФлаг неудачного вызова в tool_result
computer useМодель смотрит на скриншоты и кликает
зрение (vision)Модель читает изображения и PDF
  • Храните описания инструментов в git и дописывайте «НЕ используй, когда…» после каждого ложного вызова.
  • Давайте агенту права только на чтение, а запись подтверждайте отдельно.
  • Сверяйте числа из сканов, как тесты данных: сумма строк равна итогу.

Код книги требует ключ API. Наши скрипты показывают ту же технику без ключа: ответы модели заданы заготовками.

Цикл с параллельными вызовами, is_error и остановкой (ch19_tool_loop.py):

Окно терминала
python3 scripts/claude-ai-bible-code/ch19_tool_loop.py
--- сценарий «склад»
ход 1: модель просит инструменты: get_stock, get_price, get_stock
{"type": "tool_result", "tool_use_id": "tu_1", "content": "A-100001: на складе 14 шт."}
{"type": "tool_result", "tool_use_id": "tu_2", "content": "A-100001: цена $39.90"}
{"type": "tool_result", "tool_use_id": "tu_3", "is_error": true, "content": "Нет товара с SKU 'A-10002'. SKU — буква, дефис и шесть цифр, а здесь пять. Попроси пользователя проверить SKU."}
ответ: A-100001: 14 шт. по $39.90. Второй SKU не найден: уточните его, пожалуйста.
--- сценарий «удаление»
ход 1: модель просит инструменты: delete_order
СТОП: инструмент delete_order не разрешён. Цикл остановлен, нужен человек.

Проверка полей четырёх счетов (ch19_invoice_check.py):

Окно терминала
python3 scripts/claude-ai-bible-code/ch19_invoice_check.py
счёт 1: провести
счёт 2: на проверку: строки дают 430.00, итог 480.00
счёт 3: на проверку: по заказу 99.90, в счёте 199.90
счёт 4: на проверку: поле vendor пустое; заказа PO-504 нет

Настоящий вызов API: зрение плюс tool_choice. Нужны pip install anthropic и ключ, поэтому мы его не запускали.

import base64
import anthropic
client = anthropic.Anthropic() # ключ из ANTHROPIC_API_KEY
img = base64.standard_b64encode(open("invoice.png", "rb").read()).decode()
record_invoice = {
"name": "record_invoice",
"description": "Записать поля счёта. Вызывай ровно один раз. "
"Если поле не читается, ставь null, не угадывай.",
"input_schema": {
"type": "object",
"properties": {
"vendor": {"type": ["string", "null"]},
"po": {"type": ["string", "null"], "description": "Номер заказа, например 'PO-501'."},
"total": {"type": ["string", "null"], "description": "Итог счёта, например '1250.00'."},
"lines": {"type": "array", "items": {"type": "string"}},
},
"required": ["vendor", "po", "total", "lines"],
},
}
resp = client.messages.create(
model="claude-haiku-4-5",
max_tokens=1024,
tools=[record_invoice],
tool_choice={"type": "tool", "name": "record_invoice"}, # только этот инструмент
messages=[{"role": "user", "content": [
{"type": "image", "source": {"type": "base64", "media_type": "image/png", "data": img}},
{"type": "text", "text": "Извлеки поля этого счёта."},
]}],
)
invoice = next(b for b in resp.content if b.type == "tool_use").input
print(invoice)
  1. Почему Claude не может сам удалить запись в вашей базе?
  2. Почему строка «НЕ используй, когда…» чинит ложные вызовы?
  3. Какие ошибки инструмента вернуть модели, а какие должны остановить цикл?
  4. Когда оправдан computer use, и что поставить вокруг него?
  5. Как проверить числа из скана счёта без ручного чтения?

Предыдущая: Claude Agent SDK. Следующая: Агенты и автоматизация.