Руководство по быстрому старту с Claude Managed Agents 2026

Когда я впервые попытался запустить сессию Managed Agents, на самом первом curl я получил ошибку 400. Не при создании агента. Не при создании окружения. На стриминговом эндпоинте. Я скопировал заголовок из запроса создания — anthropic-beta: managed-agents-2026-04-01 — и стриминговый API его отклонил. Оказалось, что стриминговый эндпоинт в тот момент в документации ссылался на другой бета-заголовок. Я потерял сорок минут на это.

Если вы сейчас пытаетесь запустить свою первую сессию Managed Agents от начала до конца, вот путь, которым я прошёл сам. Привет, я Дора! Сначала про бета-заголовок, потому что именно там живёт половина всех ошибок. Затем: агент, окружение, сессия, стрим. И в конце — контрольная точка по стоимости, потому что счётчик сессии тикает, пока вы отлаживаете.

Перед Началом

Вам нужен API-ключ Anthropic с доступом к Managed Agents. Листа ожидания сейчас нет — любой существующий ключ работает в публичной бете.

Бета-заголовок обязателен. Каждый эндпоинт Managed Agents требует anthropic-beta: managed-agents-2026-04-01. Согласно обзору Managed Agents от Anthropic, SDK устанавливает его автоматически. Если вы используете сырой curl, добавляйте его к каждому запросу самостоятельно. Это самая распространённая причина ошибок 400, которую я видел в отчётах сообщества.

Если вы используете официальный SDK (anthropic для Python, @anthropic-ai/sdk для TypeScript), убедитесь, что у вас версия с поддержкой бета-агентов. Старые версии не будут иметь client.beta.agents или client.beta.sessions.

Выбор модели здесь важен. Opus 4.7 лучше справляется с долгосрочными агентными рассуждениями. Sonnet 4.6 дешевле и быстрее за токен. Для первого запуска Sonnet 4.6 достаточно. Если ваша реальная задача — отладка, планирование или длинные цепочки инструментов, Opus 4.7 оправдывает свою цену.

Шаг 1 — Определение Агента

Агент в Managed Agents — это объект конфигурации, а не процесс. Вы определяете имя, модель, системный промпт и доступ к инструментам один раз, а затем используете его повторно в разных сессиях.

Минимально жизнеспособное определение из официального руководства по быстрому старту:

python

agent = client.beta.agents.create(
    name="Coding Assistant",
    model="claude-opus-4-7",
    system="You are a helpful coding agent.",
    tools=[{"type": "agent_toolset_20260401"}],
)

Тип инструмента agent_toolset_20260401 открывает полный встроенный набор — bash, чтение/запись файлов, веб-поиск, веб-запросы, выполнение кода. Позже можно ограничить. Для первого запуска оставьте широкий доступ, чтобы видеть, что агент выбирает.

Сохраните agent.id. Каждая сессия ссылается на него.

Шаг 2 — Создание Окружения

Окружение определяет изолированный контейнер. Для большинства первых запусков:

python

env = client.beta.environments.create(
    name="quickstart-env",
    config={"type": "cloud", "networking": {"type": "unrestricted"}},
)

Сохраните env.id. Если ваш агент работает только со своей файловой системой, "networking": {"type": "limited"} безопаснее и хорошо задокументировано в кулинарной книге SRE incident responder.

Шаг 3 — Запуск Сессии

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

python

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=env.id,
    title="Quickstart session",
)

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

Шаг 4 — Стриминг Событий

Откройте стрим, отправьте пользовательское сообщение, читайте события до session.status_idle:

python

with client.beta.sessions.events.stream(session.id) as stream:
    client.beta.sessions.events.send(
        session.id,
        events=[{
            "type": "user.message",
            "content": [{"type": "text",
                         "text": "Generate first 20 Fibonacci numbers, save to fib.txt"}],
        }],
    )
    for event in stream:
        match event.type:
            case "agent.message":
                for block in event.content:
                    print(block.text, end="")
            case "agent.tool_use":
                print(f"\n[tool: {event.name}]")
            case "session.status_idle":
                break

Имена событий следуют формату {domain}.{action}. Полная схема — в документации по событиям и стримингу. Поле processed_at важно: если оно null, событие в очереди, но ещё не выполнено. Я пропустил это при первом запуске и думал, что инструменты молча падают.

Контрольные Точки по Стоимости

Managed Agents тарифицирует две вещи: стандартные ставки за токены плюс $0,08 за час активной работы сессии. Согласно официальной странице цен, время работы начисляется по миллисекундам — но только пока статус running. Время простоя и завершённые сессии не тарифицируются.

Что это означает на практике:

• Сессия, которую вы забыли закрыть во время отладки: всё ещё начисляется (если работает).
• Веб-поиск: $10 за 1 000 вызовов, тарифицируется отдельно. Исследовательские агенты быстро это набирают.
• Проверяйте активные сессии в Console tracing перед завершением работы. Проверьте актуальный путь в интерфейсе самостоятельно — раскладка Console постоянно меняется.

Распространённые Ошибки

Отсутствующий или неверный бета-заголовок. Ошибка 400, часто с сообщением о неподдерживаемых эндпоинтах. Исправление: убедитесь, что managed-agents-2026-04-01 присутствует в каждом прямом HTTP-вызове. Если вы используете SDK и всё равно получаете эту ошибку, обновите SDK.

Ограничения частоты запросов. Эндпоинты создания ограничены 60 запросами в минуту; эндпоинты чтения — 600 запросами в минуту. Ограничения уровня организации применяются поверх этого. 429 означает отступить с разбросом, а не повторять немедленно.

Молчаливый цикл инструментов. Агент продолжает вызывать инструменты, но не выдаёт финального сообщения. Проверьте трейсы сессии — обычно это необработанный requires_action, на который никогда не был отправлен ответ.

FAQ

В1: Как включить координацию нескольких агентов в Managed Agents?

Мультиагентность (вместе с памятью и результатами) всё ещё является функцией предварительного просмотра исследований. Доступ запрашивается отдельно через Claude Console. Паттерн координации — оркестратор делегирует вызываемым агентам — задокументирован в разделе мультиагентных сессий, но использовать его нельзя, пока флаг предварительного просмотра не включён для вашей организации.

В2: Можно ли проверить, какие инструменты агент вызывал во время сессии?

Да. Используйте client.beta.sessions.events.list(session.id) для программного доступа или представление трейсов в Console для хронологической временной шкалы с токенами и временными метками для каждого события.

В3: Где найти официальную кулинарную книгу по Managed Agents?

Руководства находятся на сайте Claude Cookbook — блокнот iterate-fix-failing-tests лучший для первого чтения. Блокнот operate-in-production охватывает хранилища, MCP и вебхуки, когда вы выйдете за пределы этапа hello-world.

В4: Есть ли способ тестировать без затрат на время работы сессии?

Бесплатного уровня специально для Managed Agents не существует. Стандартные бесплатные кредиты API покрывают его. Держите сессии короткими во время разработки и закрывайте их, когда прекращаете работу. Сессии в простое не тарифицируются, но работающие тарифицируются — и «работающие» включают молчаливо зацикленных агентов.

В5: Какая лучшая модель для длительных задач Managed Agents?

Зависит от того, что означает «длительные». Для многочасовых рассуждений с интенсивным использованием инструментов — Opus 4.7. Для высококонкурентных, более простых циклов Sonnet 4.6 с кэшированием промптов значительно снижает стоимость. Я всё ещё тестирую Opus 4.7 на сессиях продолжительностью свыше двух часов. Вот где заканчиваются мои данные. Будет продолжение.

Всё ещё проверяю, как работает уплотнение после двухчасовой отметки. Запустите сами — это расскажет вам больше, чем я могу.

Предыдущие посты:

• Godmod3 AI Explained
• Claude Opus 4.7 Unified Model & API Layer
• Agentic Workflow Tool Wiring: Patterns & Pitfalls
• GLM-5V Turbo vs GPT-4o Vision UI & Coding
• How to Set Up G0DM0D3 OpenRouter 2026