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

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

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

Типы событий

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

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

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

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

Полную схему каждого типа событий см. в справочнике API событий сессии.

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

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

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

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

Сессия отправляет событие agent.custom_tool_use, содержащее имя инструмента и входные данные.
Сессия приостанавливается с событием session.status_idle, содержащим stop_reason: requires_action. Идентификаторы блокирующих событий находятся в массиве stop_reason.requires_action.event_ids.
Выполните инструмент в вашей системе и отправьте событие user.custom_tool_result для каждого, передав идентификатор события в параметре 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 минут, поэтому последовательные обращения в пределах этого окна выигрывают от чтения кэша, что снижает стоимость за токен.

exec {fd}< <(curl -sS -N --fail-with-body \
  "https://api.anthropic.com/v1/sessions/$SESSION_ID/stream?beta=true" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -H "Accept: text/event-stream")

while IFS= read -r -u "$fd" line; do
  [[ $line == data:* ]] || continue
  data="${line#data: }"
  [[ $(jq -r '.type' <<<"$data") == "session.status_idle" ]] || continue
  case $(jq -r '.stop_reason.type // empty' <<<"$data") in
    requires_action)
      while IFS= read -r event_id; do
        # Найти событие вызова пользовательского инструмента и выполнить его
        result=$(call_tool "$event_id")
        # Отправить результат обратно
        jq -n --arg id "$event_id" --arg result "$result" \
          '{events: [{type: "user.custom_tool_result", custom_tool_use_id: $id, content: [{type: "text", text: $result}]}]}' |
          curl -sS --fail-with-body \
            "https://api.anthropic.com/v1/sessions/$SESSION_ID/events?beta=true" \
            -H "x-api-key: $ANTHROPIC_API_KEY" \
            -H "anthropic-version: 2023-06-01" \
            -H "anthropic-beta: managed-agents-2026-04-01" \
            -H "content-type: application/json" \
            -d @-
      done < <(jq -r '.stop_reason.event_ids[]' <<<"$data")
      ;;
    end_turn)
      break
      ;;
  esac
done
exec {fd}<&-

exec {fd}< <(curl -sS -N --fail-with-body \
  "https://api.anthropic.com/v1/sessions/$SESSION_ID/stream?beta=true" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -H "Accept: text/event-stream")

while IFS= read -r -u "$fd" line; do
  [[ $line == data:* ]] || continue
  data="${line#data: }"
  [[ $(jq -r '.type' <<<"$data") == "session.status_idle" ]] || continue
  case $(jq -r '.stop_reason.type // empty' <<<"$data") in
    requires_action)
      while IFS= read -r event_id; do
        # Approve the pending tool call
        jq -n --arg id "$event_id" \
          '{events: [{type: "user.tool_confirmation", tool_use_id: $id, result: "allow"}]}' |
          curl -sS --fail-with-body \
            "https://api.anthropic.com/v1/sessions/$SESSION_ID/events?beta=true" \
            -H "x-api-key: $ANTHROPIC_API_KEY" \
            -H "anthropic-version: 2023-06-01" \
            -H "anthropic-beta: managed-agents-2026-04-01" \
            -H "content-type: application/json" \
            -d @-
      done < <(jq -r '.stop_reason.event_ids[]' <<<"$data")
      ;;
    end_turn)
      break
      ;;
  esac
done
exec {fd}<&-