Как работает цикл агента

Поймите жизненный цикл сообщений, выполнение инструментов, контекстное окно и архитектуру, которые питают ваших агентов SDK.

Agent SDK позволяет встроить автономный цикл агента Claude Code в ваши собственные приложения. SDK — это отдельный пакет, который дает вам программный контроль над инструментами, разрешениями, ограничениями затрат и выводом.

Оба SDK (TypeScript и Python) включают собственный бинарный файл Claude Code, поэтому большинству установок не требуется отдельная установка Claude Code. Примечание об установке см. в quickstart.

Когда вы запускаете агента, SDK запускает тот же цикл выполнения, который питает Claude Code: Claude оценивает ваш запрос, вызывает инструменты для выполнения действий, получает результаты и повторяет до завершения задачи. На этой странице объясняется, что происходит внутри этого цикла, чтобы вы могли эффективно создавать, отлаживать и оптимизировать своих агентов.

Цикл с первого взгляда

Каждая сессия агента следует одному и тому же циклу:

1. Получить запрос. Claude получает ваш запрос вместе с системным запросом, определениями инструментов и историей разговора. SDK выдает SystemMessage с подтипом "init", содержащий метаданные сессии.
2. Оценить и ответить. Claude оценивает текущее состояние и определяет, как действовать дальше. Он может ответить текстом, запросить один или несколько вызовов инструментов или оба варианта. SDK выдает один или несколько объектов AssistantMessage, по одному для каждого блока содержимого, такого как текстовый блок или запрос вызова инструмента.
3. Выполнить инструменты. SDK запускает каждый запрошенный инструмент и собирает результаты. Каждый набор результатов инструментов возвращается Claude для следующего решения. Вы можете использовать hooks для перехвата, изменения или блокировки вызовов инструментов перед их выполнением.
4. Повторить. Шаги 2 и 3 повторяются как цикл. Каждый полный цикл — это один ход. Claude продолжает вызывать инструменты и обрабатывать результаты до тех пор, пока не выдаст ответ без вызовов инструментов.
5. Вернуть результат. SDK выдает финальное AssistantMessage с текстовым ответом (без вызовов инструментов), за которым следует ResultMessage с финальным текстом, использованием токенов, стоимостью и ID сессии.

Быстрый вопрос («какие файлы здесь?») может занять один или два хода вызова Glob и ответа с результатами. Сложная задача («рефакторить модуль аутентификации и обновить тесты») может связать десятки вызовов инструментов на протяжении многих ходов, читая файлы, редактируя код и запуская тесты, при этом Claude корректирует свой подход на основе каждого результата.

Ходы и сообщения

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

Рассмотрим, как может выглядеть полная сессия для запроса «Исправить неудачные тесты в auth.ts».

Сначала SDK отправляет ваш запрос Claude и выдает SystemMessage с метаданными сессии. Затем начинается цикл:

1. Ход 1: Claude вызывает Bash для запуска npm test. SDK выдает AssistantMessage с вызовом инструмента, выполняет команду, затем выдает UserMessage с выводом (три ошибки).
2. Ход 2: Claude вызывает Read на auth.ts и auth.test.ts. SDK выдает AssistantMessage для каждого вызова и возвращает содержимое файлов.
3. Ход 3: Claude вызывает Edit для исправления auth.ts, затем вызывает Bash для повторного запуска npm test. Все три теста проходят. SDK выдает AssistantMessage для каждого вызова.
4. Финальный ход: Claude выдает текстовый ответ без вызовов инструментов: «Исправлена ошибка аутентификации, все три теста теперь проходят.» SDK выдает финальное AssistantMessage с этим текстом, затем ResultMessage с тем же текстом плюс стоимость и использование.

Это было четыре хода: три с вызовами инструментов, один финальный текстовый ответ.

Вы можете ограничить цикл с помощью max_turns / maxTurns, который считает только ходы с использованием инструментов. Например, max_turns=2 в цикле выше остановился бы перед шагом редактирования. Вы также можете использовать max_budget_usd / maxBudgetUsd для ограничения ходов на основе порога расходов.

Без ограничений цикл работает до тех пор, пока Claude не закончит самостоятельно, что хорошо для хорошо определенных задач, но может работать долго на открытых запросах («улучшить этот кодовую базу»). Установка бюджета — хороший стандарт для производственных агентов. См. Ходы и бюджет ниже для справки по опциям.

Типы сообщений

По мере выполнения цикла SDK выдает поток сообщений. Каждое сообщение имеет тип, который говорит вам, на каком этапе цикла оно пришло. Пять основных типов:

• SystemMessage: события жизненного цикла сессии. Поле subtype их различает:

  • "init": метаданные сессии для запуска. Когда hook SessionStart или Setup запускается при инициализации сессии, его сообщения жизненного цикла hook прибывают перед сообщением init
  • "compact_boundary": срабатывает после компактирования
  • "informational": простые текстовые баннеры статуса из цикла
  • "worker_shutting_down": цикл завершится после текущего хода, потому что хост выходит или Remote Control отключился

  В TypeScript каждый подтип, кроме "init", является собственным типом в объединении SDKMessage, а не подтипом SDKSystemMessage.

• AssistantMessage: выдается для каждого блока содержимого в ответах Claude, включая финальный текстовый. Каждое содержит один блок содержимого, такой как текст или вызов инструмента, и сообщения из одного ответа имеют общий ID сообщения.

• UserMessage: выдается после каждого выполнения инструмента с результатом инструмента, отправленным обратно Claude. Также выдается для любых пользовательских входов, которые вы транслируете в середине цикла.

• StreamEvent: выдается только при включении частичных сообщений. Содержит необработанные события потоковой передачи API (дельты текста, фрагменты входных данных инструмента). См. Потоковые ответы.

• ResultMessage: отмечает конец цикла агента. Содержит финальный текстовый результат, использование токенов, стоимость и ID сессии. Проверьте поле subtype, чтобы определить, успешна ли задача или достигнут ли лимит. Небольшое количество завершающих системных событий, таких как prompt_suggestion, может прибыть после него, поэтому итерируйте поток до завершения, а не прерывайте на результате. См. Обработать результат.

Эти пять типов охватывают полный жизненный цикл цикла агента. Оба SDK также выдают события наблюдаемости, такие как статус ограничения скорости и уведомления задач, которые не требуются для управления циклом. См. справку по типам сообщений Python и справку по типам сообщений TypeScript для полных списков.

Обработать сообщения

Какие сообщения вы обрабатываете, зависит от того, что вы создаете:

• Только финальные результаты: обработайте ResultMessage, чтобы получить выход, стоимость и то, успешна ли задача или достигнут ли лимит.
• Обновления прогресса: обработайте AssistantMessage, чтобы увидеть, что делает Claude на каждом ходу, включая какие инструменты он вызвал.
• Прямая потоковая передача: включите частичные сообщения (include_partial_messages в Python, includePartialMessages в TypeScript), чтобы получить сообщения StreamEvent в реальном времени. См. Потоковые ответы в реальном времени.

Как вы проверяете типы сообщений, зависит от SDK:

• Python: проверьте типы сообщений с помощью isinstance() для классов, импортированных из claude_agent_sdk (например, isinstance(message, ResultMessage)).
• TypeScript: проверьте строковое поле type (например, message.type === "result"). AssistantMessage и UserMessage оборачивают необработанное сообщение API в поле .message, поэтому блоки содержимого находятся в message.message.content, а не в message.content.

import asyncio
from claude_agent_sdk import query, AssistantMessage, ResultMessage, TextBlock, ToolUseBlock


async def main():
try:
async for message in query(prompt="Summarize this project"):
if isinstance(message, AssistantMessage):
# Each AssistantMessage carries one content block
for block in message.content:
if isinstance(block, TextBlock):
print(f"Claude: {block.text}")
elif isinstance(block, ToolUseBlock):
print(f"Tool call: {block.name}")
if isinstance(message, ResultMessage):
if message.subtype == "success":
print(message.result)
else:
print(f"Stopped: {message.subtype}")
except Exception as error:
# A single-shot query() raises after yielding an error result. If the
# failure was an error result, the error subtype branches above have
# already run; connection or process failures yield no result message.
print(f"Session ended with an error: {error}")


asyncio.run(main())

import { query } from "@anthropic-ai/claude-agent-sdk";

try {
for await (const message of query({ prompt: "Summarize this project" })) {
if (message.type === "assistant") {
// Each assistant message carries one content block
for (const block of message.message.content) {
if (block.type === "text") {
console.log(`Claude: ${block.text}`);
} else if (block.type === "tool_use") {
console.log(`Tool call: ${block.name}`);
}
}
}
if (message.type === "result") {
if (message.subtype === "success") {
console.log(message.result);
} else {
console.log(`Stopped: ${message.subtype}`);
}
}
}
} catch (error) {
// A single-shot query() throws after yielding an error result. If the
// failure was an error result, the error subtype branches above have
// already run; connection or process failures yield no result message.
console.log(`Session ended with an error: ${error}`);
}

Выполнение инструментов

Инструменты дают вашему агенту возможность действовать. Без инструментов Claude может только отвечать текстом. С инструментами Claude может читать файлы, запускать команды, искать код и взаимодействовать с внешними сервисами.

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

SDK включает те же инструменты, которые питают Claude Code:

На моделях, которые не получают инструменты отслеживания задач, Claude Code предоставляет TaskCreate и TaskUpdate только когда вы согласитесь.

Помимо встроенных инструментов, вы можете:

• Подключить внешние сервисы с помощью MCP servers (базы данных, браузеры, API)
• Определить пользовательские инструменты с помощью пользовательских обработчиков инструментов
• Загрузить skills проекта через источники настроек для повторно используемых рабочих процессов

Разрешения инструментов

Claude определяет, какие инструменты вызывать на основе задачи, но вы контролируете, разрешено ли выполнение этих вызовов. Вы можете автоматически одобрить определенные инструменты, полностью заблокировать другие или требовать одобрения для всего. Три опции работают вместе, чтобы определить, что работает:

• allowed_tools / allowedTools автоматически одобряет перечисленные инструменты. Агент только для чтения с ["Read", "Glob", "Grep"] в списке разрешенных инструментов запускает эти инструменты без подсказок. Инструменты, не указанные в списке, все еще доступны, и вызовы к ним, которые требуют одобрения, переходят к режиму разрешения и canUseTool.
• disallowed_tools / disallowedTools блокирует перечисленные инструменты, независимо от других настроек. См. Разрешения для порядка, в котором правила проверяются перед запуском инструмента.
• permission_mode / permissionMode контролирует, сколько человеческого надзора вы хотите. SDK оценивает активный режим вместе с вашими правилами разрешения и запрета в фиксированном порядке, описанном в Как оцениваются разрешения. См. Режим разрешения для доступных режимов.

Вы также можете ограничить отдельные инструменты правилами, такими как "Bash(npm *)", чтобы разрешить только определенные команды. См. Разрешения для полного синтаксиса правил.

Когда инструмент отклоняется, Claude получает сообщение об отклонении как результат инструмента и обычно пытается использовать другой подход или сообщает, что не может продолжить.

Параллельное выполнение инструментов

Когда Claude запрашивает несколько вызовов инструментов в одном ходе, оба SDK могут запускать их одновременно или последовательно в зависимости от инструмента. Инструменты только для чтения (такие как Read, Glob, Grep и MCP инструменты, отмеченные как только для чтения) могут работать одновременно. Инструменты, которые изменяют состояние (такие как Edit, Write и Bash), работают последовательно, чтобы избежать конфликтов.

Пользовательские инструменты по умолчанию работают последовательно. Чтобы включить параллельное выполнение для пользовательского инструмента, установите readOnlyHint в его аннотациях. Оба SDK TypeScript и Python используют это имя поля из MCP SDK.

Контролировать, как работает цикл

Вы можете ограничить количество ходов, которые делает цикл, сколько он стоит, насколько глубоко Claude рассуждает, и требуют ли инструменты одобрения перед запуском. Все это поля на ClaudeAgentOptions (Python) / Options (TypeScript).

Ходы и бюджет

Когда достигается любой лимит, SDK возвращает ResultMessage с соответствующим подтипом ошибки (error_max_turns или error_max_budget_usd). См. Обработать результат для того, как проверить эти подтипы, и ClaudeAgentOptions / Options для синтаксиса.

Крышка бюджета охватывает подагентов: их расходы учитываются в общей сумме. Когда расходы достигают крышки, создание другого подагента не удается с Budget limit reached, и Claude Code останавливает любых фоновых подагентов, которые все еще работают. Поведение принудительного применения крышки требует Claude Code v2.1.217 или позже.

При потоковом вводе сообщение, которое все еще находится в очереди, когда ход заканчивается на пределе максимальных ходов, остается в очереди. Claude Code не добавляет его в последний вызов модели этого хода. Он начинает новый ход для сообщения, и счетчик максимальных ходов начинается заново для этого хода.

Уровень усилий

Опция effort контролирует, сколько рассуждений применяет Claude. Более низкие уровни усилий используют меньше токенов за ход и снижают стоимость. Не все модели поддерживают параметр effort. См. Effort для того, какие модели его поддерживают.

Если вы не установите effort, оба SDK оставляют параметр неустановленным и полагаются на поведение модели по умолчанию.

Используйте более низкие усилия для агентов, выполняющих простые, хорошо определенные задачи (такие как список файлов или запуск одного grep), чтобы снизить стоимость и задержку. Установите effort в опциях верхнего уровня query() для всей сессии или для каждого подагента с полем effort на AgentDefinition, чтобы переопределить уровень сессии.

Режим разрешения

Опция режима разрешения (permission_mode в Python, permissionMode в TypeScript) контролирует, просит ли агент одобрения перед использованием инструментов:

Для интерактивных приложений используйте "default" с обратным вызовом одобрения инструмента для отображения подсказок одобрения. Для автономных агентов на машине разработки используйте "acceptEdits", чтобы автоматически одобрить редактирование файлов и общие команды файловой системы (mkdir, touch, mv, cp и т. д.), при этом все еще ограничивая другие команды Bash правилами разрешения. Зарезервируйте "bypassPermissions" для CI, контейнеров или других изолированных окружений. См. Разрешения для полных деталей.

Модель

Если вы не установите model, SDK использует значение по умолчанию Claude Code, которое зависит от вашего метода аутентификации и подписки. Установите его явно (например, model="claude-sonnet-5"), чтобы закрепить определенную модель или использовать меньшую модель для более быстрых и дешевых агентов. См. models для доступных ID.

Контекстное окно

Контекстное окно — это общее количество информации, доступной Claude во время сессии. Оно не сбрасывается между ходами в пределах сессии. Все накапливается: системный запрос, определения инструментов, история разговора, входные данные инструментов и выходные данные инструментов. Содержимое, которое остается неизменным на протяжении ходов (системный запрос, определения инструментов, CLAUDE.md), автоматически кэшируется в запросе, что снижает стоимость и задержку для повторяющихся префиксов. Для информации о том, как пользовательский системный запрос или текст append влияет на повторное использование кэша между сессиями, см. Изменение системных запросов.

Что потребляет контекст

Вот как каждый компонент влияет на контекст в SDK:

Большие выходные данные инструментов потребляют значительный контекст. Чтение большого файла или запуск команды с подробным выводом может использовать тысячи токенов в одном ходе. Контекст накапливается на протяжении ходов, поэтому более длительные сессии с множеством вызовов инструментов накапливают значительно больше контекста, чем короткие.

Автоматическое компактирование

Когда контекстное окно приближается к своему лимиту, SDK автоматически компактирует разговор: он суммирует более старую историю, чтобы освободить место, сохраняя ваши самые последние обмены и ключевые решения нетронутыми. SDK выдает сообщение с type: "system" и subtype: "compact_boundary" в потоке, когда это происходит (в Python это SystemMessage; в TypeScript это отдельный тип SDKCompactBoundaryMessage).

Компактирование заменяет более старые сообщения резюме, поэтому конкретные инструкции с начала разговора могут не сохраниться. Постоянные правила должны находиться в CLAUDE.md (загружаемые через settingSources), а не в начальном запросе, потому что содержимое CLAUDE.md повторно вводится в каждом запросе.

Вы можете настроить поведение компактирования несколькими способами:

• Инструкции по суммированию в CLAUDE.md: Компактор читает ваш CLAUDE.md как любой другой контекст, поэтому вы можете включить раздел, рассказывающий ему, что сохранить при суммировании. Компактор совпадает по намерению, поэтому заголовок раздела свободной формы.
• Hook PreCompact: Запустите пользовательскую логику перед компактированием, например для архивирования полной транскрипции. Hook получает поле trigger (manual или auto). См. hooks.
• Ручное компактирование: Отправьте /compact как строку запроса для запуска компактирования по требованию. Команды, отправленные таким образом, — это обычные входные данные SDK. См. dispatch commands by name.

# Summary instructions

When summarizing this conversation, always preserve:
- The current task objective and acceptance criteria
- File paths that have been read or modified
- Test results and error messages
- Decisions made and the reasoning behind them

Держите контекст эффективным

Несколько стратегий для долгоживущих агентов:

• Используйте подагентов для подзадач. Каждый подагент начинает со свежего разговора (без предыдущей истории сообщений, хотя он загружает свой собственный системный запрос и контекст уровня проекта, такой как CLAUDE.md). Он не видит ходы родителя, и только его финальный ответ возвращается родителю как результат инструмента. Контекст основного агента растет на эту резюме, а не на полную транскрипцию подзадачи. См. Что наследуют подагенты для деталей.
• Будьте избирательны с инструментами. Каждое определение инструмента занимает место контекста. Используйте поле tools на AgentDefinition для ограничения подагентов минимальным набором, который им нужен.
• Следите за стоимостью MCP сервера. MCP tool search отложит схемы инструментов MCP по умолчанию и загружает их по требованию. Когда поиск инструментов отключен или вернулся к предварительной загрузке, каждый MCP сервер добавляет все свои схемы инструментов в каждый запрос, поэтому несколько серверов с множеством инструментов могут потребить значительный контекст перед тем, как агент выполнит какую-либо работу. См. Configure tool search для конфигураций, где применяется fallback.
• Используйте более низкие усилия для обычных задач. Установите effort на "low" для агентов, которым нужно только читать файлы или список каталогов. Это снижает использование токенов и стоимость.

Для подробного разбора стоимости контекста для каждой функции см. Понять стоимость контекста.

Сессии и непрерывность

Каждое взаимодействие с SDK создает или продолжает сессию. Захватите ID сессии из ResultMessage.session_id (доступно в обоих SDK) для возобновления позже. TypeScript SDK также выставляет его как прямое поле на инициализирующем SystemMessage; в Python он вложен в SystemMessage.data.

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

См. Управление сессией для полного руководства по возобновлению, продолжению и разветвлению паттернов. Для возобновления сессий в контейнерах без состояния или бессерверных хостах передайте адаптер session_store / sessionStore, чтобы SDK зеркалировал стенограммы на ваш собственный бэкенд и другой хост мог их возобновить. Подпроцесс Claude Code по-прежнему сначала записывает на локальный диск. См. Архитектура двойной записи для того, какая копия пережидает свежую сессию в сравнении с запуском, возобновленным из хранилища, и как сохранить локальную копию эфемерной.

Обработать результат

Когда цикл заканчивается, ResultMessage говорит вам, что произошло, и дает вам выход. Поле subtype (доступно в обоих SDK) — это основной способ проверить состояние завершения.

Поле result содержит финальный текстовый выход и присутствует только в варианте success, поэтому всегда проверяйте подтип перед его чтением.

Все подтипы результатов содержат total_cost_usd, usage, num_turns и session_id, поэтому вы можете отслеживать стоимость и возобновлять даже после ошибок. Есть две вещи, на которые нужно обратить внимание:

• После сбоя сеанса финальный результат — это error_during_execution, чьи поля стоимости могут быть обнулены и чей stop_reason равен null, и процесс завершается после его выдачи. См. Восстановление итогов после сбоя сеанса.
• В Python total_cost_usd, usage и model_usage типизированы как опциональные, поэтому проверьте, что они не равны None перед их чтением.

Поле usage охватывает только основной цикл агента. Используйте modelUsage или model_usage в Python для полного учета токенов и стоимости дерева. См. Отслеживание стоимости и использования для деталей по интерпретации полей usage.

Результат также включает поле stop_reason (string | null в TypeScript, str | None в Python), указывающее, почему модель остановила генерацию на своем финальном ходе. Общие значения — end_turn (модель закончила нормально), max_tokens (достигнут лимит выходных токенов) и refusal (модель отклонила запрос). На результатах ошибок, которые произвел цикл, stop_reason содержит значение из последнего ответа помощника перед завершением цикла; результат, который Claude Code синтезирует после сбоя сеанса, содержит null.

Для обнаружения отклонений проверьте stop_reason === "refusal" (TypeScript) или stop_reason == "refusal" (Python). См. SDKResultMessage (TypeScript) или ResultMessage (Python) для полного типа.

Hooks

Hooks — это обратные вызовы, которые срабатывают в определенных точках цикла: перед запуском инструмента, после его возврата, когда агент заканчивает, и так далее. Некоторые часто используемые hooks:

Hooks работают в процессе вашего приложения, а не внутри контекстного окна агента, поэтому они не потребляют контекст. Hooks также могут короткозамкнуть цикл: hook PreToolUse, который отклоняет вызов инструмента, предотвращает его выполнение, и Claude получает сообщение об отклонении вместо этого.

Оба SDK поддерживают все события выше. TypeScript SDK включает дополнительные события, которые Python еще не поддерживает. См. Контролировать выполнение с помощью hooks для полного списка событий, доступности для каждого SDK и полного API обратного вызова.

Собрать все вместе

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

Поскольку один вызов query() вызывает исключение после выдачи результата ошибки, цикл обернут в блок try, чтобы скрипт корректно завершился при достижении лимита.

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage


async def run_agent():
session_id = None

try:
async for message in query(
prompt="Find and fix the bug causing test failures in the auth module",
options=ClaudeAgentOptions(
allowed_tools=[
"Read",
"Edit",
"Bash",
"Glob",
"Grep",
],  # Listing tools here auto-approves them (no prompting)
setting_sources=[
"project"
],  # Load CLAUDE.md, skills, hooks from current directory
max_turns=30,  # Prevent runaway sessions
effort="high",  # Thorough reasoning for complex debugging
),
):
# Handle the final result
if isinstance(message, ResultMessage):
session_id = message.session_id  # Save for potential resumption

if message.subtype == "success":
print(f"Done: {message.result}")
elif message.subtype == "error_max_turns":
# Agent ran out of turns. Resume with a higher limit.
print(f"Hit turn limit. Resume session {session_id} to continue.")
elif message.subtype == "error_max_budget_usd":
print("Hit budget limit.")
else:
print(f"Stopped: {message.subtype}")
if message.total_cost_usd is not None:
print(f"Cost: ${message.total_cost_usd:.4f}")
except Exception as error:
# A single-shot query() raises after yielding an error result. If the
# failure was an error result, the error subtype branches above have
# already run; connection or process failures yield no result message.
print(f"Session ended with an error: {error}")


asyncio.run(run_agent())

import { query } from "@anthropic-ai/claude-agent-sdk";

let sessionId: string | undefined;

try {
for await (const message of query({
prompt: "Find and fix the bug causing test failures in the auth module",
options: {
allowedTools: ["Read", "Edit", "Bash", "Glob", "Grep"], // Listing tools here auto-approves them (no prompting)
settingSources: ["project"], // Load CLAUDE.md, skills, hooks from current directory
maxTurns: 30, // Prevent runaway sessions
effort: "high" // Thorough reasoning for complex debugging
}
})) {
// Save the session ID to resume later if needed
if (message.type === "system" && message.subtype === "init") {
sessionId = message.session_id;
}

// Handle the final result
if (message.type === "result") {
if (message.subtype === "success") {
console.log(`Done: ${message.result}`);
} else if (message.subtype === "error_max_turns") {
// Agent ran out of turns. Resume with a higher limit.
console.log(`Hit turn limit. Resume session ${sessionId} to continue.`);
} else if (message.subtype === "error_max_budget_usd") {
console.log("Hit budget limit.");
} else {
console.log(`Stopped: ${message.subtype}`);
}
console.log(`Cost: $${message.total_cost_usd.toFixed(4)}`);
}
}
} catch (error) {
// A single-shot query() throws after yielding an error result. If the
// failure was an error result, the error subtype branches above have
// already run; connection or process failures yield no result message.
console.log(`Session ended with an error: ${error}`);
}

Когда агент успешно завершает работу, пример выводит строку Done: с резюме исправления агента, а затем строку вроде Cost: $0.0312.

Следующие шаги

Теперь, когда вы понимаете цикл, вот куда идти в зависимости от того, что вы создаете:

• Еще не запустили агента? Начните с quickstart, чтобы установить SDK и увидеть полный пример, работающий от начала до конца.
• Готовы подключиться к вашему проекту? Загрузите CLAUDE.md, skills и hooks файловой системы, чтобы агент автоматически следовал соглашениям вашего проекта.
• Создаете интерактивный UI? Включите потоковую передачу, чтобы показать живой текст и вызовы инструментов по мере выполнения цикла.
• Нужен более плотный контроль над тем, что может делать агент? Заблокируйте доступ к инструментам с помощью разрешений и используйте hooks для аудита, блокировки или преобразования вызовов инструментов перед их выполнением.
• Запускаете долгие или дорогие задачи? Перенесите изолированную работу на подагентов, чтобы держать ваш основной контекст стройным.
• Развертываете как сервис? См. Hosting the Agent SDK для руководства по контейнерам и бессерверным решениям, и Session storage для сохранения сессий в вашем собственном бэкенде.

Для более широкой концептуальной картины цикла агента (не специфичной для SDK) см. Как работает Claude Code. Для практического руководства по проектированию циклов в Claude Code, от циклов на основе ходов к циклам на основе целей и проактивным циклам, см. Loop engineering: getting started with loops в блоге.