Руководство по API Claude Opus 5.5: создаём ИИ‑расследователя инцидентов

Следуйте этому руководству по API Claude Opus 5.5 и создайте Python‑агента для расследования инцидентов с vision, программными вызовами инструментов, контрфактическим реплеем, бюджетами задач, структурированными выводами и учётом стоимости.

Обновлено 28 сент. 2026 г. · 12 мин читать

Изучить с помощью AI

ChatGPT Claude Perplexity

В этом руководстве мы разберём сценарий: через несколько минут после обновления ПО в HarborCart — вымышленном магазине для этого примера — начинаются сбои на этапе оплаты. Одни клиенты ждут более 30 секунд, другим показывается ошибка сервера, и они не могут заплатить. У платёжного провайдера тоже кратковременный сбой, так что причина вроде бы очевидна.

Но сбой провайдера не объясняет, почему также падают страницы корзины и заказа. Чтобы найти недостающее звено, нужны журналы приложения, графики, записи запросов и недавние изменения в коде. Это руководство проверяет, сможет ли Claude Opus 5.5 последовательно проанализировать эти данные, проверить свою гипотезу в контролируемых условиях и сообщить только то, что подтверждено доказательствами.

Немного предыстории: Claude Opus 5.5 вышел за несколько дней до начала этого проекта. Наш обзор Claude Opus 5.5 описывает запуск и бенчмарки, поэтому здесь мы сосредоточимся на API и соберём одного агента‑расследователя от первого запроса до проверенного отчёта.

Мы разберём, как:

Сделать первый вызов Claude Opus 5.5 и читать его блоки контента по типам
Дать агенту инструменты только для чтения со строгими схемами
Позволить коду самого Claude фильтровать логи и трейсы через программные вызовы инструментов
Относиться к скриншотам как к гипотезам и проверять их по метрикам
Проверить коренную причину с помощью контрфактического реплея
Сравнить уровни effort на одних и тех же данных
Вернуть структурированный отчёт, в котором допустим вердикт «inconclusive»
Посчитать стоимость расследования по данным об использовании API

TL;DR

Расследователь HarborCart отделил всплеск ошибок платёжного шлюза от политики повторов, которая его усилила, а затем проверил это объяснение перед возвратом отчёта.

Сбой шлюза — это триггер, а не полная коренная причина. Повторные попытки списания удерживают соединения с БД достаточно долго, чтобы «положить» эндпоинты, которые вообще не обращаются к шлюзу.
Расследование и отчёт — отдельные запросы. Веб‑поиск и ссылки доступны во время расследования; второй запрос форматирует проверенные доказательства в JSON.
Программные вызовы инструментов сократили сериализованные доказательства на 98,8%. В трёх расследованиях 142,8 КБ результатов инструментов превратились в 1,7 КБ сводок, возвращённых модели.
Более высокий effort не изменил базовый план реплея. Уровни medium и high выбрали одну и ту же гипотезу и ядро причинно‑следственных тестов.
Средняя стоимость трёх полноценных расследований составила $0,2737 и около двух минут.

Что такое API Claude Opus 5.5?

Доступ к Claude Opus 5.5 — через Messages API Anthropic с идентификатором модели claude-opus-5-5. Согласно обзору модели, она принимает текст и изображения, имеет контекст 1M токенов и максимум 128K на вывод. Адаптивное рассуждение всегда включено, по умолчанию effort — medium.

Стандартная стоимость — $4 за миллион входных токенов и $20 за миллион выходных. Запись в кэш на пять минут стоит $5 за миллион, чтение из кэша — $0,20. Когда кэширование промптов активно, совпадающие префиксы тарифицируются по сниженной ставке чтения из кэша.

Что изменилось по сравнению с Claude Opus 5?

Четыре пункта из руководства по миграции напрямую затрагивают этот проект.

Принудительный tool_choice со значением any или именем инструмента возвращает ошибку 400.
Значение effort по умолчанию изменилось с high в Claude Opus 5 на medium.
Режим рассуждения нельзя отключить, а блоки thinking должны возвращаться без изменений внутри цикла инструментов.
Заметки, которые модель пишет между вызовами инструментов, приходят внутри блоков thinking, которые по умолчанию пусты.

Что мы построим с Claude Opus 5.5?

Агент только расследует. У него есть инструменты для чтения и нет продакшн‑доступов. После сбора доказательств отдельные запросы планирования предлагают контрфактические тесты, а Python валидирует и запускает план уровня medium.

Полный код, генератор данных и веб‑приложение находятся в этом репозитории GitHub.

Что случилось с оплатой в HarborCart?

HarborCart — вымышленный магазин. Его checkout-api обслуживает страницы корзины, статус заказа и POST /checkout, который списывает средства через сторонний платёжный шлюз. Все эти эндпоинты используют общий пул PostgreSQL — 15 соединений на инстанс.

Происходит деплой, и через пять минут шлюз около 90 секунд отдаёт 503. Задержка оплаты растёт сверх 30 секунд, пул забит на 15 из 15. Обвинить платёжного провайдера — просто, и шлюз действительно падал.

Скрытая причина — на шаг глубже. Деплой разрешил повторные попытки неудачных списаний POST до трёх раз, итого четыре попытки, без паузы, пока обработчик держит соединение с БД. Медленные неудачные списания теперь удерживают соединения 30 секунд и более — пул исчерпывается, и падают даже страницы корзины, которые к шлюзу не обращаются.

Далее используем три термина последовательно. Здесь триггер — временный сбой шлюза. Повторы механизм усиления — это повторы POST при удержании дефицитных соединений с БД; а исчерпание общего пула — это системный сбой.

Какие данные агент может проверить?

Агент начинает с алерта, скриншота мониторинга и диаграммы архитектуры. Всё остальное приходит через инструменты: логи, трейсы, пять метрик, метаданные деплоя, Git‑дифф и ранбук. В доказательства преднамеренно добавлены три конкурирующих объяснения: предупреждение об инвентаризации, предупреждение фронтенда и возможное насыщение CPU.

Путь оплаты HarborCart и общий пул. Изображение автора.

Диаграмма показывает, что соединение удерживается на весь запрос. Она не утверждает, что это проблема; расследование должно выяснить это самостоятельно.

Как понять, что диагноз верен?

Определите критерии успеха до сборки агента. Верный отчёт должен:

Назвать изменение политики повторов, разрешившее ретраи POST
Утвердить, что соединение с БД удерживается во время вызова шлюза
Объяснить, как более долгие удержания исчерпывают пул
Рассматривать всплеск ошибок шлюза как триггер, а не как механизм усиления
Отклонить как минимум два из трёх альтернативных объяснений
Привести конкретные доказательства, включая дифф и метрику
Включить контрфактический реплей с результатом, соответствующим вердикту

Как использовать API Claude Opus 5.5 в Python

Нужен Python 3.10+ и ключ Anthropic с доступом к claude-opus-5-5. Эти команды PowerShell клонируют проект и установят закреплённые зависимости, включая anthropic 1.8.0. Если вы на Amazon Bedrock, сначала прочитайте FAQ — часть функций не перенесётся.

git clone https://github.com/KhalidAbdelaty/opus-5-5-api-tutorial.git
cd opus-5-5-api-tutorial
python -m venv .venv
.venv\Scripts\Activate.ps1
pip install -r requirements.txt
Copy-Item .env.example .env

На macOS или Linux активируйте через source .venv/bin/activate и копируйте с помощью cp .env.example .env. Добавьте ключ в .env — python-dotenv загрузит его для SDK; наш гайд по переменным окружения объясняет подход. Если вы уже вызывали Claude из Python, пропустите следующий подраздел — он лишь подтверждает настройку.

Сделайте первый вызов API Claude Opus 5.5

Минимально полезный запрос подтверждает ключ и показывает структуру ответа.

import anthropic
from dotenv import load_dotenv

load_dotenv()
client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=2048,
    messages=[{"role": "user", "content": "A checkout API returns HTTP 503 right after a deploy. Name the first two things to check."}],
)
print([block.type for block in response.content])
text = "".join(block.text for block in response.content if block.type == "text")

В этом запросе ответ содержит блоки thinking и text. Выбирайте блоки по типу, а не через чтение response.content[0].

Как построить агента с вызовом инструментов в Claude Opus 5.5

Агенты с вызовом инструментов соединяют Messages API Claude с Python‑функциями, контролирующими доступ к данным. Приложение следует правилу: Claude решает, какие доказательства ему нужны, а Python — к чему можно дать доступ.

Наше руководство по инженерии обвязки агента описывает более общие границы инструментов и циклы; HarborCart держит инструменты только для чтения и ограничивает их текущим инцидентом.

Определите инструменты инцидента только для чтения

Каждый инструмент читает фиксированный набор данных и возвращает ограниченный JSON‑результат. Запросы логов и трейсинга возвращают максимум 200 строк плюс счётчик, а запросы метрик — максимум 60 точек.

Программные вызовы инструментов не поддерживают strict: true, поэтому разделите инструменты на два типа. Контроль доступа к данным и инструмент остановки расследования держите строгими и доступными только напрямую. Логи, трейсы и метрики — только через исполнение кода, чтобы у Claude был один понятный путь для больших запросов.

{"name": "finish_investigation", "strict": True,
 "allowed_callers": ["direct"],
 "input_schema": {"type": "object",
                  "properties": {"summary": {"type": "string"}},
                  "required": ["summary"],
                  "additionalProperties": False}},
{"name": "query_traces",
 "allowed_callers": ["code_execution_20260120"],
 "input_schema": {...}},

allowed_callers направляет модель, но не является границей безопасности. Python проверяет вызывающего перед исполнением каждого инструмента и отклоняет прямые вызовы запроса. Программные вызовы также обходят строгую валидацию, поэтому функции запросов всё равно валидируют свои аргументы.

Приложение помечает каждый принятый результат инструмента, отклоняет выводы, которые ссылаются на отсутствующие доказательства, и принимает URL документации только если их вернул веб‑поиск. Выходы реплея пишет Python, а не модель.

Используйте строгие схемы вместо принудительного выбора инструмента

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

Постройте многоходовый цикл расследования

Цикл отправляет диалог, выполняет блоки tool_use, добавляет результаты и повторяет. Добавляйте блоки ассистента без изменений, включая thinking, а пока программный код на паузе — передавайте ID container обратно только с блоками tool_result.

Запрос на расследование включает vision, инструменты, веб‑поиск, effort и бюджет задачи, но без выходной схемы. Это не допускает включение результатов поиска со ссылками в структурированный JSON‑вывод, а стабильный префикс запроса сохраняет кэширование промптов активным:

request = dict(
    model="claude-opus-5-5",
    max_tokens=16_000,
    system=[{"type": "text", "text": SYSTEM_PROMPT, "cache_control": {"type": "ephemeral"}}],
    tools=investigation_tools,
    cache_control={"type": "ephemeral"},
    thinking={"type": "adaptive", "display": "updates"},
    output_config={
        "effort": "medium",
        "task_budget": {"type": "tokens", "total": 20_000},
    },
    betas=["task-budgets-2026-03-13", "thinking-display-updates-2026-08-18"],
)

Как отправлять изображения в API Claude Opus 5.5

Приложите к первому пользовательскому сообщению дашборд и диаграмму архитектуры как base64 PNG. Попросите Claude считать всё, что он «читает» с изображения, гипотезой и подтверждать её через query_metrics.

Дашборд показывает насыщение пула при ровном CPU. Изображение автора.

И дашборд, и запросы метрик используют одни и те же исходные данные. CPU держится около 30%, пока пул полон, что ещё до запросов говорит против версии «хост перегружен».

Перекрёстно проверяйте визуальные наблюдения по «сырым» метрикам

Скриншот подсказывает, куда смотреть, но числовой ряд решает, подтверждается ли наблюдение. Vision генерирует гипотезу; метрики проверяют её.

Для сценариев «сначала изображение» см. наш туториал по agentic vision. В HarborCart vision используется только для выбора следующей метрики.

Как работает программный вызов инструментов в Claude Opus 5.5?

Программный вызов инструментов позволяет Claude писать Python‑код, который выполняется в контейнере и вызывает ваши инструменты как функции. «Сырые» результаты остаются в песочнице, а к модели попадает только напечатанный вывод кода.

Фан‑аут по логам и трейсингу

Агент пишет короткие скрипты, которые вытягивают сбойные трейсы и печатают только количества по эндпоинтам. В одном полном расследовании программные вызовы сократили объём сериализованных доказательств, возвращённых модели, на 98,8%. Результаты инструментов составили 42,9 КБ, а сводки — 0,5 КБ — это байты, а не сэкономленные токены тарификации.

Вызовы инструментов сужают круг доказательств. Изображение автора.

Добавьте поиск документации при неясном поведении зависимостей

Приложение предоставляет ограниченный веб‑поиск по семантике библиотеки повторов. Во время финальной оценки Claude им не пользовался, так что диагноз основан на диффе, метриках, логах и трейсе. Справочник urllib3 отдельно подтверждает, что allowed_methods=None ретраит любой глагол, а backoff_factor=0 убирает ожидание, но эта страница не входит в набор измеренных доказательств.

Как подтвердить коренную причину контрфактическим реплеем

Контрфактический реплей повторно прокручивает трафик инцидента, убирая подозреваемую причину, и проверяет, исчезает ли сбой. Это превращает «эти линии растут вместе» в эксперимент.

Сохраните честность реплея

Реплей использует тот же профиль трафика. В сравнении ниже каждый сценарий меняет одно условие, и приложение контролирует, какие изменения допустимы.

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

Каждый реплей меняет ровно одну вещь. Изображение автора.

Базовый реплей дал 124 ответа 503: 105 таймаутов пула, включая 68 сбоев на эндпоинтах чтения, и 19 ошибок шлюза. Откат политики повторов убрал все таймауты пула и ошибки чтения, но показал 93 шлюзовых 503 на оплате. Освобождение соединения до вызова шлюза также убрало сбои пула, оставив 33 шлюзовых 503, а удаление всплеска шлюза дало ноль ошибок.

Реплей показывает компромисс: откат защищает общий пул, но пропускает больше сбоев оплаты. Используйте как временную меру. Затем добавьте ключ идемпотентности, чтобы повторный платёж не списывал дважды, и перестаньте держать соединение во время вызова шлюза.

Сделайте проверку правилом в коде

Системный промпт просит запустить реплей, но промпт — не механизм принуждения. Цикл проверяет наличие доказательств реплея и отклоняет неподтверждённый диагноз.

Держите эту проверку в Python. Более жёсткий промпт может повысить дисциплину, но не гарантирует её.

Как использовать effort и бюджеты задач в Claude Opus 5.5

Effort определяет, сколько Claude рассуждает на шаг, а бюджет задачи — сколько работы должен занять весь цикл. Наш туториал по Claude Opus 5 API сравнивает все пять уровней effort; здесь medium и high получают один и тот же набор данных до реплея.

Сравните medium и high на одних и тех же данных

В продакшне остаётся medium. До реплея приложение просит уровни medium и high спроектировать причинный тест на одних и тех же данных. Исполняется только рекомендация medium; ответ high служит для сравнения.

Запрос high использует пометку output_config.effort на уровне сообщения за флагом mid-conversation-output-config-2026-07-01. Он не видит ответ medium.

Оба уровня выбрали одну и ту же гипотезу и три одинаковых базовых сценария реплея. В среднем high использовал 2 631 выходной токен против 2 307 у medium и стоил примерно на 11% дороже без изменения причинного теста.

Задайте бюджет задачи для всего цикла

Выбирайте бюджет задачи по наблюдаемому использованию, а не «на глаз». Крупнейшее неограниченное расследование HarborCart потребило 13 322 учитываемых токена, включая вывод модели и текст результатов инструментов, увиденный Claude. Добавим 25% запаса — получим 16 653, ниже минимальных 20 000 у Anthropic, поэтому настроен бюджет 20 000.

Лимиты по числу ходов и времени держите на уровне приложения. Запуск эксперимента переставал начинать новые работы после достижения записанных расходов $2,50. Это не жёсткий потолок: уже идущий запрос может завершиться выше него.

Как использовать структурированные выводы Claude Opus 5.5

Итоговый ответ использует структурированные выводы. Его плоская схема охватывает вердикт, причину, отклонённые гипотезы, доказательства и фикс. Стоимость и задержка не включаются — их измеряет приложение.

Разделите расследование и отчётность

Ссылки из веб‑поиска и output_config.format нельзя совмещать в одном запросе: для ссылок нужны чередующиеся блоки контента, а для схемы требуется JSON. Поэтому HarborCart расследует без выходной схемы. Он сохраняет выводы, привязанные к источникам и результатам реплея, а затем отправляет только проверенные данные во второй запрос — без инструментов и поиска.

import json

report_response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=16_000,
    system=report_instructions,
    messages=[{"role": "user", "content": json.dumps(verified_evidence)}],
    output_config={
        "effort": "medium",
        "format": {"type": "json_schema", "schema": report_schema},
    },
)

Второму запросу нужны только проверенные доказательства, поэтому сохранять полный кэш расследования не требуется.

Разрешите "inconclusive" в поле verdict. Отчёт не должен «выжимать» подтверждённый диагноз, если реплей ему противоречит.

Валидность по схеме не равна корректности

Схема проверяет форму отчёта, а реплей — диагноз. Отказ тоже возвращает HTTP 200 со stop_reason: "refusal" и может не соответствовать вашей схеме, поэтому проверяйте причину остановки до парсинга.

Удалось ли Claude Opus 5.5 найти истинную коренную причину?

Все три финальных отчёта нашли основной причинный механизм и отвергли три альтернативные версии. Два прошли все восемь проверок; третий получил 6/8, так как не указал явное изменение конфигурации ретраев POST и не сослался на дифф деплоя. Поэтому офлайн‑оценка отделена от валидации схемы: корректный JSON и верный диагноз всё ещё могут дать неполный отчёт.

Отчёты также выделяют второй риск: повтор платежа может списать средства дважды. RFC 9110 не определяет POST как по природе идемпотентный и не советует автоматические повторы, если клиент не уверен в безопасности операции. Ключ идемпотентности, поддерживаемый платёжным провайдером, — один из распространённых способов сделать повторы безопаснее.

Наш туториал по Streamlit описывает настройку интерфейса. Интерфейс HarborCart показывает события расследования, планы реплея для medium и high, результаты реплея, финальный отчёт и стоимость. Для статуса между вызовами инструментов гайд по промптам Claude Opus 5.5 описывает display: "updates"; приложение также рендерит события инструментов, когда блок обновлений пуст.

Streamlit показывает ход расследования и отчёт. Видео автора.

Сколько стоило расследование с Claude Opus 5.5?

Полное расследование стоило $0,2582–$0,2838 и заняло 108,8–129,7 секунды. Средняя стоимость — $0,2737, включая необязательное сравнение с высоким effort. На выход в среднем приходилось $0,2043 — около трёх четвертей общей суммы.

Считайте токены кэша так же, как сообщает API

input_tokens уже исключает токены из кэша, поэтому общий вход — сумма трёх полей. Не вычитайте из него чтения кэша. Если ваш учёт стоимости уже учитывает это, пропустите сниппет.

cost = (
    usage.input_tokens * 4.00                  # uncached input only
    + usage.cache_read_input_tokens * 0.20
    + cache_creation.ephemeral_5m_input_tokens * 5.00
    + cache_creation.ephemeral_1h_input_tokens * 8.00
    + usage.output_tokens * 20.00
) / 1_000_000 + web_search_requests * 0.01    # from usage.server_tool_use

Читайте число поисков из usage.server_tool_use. При response_inclusion: "excluded" подсчёт блоков поиска в ответе может занизить число.

Каждый запрос расследования включает web_search_20260318, поэтому Anthropic не добавляет отдельную плату за контейнер выполнения кода сверх токенов и поиска. Если убрать квалифицирующий веб‑инструмент, отслеживайте время выполнения кода отдельно.

Кэширование промптов в Claude Opus 5.5 требует минимум 512 токенов. Во время расследования верхнеуровневый cache_control сдвигает точку отсечки по мере роста истории. Отчёт получает только компактные проверенные доказательства и намеренно запускается без полного кэша расследования.

Что нужно изменить перед продакшном?

Реальный инструмент для дежурства требует больше контролей, чем этот демо‑пример — все на стороне приложения:

Ограничьте учётные данные наблюдаемости данными, к которым обращаются инструменты; меры по устранению держите в отдельном уровне прав; проверяйте разрешения вызывающего в Python, а не полагайтесь на промпты или allowed_callers.
Считайте логи, тикеты, веб‑страницы и результаты инструментов недоверенными данными. Валидируйте их форму и никогда не исполняйте текст, скопированный из них.
Классифицируйте и редактируйте продакшн‑логи перед отправкой в выполнение кода. В таблице хранения данных Anthropic указано, что выполнение кода и программные вызовы инструментов не соответствуют ZDR и HIPAA, а данные контейнера хранятся до 30 дней. Фильтрация веб‑поиска через выполнение кода тоже вне соответствия ZDR и HIPAA.
Ветвите логику по stop_reason до парсинга, считайте отказы отдельно от HTTP‑ошибок и направляйте отчёты inconclusive человеку.
Сохраняйте вызовы инструментов, реплеи, гипотезы, использование токенов и тайминги как журнал доказательств. Не храните скрытое рассуждение.

Когда использовать Claude Opus 5.5 для агентных задач?

Используйте Claude Opus 5.5, когда цена ошибочного диагноза выше стоимости API‑вызова. Разбор корневых причин, отладка по всему репозиторию, планирование миграций и расследования, сочетающие логи, изображения, документацию и несколько инструментов, подходят под этот критерий.

Не используйте его для форматирования, классификации, извлечения и коротких вопросов, где не нужен цикл инструментов. Меньшая модель обычно решит такие задачи быстрее и дешевле.

Для важных агентных задач выбирайте те, где выводы можно проверить тестами, метриками, исходными данными или человеческой проверкой. Держите продакшн на medium, если только парные оценки не показывают, что более высокий effort улучшает план на ваших задачах.

Итоги

Мы собрали расследователя инцидентов, который читает смешанные данные, вызывает ограниченные инструменты, проверяет свой диагноз и возвращает структурированный отчёт. Все три итоговых отчёта сохранили разделение на триггер и коренную причину, описанное ранее, но Python всё равно должен был требовать реплей.

Не стал бы обобщать этот результат на каждый инцидент или кодовую базу. То, что переносится, — это метод: ограничивайте доступ к данным, фильтруйте большие результаты инструментов до попадания в модель, допускайте вердикт "inconclusive" и проверяйте объяснение вне модели. Реплей — та часть, которую стоило бы сохранить даже в уменьшённой версии проекта.

Изменив инструменты доказательств и шаг валидации, по той же схеме можно поддержать расследователь сбоев CI, ревьюер pull‑request или проверяющий миграции. Первым расширением стал бы роутер, отправляющий простые инциденты в более дешёвую модель и оставляющий Claude Opus 5.5 для случаев, где нужны несколько источников доказательств. За обзором модели см. ссылку на Claude Opus 5.5 во введении.

Можно ли выключить thinking в Claude Opus 5.5?

Сообщает ли API, сколько бюджета задачи осталось?

Лучше ли Claude Opus 5.5, чем Claude Opus 5?

Можно ли запустить этого агента на Amazon Bedrock?

Не без изменений. Базовые Messages и цикл инструментов на стороне клиента можно перенести на Amazon Bedrock с ID модели anthropic.claude-opus-5-5. В Bedrock сейчас нет структурированных выводов, серверного выполнения кода, веб‑поиска и программных вызовов инструментов, использованных здесь. Claude Platform on AWS — отдельный сервис с более широкими возможностями.