Агентный цикл

Слово «агент» звучит как что-то отдельное от обычного API, но это не так. Агент — это тот же messages.create, вызванный в цикле, где между вызовами ваш код выполняет то, о чём попросила модель. В этом уроке разберём этот цикл по шагам на примере агента, который проверяет pull request, и посмотрим, какие правила нужно соблюдать, чтобы цикл не развалился.

Модель без рук

Модель не может сама открыть файл, сходить в GitLab или запустить тесты. Всё, что она умеет, — читать текст и писать текст. Чтобы она «что-то сделала», нужен посредник: ваша программа, которая понимает запрос модели, выполняет действие и возвращает результат.

Договорённость выглядит так. Вы описываете модели список доступных действий — инструментов. Модель, когда ей нужно действие, вместо текста возвращает специальный блок: «вызови инструмент такой-то с такими параметрами». Ваш код видит этот блок, выполняет действие и отправляет результат обратно как новое сообщение. Модель читает результат и решает, что дальше: вызвать ещё один инструмент или написать финальный ответ.

Это и есть агентный цикл. Если вы проходили курс по Claude Code, то видели его в действии: там точно такой же цикл, только инструменты (чтение файлов, bash, поиск) уже написаны за вас. Об этом — в уроке «Как работает Claude Code». Здесь мы пишем цикл сами.

Цикл по шагам

Возьмём ревьюера PR. У него два инструмента: get_diff (получить изменения по номеру PR) и read_file (прочитать файл из репозитория целиком, чтобы понять контекст).

1. Отправляем запрос: системный промпт с правилами ревью, список инструментов и сообщение «Проверь PR #482».
2. Модель отвечает блоком tool_use: «вызови get_diff с { pr: 482 }». stop_reason равен tool_use.
3. Код вызывает API GitLab, получает diff и добавляет в историю два сообщения: ответ модели (как есть, целиком) и сообщение от user с блоком tool_result, содержащим diff.
4. Снова отправляем запрос — теперь уже с историей из трёх сообщений.
5. Модель видит diff, замечает, что изменённая функция вызывается ещё где-то, и просит read_file для этого файла. Повторяем шаги 3–4.
6. Модели достаточно информации, она пишет замечания текстом. stop_reason равен end_turn. Цикл завершён.

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

Как это выглядит в коде

Полное описание инструментов — в следующем уроке, здесь важен сам скелет цикла.

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

async function reviewPullRequest(prNumber: number): Promise<string> {
  const messages: Anthropic.MessageParam[] = [
    { role: "user", content: `Проверь pull request #${prNumber}.` },
  ];

  for (let iteration = 0; iteration < 20; iteration++) {
    const response = await client.messages.create({
      model: "claude-opus-5",
      max_tokens: 16000,
      system: REVIEW_RULES,
      tools: TOOLS,
      messages,
    });

    if (response.stop_reason === "end_turn") {
      return response.content
        .filter((b): b is Anthropic.TextBlock => b.type === "text")
        .map((b) => b.text)
        .join("\n");
    }

    if (response.stop_reason !== "tool_use") {
      throw new Error(`Неожиданная остановка: ${response.stop_reason}`);
    }

    // 1. Ответ модели добавляем в историю целиком
    messages.push({ role: "assistant", content: response.content });

    // 2. Выполняем все запрошенные инструменты
    const results: Anthropic.ToolResultBlockParam[] = [];
    for (const block of response.content) {
      if (block.type !== "tool_use") continue;
      results.push({
        type: "tool_result",
        tool_use_id: block.id,
        content: await runTool(block.name, block.input),
      });
    }

    // 3. Все результаты — одним сообщением от user
    messages.push({ role: "user", content: results });
  }
  throw new Error("Слишком много итераций");
}

runTool здесь — обычная функция-диспетчер, которая по имени вызывает нужный API. Ничего специфичного для ИИ в ней нет.

Правила, без которых цикл ломается

Несколько вещей в коде выше сделаны не случайно.

Ответ модели добавляется в историю целиком. Не только текст, а весь response.content: блоки tool_use, блоки рассуждения, всё. Если вы сохраните только текст, в следующем запросе tool_result будет ссылаться на tool_use_id, которого в истории нет, и API вернёт ошибку.

Все результаты — в одном сообщении. Модель может запросить несколько инструментов сразу (например, прочитать три файла). Выполните все и верните все tool_result одним сообщением от user. Если разбивать по одному, модель со временем перестанет делать параллельные вызовы.

Ошибка инструмента — тоже результат. Если GitLab вернул 404, не кидайте исключение из цикла. Верните tool_result с полем is_error: true и текстом ошибки: модель прочитает его и попробует иначе или честно скажет, что PR не найден.

Ограничение на итерации. Без него цикл, в котором инструмент раз за разом возвращает что-то бесполезное, будет крутиться, пока не кончатся деньги. Двадцать итераций для ревью — разумная граница, для других задач подберите свою.

Причины остановки

Цикл управляется полем stop_reason, и его значений стоит знать все.

• end_turn — модель закончила. Выход из цикла.
• tool_use — модель просит инструменты. Выполнить и продолжить.
• max_tokens — ответ обрезан. Обычно значит, что max_tokens слишком мал для агента; поднимите его.
• pause_turn — модель сделала паузу в долгой серии серверных инструментов (о них в уроке про встроенные инструменты). Нужно добавить ответ в историю и отправить запрос снова без нового сообщения от пользователя.
• refusal — модель отказалась продолжать. Прочитайте stop_details и завершите сценарий; повторять запрос бессмысленно.

Где проходит граница ответственности

Модель решает, что вызвать. Ваш код решает, можно ли это вызвать. Инструмент «оставить комментарий в PR» — безобидный, его можно выполнять сразу. Инструмент «влить PR в main» безобидным не является, и перед его выполнением ваш код должен спросить человека или вовсе не давать такой инструмент агенту. Модель не знает вашей политики безопасности; она знает только описания инструментов, которые вы ей дали.

Отсюда практическое правило: чем опаснее действие, тем более узким и отдельным инструментом оно должно быть. Один инструмент bash даёт модели возможность сделать что угодно, но вашему коду — только непрозрачную строку команды, которую невозможно проверить. Отдельный инструмент merge_pr с параметром pr можно поставить на подтверждение, залогировать и посчитать.