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

​

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

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

​

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

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 с тем же текстом плюс стоимость и использование.

​

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

• SystemMessage: события жизненного цикла сессии. Поле subtype их различает: "init" — это первое сообщение (метаданные сессии), а "compact_boundary" срабатывает после компактирования. В TypeScript граница компактирования — это собственный тип SDKCompactBoundaryMessage вместо подтипа SDKSystemMessage.
• AssistantMessage: выдается после каждого ответа Claude, включая финальный текстовый. Содержит блоки текстового содержимого и блоки вызовов инструментов из этого хода.
• UserMessage: выдается после каждого выполнения инструмента с результатом инструмента, отправленным обратно Claude. Также выдается для любых пользовательских входов, которые вы транслируете в середине цикла.
• StreamEvent: выдается только при включении частичных сообщений. Содержит необработанные события потоковой передачи API (дельты текста, фрагменты входных данных инструмента). См. Потоковые ответы.
• ResultMessage: отмечает конец цикла агента. Содержит финальный текстовый результат, использование токенов, стоимость и ID сессии. Проверьте поле subtype, чтобы определить, успешна ли задача или достигнут ли лимит. Небольшое количество завершающих системных событий, таких как prompt_suggestion, может прибыть после него, поэтому итерируйте поток до завершения, а не прерывайте на результате. См. Обработать результат.

​

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

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

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

from claude_agent_sdk import query, AssistantMessage, ResultMessage

async for message in query(prompt="Summarize this project"):
    if isinstance(message, AssistantMessage):
        print(f"Turn completed: {len(message.content)} content blocks")
    if isinstance(message, ResultMessage):
        if message.subtype == "success":
            print(message.result)
        else:
            print(f"Stopped: {message.subtype}")

​

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

​

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

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

​

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

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

​

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

​

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

​

Ходы и бюджет

​

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

​

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

​

Модель

​

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

​

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

​

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

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

# 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 отложит схемы инструментов MCP по умолчанию и загружает их по требованию. Когда поиск инструментов отключен, на Vertex AI или за не первой стороной ANTHROPIC_BASE_URL, каждый MCP сервер добавляет все свои схемы инструментов в каждый запрос, поэтому несколько серверов с множеством инструментов могут потребить значительный контекст перед тем, как агент выполнит какую-либо работу.
• Используйте более низкие усилия для обычных задач. Установите effort на "low" для агентов, которым нужно только читать файлы или список каталогов. Это снижает использование токенов и стоимость.

​

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

​

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

​

Hooks

​

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

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage


async def run_agent():
    session_id = None

    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}")


asyncio.run(run_agent())

​

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

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