Задача: сделать агентский workflow с Claude, чтобы он вызывал инструменты, смотрел результаты и решал, что делать дальше. В реальной жизни перед тобой стоит выбор, который задаёт архитектуру всего продукта: написать цикл вызова инструментов самому, взять бета-обёртку Tool Runner из Anthropic SDK или встроить Claude Agent SDK с его «фулл ха́рнессом» из Claude Code.
В этом материале я не буду восторгаться или критиковать, а просто разберу, что, где и зачем лучше использовать. Покажу реальные примеры кода на TypeScript, расскажу про контроль, который ты теряешь или приобретаешь, и поделюсь замерами токенов и цен. В конце — табличка, которая поможет выбрать подход под твою задачу.
Собственный цикл вызова инструментов: максимум контроля, минимум магии
Если ты хочешь максимальную прозрачность и контроль — пиши свой цикл. Это около 50 строк кода, которые делают примерно следующее: отправляют запрос к API (client.messages.create()), смотрят stop_reason, если Claude попросил вызвать инструмент — запускают его у себя, отправляют результаты обратно в одном сообщении и повторяют.
Пример из реальной жизни — поддержка клиента, которая умеет смотреть статус заказа по ID:
import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic();
const MODEL = process.env.MODEL ?? "claude-sonnet-5-5";
const tools = [
{
name: "get_order",
description: "Look up an order by id. Returns status and total in USD.",
input_schema: {
type: "object",
properties: { order_id: { type: "string" } },
required: ["order_id"],
additionalProperties: false,
},
strict: true,
},
];
async function runTool(name: string, input: unknown): Promise<string> {
if (name === "get_order") {
const { order_id } = input as { order_id: string };
return JSON.stringify({ order_id, status: "shipped", total_usd: 99 });
}
throw new Error(`Unknown tool: ${name}`);
}
async function agent(prompt: string, maxTurns = 10) {
const messages = [{ role: "user", content: prompt }];
for (let turn = 0; turn < maxTurns; turn++) {
const res = await client.messages.create({
model: MODEL,
max_tokens: 4096,
system: [{ type: "text", text: "You are a support agent for an online shop.", cache_control: { type: "ephemeral" } }],
tools,
messages,
});
messages.push({ role: "assistant", content: res.content });
if (res.stop_reason !== "tool_use") return res;
const calls = res.content.filter((b): b is any => b.type === "tool_use");
const results = await Promise.all(
calls.map(async (c) => ({
type: "tool_result",
tool_use_id: c.id,
content: await runTool(c.name, c.input),
}))
);
messages.push({ role: "user", content: results });
}
throw new Error("Agent hit maxTurns without finishing");
}
На практике: ты контролируешь каждый запрос, можешь точно замерять токены, ставить лимиты, кастомизировать ошибки и логику. Это важно, когда считаешь расходы, выставляешь биллинг за каждый вызов, или хочешь гибко переключать модели (например, разные планы — разные модели).
Минусы: ты пишешь и поддерживаешь цикл, обрабатываешь ошибки и параллельные вызовы сам, добавляешь фичи вроде пауз и ветвлений вручную.
Tool Runner из Anthropic SDK: автоматизация цикла с бета-статусом
Если хочется меньше кода, но не терять гибкости — Anthropic недавно выпустил Tool Runner в своём SDK. Он берёт твои инструменты с валидацией на Zod, запускает цикл запросов и сам обрабатывает параллельные вызовы инструментов, ошибки и прогресс.
Пример с тем же заказом:
import Anthropic from "@anthropic-ai/sdk";
import { betaZodTool } from "@anthropic-ai/sdk/helpers/beta/zod";
import { z } from "zod";
const client = new Anthropic();
const MODEL = process.env.MODEL ?? "claude-sonnet-5-5";
const getOrder = betaZodTool({
name: "get_order",
description: "Look up an order by id. Returns status and total in USD.",
inputSchema: z.object({ order_id: z.string() }),
run: async ({ order_id }) => JSON.stringify({ order_id, status: "shipped", total_usd: 99 }),
});
const runner = client.beta.messages.toolRunner({
model: MODEL,
max_tokens: 4096,
max_iterations: 10,
system: "You are a support agent for an online shop.",
tools: [getOrder],
messages: [{ role: "user", content: "Where is order A-1042 and how much was it?" }],
});
for await (const message of runner) {
console.log(message.stop_reason, message.usage);
}
const final = await runner.done();
console.log(final.content.filter((b) => b.type === "text").map((b) => b.text).join(""));
Что получает разработчик:
- валидацию входных данных через Zod;
- встроенную обработку ошибок;
- поддержку параллельного вызова инструментов;
- доступ к каждому ответу цикла для логирования и метрик;
- возможность быстро прототипировать.
Осторожно: Tool Runner всё ещё в бета, API может меняться, нужно фиксировать версии SDK и внимательно читать релиз-ноты.
Claude Agent SDK: встроенный Claude Code с кучей инструментов и хуков
Это уже уровень выше: Claude Code упакован как npm-библиотека, со встроенными инструментами для работы с файлами, шеллом, веб-поиском и прочим. Тут не надо писать ни строчки кода для инструментов — они уже есть, можно только настроить разрешения, сессии, подагентов и хуки.
Пример: поиск всех TODO-комментариев в проекте:
import { query } from "@anthropic-ai/claude-agent-sdk";
for await (const message of query({
prompt: "List every TODO comment under src/ with file and line number.",
options: {
model: process.env.MODEL ?? "claude-sonnet-5-5",
cwd: process.env.REPO_DIR ?? process.cwd(),
allowedTools: ["Read", "Glob", "Grep"],
maxTurns: 10,
},
})) {
if (message.type === "result") {
console.log(message.subtype === "success" ? message.result : message.subtype);
console.log({ turns: message.num_turns, cost_usd: message.total_cost_usd, usage: message.usage });
}
}
В работе:
- экономит недели на разработку сложных агентов, которые работают с файловой системой, shell-командами и подагентами;
- встроенные permission-механизмы минимизируют риски;
- сессии и возможность продолжить работу позже — нишевые, но крутые фичи.
Но:
- большой фиксированный overhead в 43 000 токенов системного префикса (хотя он кэшируется на час);
- нужно запускать Node или Python-процесс с бинарником, не подойдёт для edge/serverless с коротким таймаутом;
- менее гибко в плане кастомных инструментов и контроля над каждым запросом.
Сколько это стоит и кому что лучше?
Мы запускали примеры на Claude Haiku 5.5 — самом дешёвом из доступных. Вот что получилось по токенам и стоимости:
| Опция | Запросов | Входные токены | Выходные токены | Цена (USD) |
|---|---|---|---|---|
| Свой цикл | 2 | < 1,000 | 134 | < $0.0002 |
| Tool Runner | 2 | ~1,000 | 114 | < $0.0002 |
| Agent SDK | 2 | 86,630 | 483 | $0.0095 |
Вывод: Agent SDK дороже из-за большого префикса, который кэшируется, но всё равно цена не заоблачная. Для internal tools с важной логикой работы с файлами цена — не проблема. Для customer-facing SaaS с API-инструментами — это может быть перебор.
Таблица выбора подхода
| Что строишь | Что выбрать | Почему |
|---|---|---|
| Кодинг-агент, dev tool | Agent SDK | Готовые инструменты, сессии, подагенты |
| Внутренняя автоматизация с редактированием кода | Agent SDK | Экономия времени и безопасность |
| Клиентская фича с кастомными API/инструментами | Свой цикл или Tool Runner | Малый префикс, полное кэширование, контроль метрик |
| Быстрый прототип | Tool Runner | Меньше кода, используй свои инструменты |
| Edge или serverless | Свой цикл | Нет бинарников, короткие таймауты |
Итог и что попробовать дальше
Если агент должен работать с файлами, запускать shell-команды и иметь сложные workflow — берём Claude Agent SDK и экономим недели. Там уже есть всё, что надо, и это проверенный боевой код.
Если это SaaS-фича, где нужно пару-тройку инструментов и четкий контроль расходов и метрик — лучше писать свой цикл или взять Tool Runner (если готовы к бете). Tool Runner — хороший компромисс: меньше кода, больше контроля, но не без рисков.
Если не знаешь, с чего начать — начни с Tool Runner. Переходить оттуда к своему циклу — маленький рефакторинг, потому что запросы идентичны.
В моей практике Claude Agent SDK отлично работает для внутренних developer tools, где важна безопасность и удобство работы с репозиториями. Для публичных продуктов с пользовательскими API мне привычнее свой цикл: прозрачнее и легче встраивается в биллинг и мониторинг.
Попробуйте оба подхода на тестовых задачах — и вы сразу почувствуете, где проще и удобнее. AI coding с Claude развивается быстро, и у вас всегда есть запасной план — переписать цикл, если что-то не устраивает.
Если есть вопросы или правки — добро пожаловать в комментарии к оригинальной статье, авторы оперативно отвечают. А я продолжу следить за новинками в agentic development и vibe coding, чтобы делиться полезным без пафоса и маркетинга.
Попробуй сам: Cursor — AI-редактор для разработчиков.