Встроенные инструменты

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

Два вида встроенных инструментов

Серверные выполняет Anthropic. Вы объявляете инструмент в tools, модель его вызывает, результат появляется в ответе — вашему коду ничего делать не нужно, цикл крутится на стороне API. К ним относятся поиск в интернете, загрузка страниц и выполнение кода.

Клиентские определены Anthropic (имя, схема, поведение модели известны заранее), но выполняете их вы. Модель возвращает tool_use, ваш код делает действие и возвращает tool_result, как с обычными инструментами. Это bash, текстовый редактор и память.

Разница важна для безопасности: серверный code_execution крутится в изолированном контейнере у Anthropic, а клиентский bash — на вашей машине, и что он там сделает, зависит только от вашей обёртки.

Поиск и загрузка страниц

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

const response = await client.messages.create({
  model: "claude-opus-5",
  max_tokens: 16000,
  tools: [
    { type: "web_search_20260209", name: "web_search", max_uses: 5 },
    { type: "web_fetch_20260209", name: "web_fetch", max_uses: 5 },
  ],
  messages: [
    {
      role: "user",
      content:
        "В ТЗ сказано, что оплата проходит через СБП по QR. Найди актуальные " +
        "ограничения по сумме одного платежа в документации и сравни с ТЗ.",
    },
  ],
});

Тип инструмента содержит дату версии, и это не формальность: версия _20260209 умеет фильтровать результаты до того, как они попадут в контекст модели, что экономит токены. name у встроенных инструментов фиксированный, менять нельзя. Полезные параметры: max_uses (сколько раз можно вызвать за один запрос), allowed_domains и blocked_domains (ограничить, куда ходить, например только на docs.claude.com и сайт заказчика).

В ответе появятся новые типы блоков: server_tool_use (что модель сделала) и web_search_tool_result / web_fetch_tool_result (что получила). Обычный текст ответа при этом может содержать ссылки на источники. Ошибка поиска не выбрасывает исключение: она приходит как блок результата с объектом ошибки внутри, так что проверяйте, список это или объект, прежде чем обращаться по индексу.

web_fetch загружает только те адреса, которые уже встречались в диалоге: их дал пользователь или нашёл web_search. Произвольный адрес модель придумать и загрузить не может.

Выполнение кода

Инструмент code_execution запускает код в контейнере у Anthropic: Python с предустановленными библиотеками для данных, без доступа в интернет. Для аналитики это удобнее, чем просить модель «посчитать в уме».

import Anthropic, { toFile } from "@anthropic-ai/sdk";
import { createReadStream } from "fs";

const client = new Anthropic();

const uploaded = await client.files.upload({
  file: await toFile(createReadStream("tickets.csv"), undefined, { type: "text/csv" }),
});

const response = await client.messages.create({
  model: "claude-opus-5",
  max_tokens: 16000,
  tools: [{ type: "code_execution_20260120", name: "code_execution" }],
  messages: [
    {
      role: "user",
      content: [
        { type: "container_upload", file_id: uploaded.id },
        {
          type: "text",
          text: "Это обращения в поддержку за квартал с категориями. Посчитай " +
            "долю каждой категории по месяцам и построй график.",
        },
      ],
    },
  ],
});

Модель сама напишет скрипт на pandas, запустит его, увидит вывод и при ошибке поправит. В ответе появятся блоки bash_code_execution_tool_result с stdout, stderr и кодом возврата, а созданные файлы (тот самый график) — как ссылки на file_id, которые можно скачать через Files API. Сохраняя файлы на диск, берите только базовое имя (path.basename) и пишите в отдельную папку: имя файла — это тоже вывод модели.

Контейнер живёт некоторое время после запроса и его можно переиспользовать: в ответе есть response.container.id, передайте его в следующий запрос параметром container, и установленные библиотеки с файлами останутся на месте.

Есть одно правило совместимости: если вы используете web_search_20260209 или web_fetch_20260209, отдельный code_execution в тот же запрос не добавляйте — у веб-инструментов этой версии уже есть своя среда выполнения, и вторая только запутает модель. Объявляйте code_execution, когда он нужен сам по себе.

Пауза в длинной серии

Серверные инструменты крутятся в своём цикле, и у него есть лимит итераций за один запрос. Если модель его исчерпала, но не закончила, ответ придёт со stop_reason: "pause_turn". Это не ошибка. Добавьте ответ в историю и отправьте запрос ещё раз без нового сообщения от пользователя — API продолжит с того места, где остановился.

if (response.stop_reason === "pause_turn") {
  messages.push({ role: "assistant", content: response.content });
  // повторить запрос с теми же tools и messages
}

Если вы используете tool runner из прошлого урока вместе с серверными инструментами, помните: на момент написания он pause_turn сам не обрабатывает и завершит цикл с обрезанным ответом. Проверяйте stop_reason на каждой итерации.

Клиентские: bash и редактор

Для ревьюера PR удобно дать модели читать файлы и запускать тесты. Можно описать свои инструменты, а можно взять готовые определения от Anthropic: модель уже умеет ими пользоваться, схему писать не нужно.

const response = await client.messages.create({
  model: "claude-opus-5",
  max_tokens: 16000,
  tools: [
    { type: "bash_20250124", name: "bash" },
    { type: "text_editor_20250728", name: "str_replace_based_edit_tool" },
  ],
  messages: [{ role: "user", content: "Запусти тесты и почини падающий." }],
});

Никакого input_schema здесь нет: схема встроена в модель. Но выполнение — ваше. Для bash модель пришлёт { command: "npm test" } (или { restart: true } — перезапустить сессию), для редактора — команду view, create, str_replace или insert с путём и текстом.

Именно здесь проходит граница ответственности, о которой мы говорили в уроке про агентный цикл. Команда и путь — это вывод модели, а значит, недоверенные данные. Запускайте bash в контейнере или под ограниченным пользователем, проверяйте команды по списку разрешённых, а не запрещённых, ставьте таймауты. Путь для редактора приводите к каноническому виду и проверяйте, что он остался внутри корня проекта: ../../etc/passwd не должен пройти. Не вызывайте writeFile на сырой строке из tool_use никогда.

Третий клиентский инструмент — memory_20250818: модель читает и пишет файлы в каталоге /memories, а хранилище реализуете вы. Это способ дать агенту память между сессиями; в SDK есть помощник betaMemoryTool для реализации бэкенда.

Когда что брать

Правило простое. Нужна информация из интернета — web_search и web_fetch. Нужно посчитать, обработать файл, построить график — code_execution. Нужно работать с вашим репозиторием или окружением — bash и редактор в вашей обёртке с ограничениями. Нужно действие в вашей системе (трекер, CRM, деплой) — свой инструмент из прошлого урока или MCP, о котором пойдёт речь через урок.