Claude Agent SDK vs свой Tool Loop: что выбрать для продакшена?

#Claude Agent#AI coding#agentic workflows#frontend#TypeScript

Задача: сделать агентский 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(""));

Что получает разработчик:

Осторожно: 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 });
  }
}

В работе:

Но:


Сколько это стоит и кому что лучше?

Мы запускали примеры на Claude Haiku 5.5 — самом дешёвом из доступных. Вот что получилось по токенам и стоимости:

ОпцияЗапросовВходные токеныВыходные токеныЦена (USD)
Свой цикл2< 1,000134< $0.0002
Tool Runner2~1,000114< $0.0002
Agent SDK286,630483$0.0095

Вывод: Agent SDK дороже из-за большого префикса, который кэшируется, но всё равно цена не заоблачная. Для internal tools с важной логикой работы с файлами цена — не проблема. Для customer-facing SaaS с API-инструментами — это может быть перебор.


Таблица выбора подхода

Что строишьЧто выбратьПочему
Кодинг-агент, dev toolAgent 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-редактор для разработчиков.


Источник: https://dev.to/agentwright/claude-agent-sdk-vs-rolling-your-own-tool-loop-which-one-for-your-product-33lg