Как создать управляемых агентов Claude с помощью Claude Sonnet 5

Хотели ли вы когда‑нибудь запускать рабочий процесс в стиле Claude Code из Python‑скрипта, где модель работает в управляемой среде с доступом к инструментам, файлам, навыкам и инструкциям?

Управляемые агенты Claude (Claude Managed Agents) созданы именно для таких сценариев и помогают строить агентов, способных выполнять многошаговые задачи в контролируемой среде.

В этом руководстве я покажу, как использовать Claude Sonnet 5 — недавнюю модель Anthropic, предназначенную для задач продвинутого рассуждения, программирования и анализа данных. Она обеспечивает способность агента анализировать данные, использовать инструменты, писать и исполнять код, а также формировать структурированные результаты.

Вы создадите управляемого агента, настроите его среду, загрузите CSV‑файл и дадите агенту доступ к инструментам и навыку для XLSX. 

Агент проанализирует данные, сгенерирует файлы Python, JSON и Excel, проверит результаты и подготовит готовые артефакты к загрузке.

Если вы совсем новичок в Claude, сначала рекомендую посмотреть курс Claude Code 101.

Что такое управляемые агенты Claude?

Claude Managed Agents — это управляемая платформа Anthropic для запуска Claude как автономного агента. 

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

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

Управляемые агенты состоят из четырёх основных частей:

• Агент: многократно используемая конфигурация, которая включает модель, системный промпт, инструменты, MCP‑серверы и навыки.
• Среда: место, где запускается агент — в облачной «песочнице» Anthropic или в вашей собственной, размещённой у вас.
• Сессия: исполняемый экземпляр агента, выполняющий конкретную задачу.
• События: сообщения, вызовы инструментов, результаты и обновления статуса, которыми обмениваются в ходе сессии.

1. Предварительные требования для рабочего пространства агента Claude

Чтобы пройти это руководство, установите Python 3.12 или новее и Jupyter Notebook на свой компьютер. Мы будем использовать Jupyter Notebook, чтобы пошагово создавать, запускать и проверять управляемого агента.

Вам также понадобится аккаунт в Anthropic Console. 

Создайте новый API‑ключ в Console, пополните как минимум на $5 кредитов API и сохраните ключ в надёжном месте. 

Управляемые агенты могут выполнять несколько вызовов модели и инструментов в рамках одной сессии, поэтому они могут стоить дороже, чем стандартный запрос к API.

Сохраните ключ в переменной окружения ANTHROPIC_API_KEY, а не добавляйте его прямо в ноутбук или репозиторий GitHub.

Для macOS, Linux или WSL выполните в терминале:

export ANTHROPIC_API_KEY="your-api-key-here"

Для Windows PowerShell используйте:

$env:ANTHROPIC_API_KEY="your-api-key-here"

2. Установите Anthropic Python SDK

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

SDK предоставляет клиент Anthropic, с помощью которого вы будете создавать агентов, среды, файлы и сессии. 

%pip install -q --upgrade anthropic

Далее загрузите ключ Anthropic API из переменной окружения. 

Хранить ключ вне ноутбука безопаснее, чем вставлять его прямо в код, особенно если вы планируете делиться проектом или отправлять его на GitHub.

import os
from anthropic import Anthropic

api_key = os.environ.get("ANTHROPIC_API_KEY")
assert api_key, "Set ANTHROPIC_API_KEY in your environment or in a local .env file."

Доступ к Managed Agents сейчас осуществляется через бета‑API Anthropic. Флаг бета‑версии managed-agents-2026-04-01 включает эту функцию, хотя официальный SDK автоматически отправляет нужный бета‑заголовок для запросов Managed Agents. 

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

BETA_FLAG = "managed-agents-2026-04-01"

client = Anthropic(api_key=api_key)

Наконец, создайте словарь для хранения идентификаторов всех ресурсов, созданных в ходе руководства. 

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

created = {"agent": None, "environment": None, "file": None, "session": None}
print("✓ Anthropic client initialized.")

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

3. Создайте управляемого агента

Управляемый агент — это многократно используемая конфигурация вашего рабочего процесса. 

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

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

Мы назовём нашего агента Sonnet 5 Data Analyst и используем claude-sonnet-5. 

Системный промпт предписывает ему вести себя как внимательный аналитик данных: изучать файлы, смонтированные в /workspace, использовать выполнение кода для анализа, формулировать результаты кратко и сохранять итоговые файлы в /mnt/session/outputs.

agent = client.beta.agents.create(
    name="Sonnet 5 Data Analyst",
    model="claude-sonnet-5",
    system=(
        "You are a meticulous data analyst. When asked about data, always read the "
        "file mounted at /workspace, analyse it with the code execution tool, and "
        "report concise, numeric results. Use the XLSX skill for spreadsheet work. "
        "Save final artifacts to /mnt/session/outputs."
    ),
    tools=[
        {"type": "agent_toolset_20260401"},
    ],
    skills=[{"type": "anthropic", "skill_id": "xlsx"}],
)

Инструментарий agent_toolset_20260401 даёт агенту доступ к встроенным инструментам Anthropic в рамках сессии, а навык xlsx предоставляет специализированные указания по созданию и анализу рабочих книг Excel. 

Anthropic также предлагает преднастроенные навыки для рабочих процессов PowerPoint, Word и PDF.

И в конце — сохраните идентификатор агента. 

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

created["agent"] = agent.id
print(f"✓ Created agent: {agent.id}")

Вы должны увидеть примерно такой вывод:

✓ Created agent: agent_01EVcgvQsAkLxNnJFp6aynwm

4. Настройте облачную «песочницу» Anthropic

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

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

Мы будем использовать облачную среду Anthropic с ограничённой сетью. Позже агент применит эту «песочницу», чтобы проанализировать загруженный CSV‑файл с помощью Python.

environment = client.beta.environments.create(
    name="code-exec-sandbox",
    config={"type": "cloud", "networking": {"type": "limited"}},
)

created["environment"] = environment.id
print(f"✓ Created environment: {environment.id}")

После выполнения ячейки вы должны увидеть идентификатор среды наподобие:

✓ Created environment: env_01FzWACEf9UJDL65ovBPA1zf

5. Загрузите данные через Files API Anthropic

Теперь загрузим набор данных, который агент будет анализировать. 

Управляемые агенты используют Files API Anthropic для загрузки локальных файлов, которые затем можно смонтировать внутри среды сессии.

В этом примере мы используем демонстрационный набор из 12 строк под названием sales_data.csv. 

Перед загрузкой проверим, что файл существует, и подтвердим ожидаемое количество строк данных.

from pathlib import Path

csv_path = Path("sales_data.csv")
assert csv_path.exists(), f"Missing input file: {csv_path.resolve()}"

row_count = sum(1 for _ in csv_path.open(encoding="utf-8")) - 1
assert row_count == 12, f"Expected 12 data rows, found {row_count}"

Затем загружаем файл и сохраняем его идентификатор для последующей очистки.

uploaded = client.beta.files.upload(file=csv_path)

created["file"] = uploaded.id
print(f"✓ Uploaded {csv_path}: {uploaded.id} ({row_count} rows)")

После выполнения ячейки вы увидите примерно такой вывод:

✓ Uploaded sales_data.csv: file_011Cch3EubJkswPdo3gMBvM2 (12 rows)

6. Инициализируйте сессию выполнения агента

Теперь создадим сессию. 

Сессия связывает агента, среду и ресурсы, необходимые для конкретной задачи. Здесь мы монтируем загруженный CSV‑файл по пути /workspace/sales_data.csv, чтобы агент мог получить к нему доступ внутри «песочницы».

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    resources=[
        {
            "type": "file",
            "file_id": uploaded.id,
            "mount_path": "/workspace/sales_data.csv",
        },
    ],
)

created["session"] = session.id
print(f"✓ Created session: {session.id}")

Вы должны увидеть идентификатор сессии наподобие:

✓ Created session: sesn_015mNhrKhqqfe7u8VP6GuFdr

7. Стриминг ответа агента

Теперь отправим задачу в сессию и будем транслировать активность агента по мере выполнения. 

Создание сессии лишь подготавливает агента и «песочницу»; агент начинает работу после получения события user.message. 

Поток событий позволяет видеть сообщения агента, вызовы инструментов и итоговый статус сессии в реальном времени. 

Промпт говорит агенту проанализировать смонтированный CSV‑файл, написать и запустить Python‑скрипт, создать JSON‑сводку и построить отчёт Excel. 

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

agent_text_parts = []
tools_used = []
final_status = None

with client.beta.sessions.events.stream(session.id) as stream:
    # Send the user message once the stream is open.
    client.beta.sessions.events.send(
        session.id,
        events=[
            {
                "type": "user.message",
                "content": [
                    {
                        "type": "text",
                        "text": (
                            "Use the XLSX skill and analyze /workspace/sales_data.csv. "
                            "Write /mnt/session/outputs/analyze_sales.py, run that Python "
                            "script, and have it create /mnt/session/outputs/summary.json. "
                            "Also create /mnt/session/outputs/sales_report.xlsx with the "
                            "source data, monthly profit, and a summary sheet."
                        ),
                    }
                ],
            }
        ],
    )

    for event in stream:
        etype = getattr(event, "type", None)

        if etype == "agent.message":
            for block in event.content:
                txt = getattr(block, "text", None)
                if txt:
                    print(txt, end="")
                    agent_text_parts.append(txt)

        elif etype == "agent.tool_use":
            name = getattr(event, "name", "<tool>")
            print(f"\n[tool_use] {name}")
            tools_used.append(name)

        elif etype == "session.status_idle":
            final_status = "idle"
            print("\n\n✓ Agent finished; session is idle.")
            break

        elif etype == "session.status_error":
            final_status = "error"
            print("\n✗ Session reported an error.")
            break

print("Tools used:", tools_used)

Во время выполнения вы увидите события инструментов, такие как read, bash, write и edit. 

Это показывает, что агент изучает доступные инструкции и файлы, пишет скрипт анализа, запускает его внутри «песочницы» и исправляет найденные проблемы.

Сессия становится «бездействующей», когда у агента больше нет работы. В этом примере session.status_idle означает, что задача завершена, поэтому мы прекращаем чтение потока. 

Anthropic управляет выполнением своих встроенных инструментов внутри «песочницы»; вам нужно самостоятельно обрабатывать результаты только при использовании пользовательских инструментов. 

8. Получите сгенерированные файлы и историю событий

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

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

history = client.beta.sessions.events.list(session.id, order="asc")

print("--- Session event history ---")
for event in history.data:
    print(event.type)

print(f"({len(history.data)} events total)")

Далее мы перечислим файлы, прикреплённые к сессии, и загрузим все, помеченные как доступные для загрузки. Файлы сохраняются локально в папку outputs.

import os

os.makedirs("outputs", exist_ok=True)

files = client.beta.files.list(scope_id=session.id, betas=[BETA_FLAG])
downloadable = [f for f in files.data if f.downloadable]

print(f"Found {len(downloadable)} downloadable file(s) for this session.")

downloaded_paths = []

for f in downloadable:
    try:
        content = client.beta.files.download(f.id, betas=[BETA_FLAG])
        local_path = os.path.join("outputs", f.filename)

        content.write_to_file(local_path)
        downloaded_paths.append(local_path)

        print(f"  downloaded {f.id} -> {local_path}")
    except Exception as exc:
        print(f"  skip {f.id}: {exc}")

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

expected_outputs = {"analyze_sales.py", "summary.json", "sales_report.xlsx"}
downloaded_names = {os.path.basename(path) for path in downloaded_paths}

assert expected_outputs <= downloaded_names, (
    f"Missing expected outputs: {sorted(expected_outputs - downloaded_names)}"
)

Сгенерированные Python‑скрипт, JSON‑сводка и Excel‑отчёт теперь доступны в локальной папке outputs.

9. Проанализируйте выходные данные Python, JSON и Excel

После завершения задачи агента сгенерированные файлы загружаются в локальный каталог outputs/. 

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

Ниже приведены скриншоты трёх сгенерированных артефактов.

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

Этот файл хранит результаты в структурированном формате, пригодном для дашбордов, API или других программ.

Этот файл Excel наглядно показывает помесячные расчёты: выручку, затраты, прибыль, маржу, итоги и диаграмму.

Для 12 строк в sales_data.csv проверенные результаты следующие:

• Итоговая выручка: $32,900
• Итоговые затраты: $14,750
• Итоговая прибыль: $18,150
• Среднемесячная прибыль: $1,512.50
• Лучший месяц: декабрь ($2,550 прибыли)
• Худший месяц: январь ($400 прибыли)

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

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

10. Очистка ресурсов Managed Agent API

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

Активные ресурсы, особенно запущенные сессии и среды, могут продолжать приносить расходы, если их оставить работающими.

Сессию можно удалить только в состоянии «бездействует». 

На финальном шаге мы удаляем сессию, загруженный файл и среду, а затем архивируем агента. 

Каждое действие по очистке обёрнуто во вспомогательную функцию, чтобы сбой при удалении одного ресурса не прервал удаление остальных.

def safe(label, fn):
    try:
        fn()
        print(f"✓ deleted {label}")
    except Exception as exc:
        print(f"· could not delete {label}: {exc}")

if created["session"]:
    safe("session", lambda: client.beta.sessions.delete(created["session"]))

if created["file"]:
    safe("file", lambda: client.beta.files.delete(created["file"]))

if created["environment"]:
    safe("environment", lambda: client.beta.environments.delete(created["environment"]))

if created["agent"]:
    safe("agent (archived)", lambda: client.beta.agents.archive(created["agent"]))

print("\n🎉 Cleanup complete. The agent is archived; other resources were deleted.")

Вы должны увидеть примерно такой вывод:

✓ deleted session
✓ deleted file
✓ deleted environment
✓ deleted agent (archived)

🎉 Cleanup complete. The agent is archived; other resources were deleted.

Полный проект, включая ноутбук, пример CSV‑файла и инструкции по настройке, доступен на GitHub. 

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

Заключение

Управляемые агенты Claude показались мне простыми в настройке и работе. 

Вы создаёте агента, даёте ему необходимые инструменты, навыки и «песочницу», затем запускаете его через сессию. 

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

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

Однако настройка оказалась слишком сложной для рамок этого руководства, поэтому я решил сосредоточиться на управляемой облачной «песочнице» Anthropic.

Основным минусом для меня стала стоимость. Я запускал этот пример дважды, используя небольшой CSV‑файл всего с 12 строками, и это стоило около $0.25. 

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

В целом проект демонстрирует полный рабочий процесс Managed Agent: создание агента, загрузку CSV‑файла, запуск Python в управляемой «песочнице», генерацию отчётов JSON и Excel, проверку выходных данных, загрузку файлов и последующую очистку ресурсов.