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

​

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

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": метаданные сессии для запуска. Когда 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, может прибыть после него, поэтому итерируйте поток до завершения, а не прерывайте на результате. См. Обработать результат.

​

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

• Только финальные результаты: обработайте 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.

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}`);
}

​

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

​

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

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

​

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

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

​

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

​

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

​

Ходы и бюджет

​

Запас бюджета

​

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

​

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

​

Модель

​

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

​

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

​

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

• Инструкции по резюмированию в CLAUDE.md: механизм сжатия читает ваш CLAUDE.md как любой другой контекст, поэтому вы можете добавить раздел, указывающий, что сохранять при резюмировании. Механизм сжатия ориентируется на смысл, поэтому заголовок раздела может быть произвольным.
• Хук PreCompact: запускайте пользовательскую логику перед сжатием контекста, например для архивирования полного транскрипта. Хук получает поле trigger (manual или auto). См. хуки.
• Ручное сжатие контекста: отправьте /compact в качестве строки промпта, чтобы запустить сжатие по требованию. Команды, отправленные таким образом, — это обычные входные данные 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 Tool Search по умолчанию откладывает загрузку схем инструментов MCP и загружает их по требованию. Когда поиск инструментов отключен или переключился на предварительную загрузку, каждый MCP-сервер добавляет все свои схемы инструментов в каждый запрос, поэтому несколько серверов с множеством инструментов могут потребить значительный объем контекста еще до того, как агент выполнит какую-либо работу. Конфигурации, в которых применяется этот резервный вариант, см. в разделе Настройка поиска инструментов.
• Используйте более низкий уровень effort для рутинных задач. Установите effort в значение "low" для агентов, которым нужно только читать файлы или выводить списки каталогов. Это снижает расход токенов и стоимость.

​

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

​

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

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

​

Hooks

​

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

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}`);
}

​

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

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