Поток событий сеанса

Поток событий сессии

Взаимодействие с Claude Managed Agents основано на событиях. Вы отправляете события пользователя агенту и получаете события агента и сеанса для отслеживания статуса.

Все запросы API Managed Agents требуют заголовка бета-версии managed-agents-2026-04-01. SDK автоматически устанавливает заголовок бета-версии.

Типы событий

События передаются в двух направлениях.

События пользователя — это то, что вы отправляете агенту для запуска сеанса и управления им по мере его выполнения.
События сеанса, события span и события агента отправляются вам для наблюдения за состоянием сеанса и ходом работы агента.

Строки типов событий следуют соглашению об именовании {domain}.{action}.

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

Интеграция событий

Дополнительные сценарии

Обработка вызовов пользовательских инструментов

Когда агент вызывает пользовательский инструмент:

Сеанс отправляет событие agent.custom_tool_use, содержащее имя и входные данные инструмента.
Сеанс приостанавливается с событием session.status_idle, содержащим stop_reason: requires_action. ID блокирующих событий находятся в массиве stop_reason.requires_action.event_ids.
Выполните инструмент в вашей системе и отправьте событие user.custom_tool_result для каждого, передав ID события в параметр custom_tool_use_id вместе с содержимым результата.
После разрешения всех блокирующих событий сеанс переходит обратно в running.

Подтверждение инструмента

Когда политика разрешений требует подтверждения перед выполнением инструмента:

Сессия выдает событие agent.tool_use или agent.mcp_tool_use.
Сессия приостанавливается с событием session.status_idle, содержащим stop_reason: requires_action. Идентификаторы блокирующих событий находятся в массиве stop_reason.requires_action.event_ids.
Отправьте событие user.tool_confirmation для каждого, передав идентификатор события в параметр tool_use_id. Установите result на "allow" или "deny". Используйте deny_message для объяснения отказа.
После разрешения всех блокирующих событий сессия переходит обратно в состояние running.

Отслеживание использования

Объект сессии включает поле usage с кумулятивной статистикой токенов. Получите сессию после того, как она перейдет в режим ожидания, чтобы прочитать последние итоги, и используйте их для отслеживания затрат, установления бюджетов или мониторинга потребления.

{
  "id": "sesn_01...",
  "status": "idle",
  "usage": {
    "input_tokens": 5000,
    "output_tokens": 3200,
    "cache_creation_input_tokens": 2000,
    "cache_read_input_tokens": 20000
  }
}

input_tokens сообщает некэшированные входные токены, а output_tokens сообщает общее количество выходных токенов во всех вызовах модели в сессии. Поля cache_creation_input_tokens и cache_read_input_tokens отражают активность кэширования подсказок. Записи кэша используют TTL в 5 минут, поэтому последовательные ходы в этом окне выигрывают от чтения кэша, что снижает стоимость за токен.

with client.beta.sessions.events.stream(session.id) as stream:
    for event in stream:
        if event.type == "session.status_idle" and (stop := event.stop_reason):
            match stop.type:
                case "requires_action":
                    for event_id in stop.event_ids:
                        # Look up the custom tool use event and execute it
                        tool_event = events_by_id[event_id]
                        result = call_tool(tool_event.name, tool_event.input)

                        # Send the result back
                        client.beta.sessions.events.send(
                            session.id,
                            events=[
                                {
                                    "type": "user.custom_tool_result",
                                    "custom_tool_use_id": event_id,
                                    "content": [{"type": "text", "text": result}],
                                },
                            ],
                        )
                case "end_turn":
                    break

with client.beta.sessions.events.stream(session.id) as stream:
    for event in stream:
        if event.type == "session.status_idle" and (stop := event.stop_reason):
            match stop.type:
                case "requires_action":
                    for event_id in stop.event_ids:
                        # Approve the pending tool call
                        client.beta.sessions.events.send(
                            session.id,
                            events=[
                                {
                                    "type": "user.tool_confirmation",
                                    "tool_use_id": event_id,
                                    "result": "allow",
                                },
                            ],
                        )
                case "end_turn":
                    break