Jak zbudować Claude Managed Agents z Claude Sonnet 5

Chciałeś kiedyś uruchomić workflow w stylu Claude Code z poziomu skryptu Pythona, w którym model działa w zarządzanym środowisku z dostępem do narzędzi, plików, umiejętności i instrukcji?

Claude Managed Agents są stworzone właśnie do takiego workflow, pomagając budować agentów, którzy wykonują wieloetapowe zadania w kontrolowanym środowisku.

W tym poradniku pokażę, jak używać Claude Sonnet 5, najnowszego modelu od Anthropic zaprojektowanego do zaawansowanego rozumowania, kodowania i analizy danych. To on napędza zdolność agenta do inspekcji danych, używania narzędzi, pisania i wykonywania kodu oraz tworzenia ustrukturyzowanych wyników.

Utworzysz Managed Agenta, skonfigurujesz jego środowisko, prześlesz plik CSV i dasz agentowi dostęp do narzędzi oraz umiejętności XLSX. 

Agent przeanalizuje dane, wygeneruje pliki Python, JSON i Excel, zweryfikuje wyniki i udostępni gotowe artefakty do pobrania.

Jeśli dopiero zaczynasz z Claude, najpierw polecam zajrzeć do kursu Claude Code 101.

Czym są Claude Managed Agents?

Claude Managed Agents to zarządzany framework Anthropic do uruchamiania Claude jako autonomicznego agenta. 

Zamiast pisać własną pętlę do wysyłania promptów, wykonywania wywołań narzędzi, zapisywania wyników i zarządzania runtime, definiujesz agenta i pozwalasz Anthropic zająć się infrastrukturą. 

Został zaprojektowany do dłuższych, wieloetapowych zadań, w których model może potrzebować kilku narzędzi, zanim zakończy pracę.

Managed Agents opierają się na czterech głównych elementach:

• Agent: wielokrotnego użytku konfiguracja zawierająca model, prompt systemowy, narzędzia, serwery MCP i umiejętności.
• Środowisko: miejsce, w którym agent działa — w chmurowym sandboxie Anthropic lub w twoim własnym, hostowanym u siebie sandboxie.
• Sesja: działająca instancja agenta, która wykonuje konkretne zadanie.
• Zdarzenia: wiadomości, wywołania narzędzi, wyniki i aktualizacje statusu wymieniane w trakcie trwania sesji.

1. Wymagania wstępne dla twojego workspace agenta Claude

Aby przerobić ten poradnik, zainstaluj Pythona 3.12 lub nowszego oraz Jupyter Notebook na swoim komputerze. Użyjemy Jupyter Notebooka, aby krok po kroku tworzyć, uruchamiać i sprawdzać Managed Agenta.

Będziesz też potrzebować konta w Anthropic Console. 

Utwórz nowy klucz API w Console, dodaj co najmniej 5 USD kredytów API i bezpiecznie zapisz klucz. 

Managed Agents mogą wykonywać kilka wywołań modelu i narzędzi w jednej sesji, więc mogą kosztować więcej niż standardowe zapytanie do API.

Przechowuj klucz jako zmienną środowiskową ANTHROPIC_API_KEY zamiast dodawać go bezpośrednio do notatnika lub commitować do GitHuba.

Dla macOS, Linuksa lub WSL uruchom to w terminalu:

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

Dla Windows PowerShell użyj:

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

2. Skonfiguruj Anthropic Python SDK

Zanim utworzysz Managed Agenta, zainstaluj oficjalne Anthropic Python SDK i zaimportuj moduły potrzebne do tego notatnika. 

SDK udostępnia klienta Anthropic, którego użyjesz do tworzenia agentów, środowisk, plików i sesji. 

%pip install -q --upgrade anthropic

Następnie wczytaj swój klucz API Anthropic ze zmiennej środowiskowej. 

Trzymanie klucza poza notatnikiem jest bezpieczniejsze niż wstawianie go bezpośrednio w kod, zwłaszcza jeśli planujesz udostępniać projekt lub wypchnąć go na GitHuba.

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 są obecnie dostępne przez beta API Anthropic. Flaga beta managed-agents-2026-04-01 włącza tę funkcję, choć oficjalne SDK automatycznie wysyła wymagany nagłówek beta dla żądań Managed Agents. 

Zostawiamy flagę w notatniku, bo później jest potrzebna przy listowaniu i pobieraniu plików sesji. 

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

client = Anthropic(api_key=api_key)

Na koniec utwórz słownik do przechowywania identyfikatorów każdego zasobu tworzonego w trakcie poradnika. 

Obejmuje to agenta, środowisko, przesłany plik i sesję. Zapisanie tych ID ułatwia sprzątanie na końcu, nawet jeśli późniejszy krok się nie powiedzie.

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

Klient jest gotowy. 

3. Utwórz Managed Agenta

Managed Agent to wielokrotnego użytku konfiguracja twojego workflow. 

Tworząc go, wybierasz model Claude, piszesz prompt systemowy definiujący jego rolę i instrukcje oraz dołączasz narzędzia i umiejętności, z których może korzystać. 

Następnie możesz używać tego samego agenta w wielu sesjach, zamiast za każdym razem odtwarzać konfigurację. 

Nazwiemy naszego agenta Sonnet 5 Data Analyst i użyjemy claude-sonnet-5. 

Prompt systemowy mówi mu, by zachowywał się jak skrupulatny analityk danych: sprawdzał pliki zamontowane w /workspace, używał wykonania kodu do analizy, trzymał wyniki zwięzłe i zapisywał końcowe pliki do /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 daje agentowi dostęp do wbudowanych narzędzi Anthropic w sesji, a umiejętność xlsx zapewnia wskazówki specyficzne dla zadań związanych z tworzeniem i analizą skoroszytów Excela. 

Anthropic udostępnia też gotowe umiejętności do PowerPointa, Worda i workflowów PDF.

Na koniec zapisz ID agenta. 

Użyjesz go przy tworzeniu sesji, a w sekcji sprzątania pozwoli zarchiwizować agenta po zakończeniu poradnika.

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

Powinieneś zobaczyć wynik podobny do:

✓ Created agent: agent_01EVcgvQsAkLxNnJFp6aynwm

4. Skonfiguruj chmurowy sandbox Anthropic

Teraz utworzymy środowisko, w którym Managed Agent będzie działał podczas sesji. 

Środowisko działa jako bezpieczny sandbox, dając agentowi osobny workspace do czytania zamontowanych plików, pisania kodu i uruchamiania poleceń.

Użyjemy chmurowego środowiska Anthropic z ograniczonym networkingiem. Agent wykorzysta ten sandbox później do analizy przesłanego pliku CSV w Pythonie.

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}")

Po uruchomieniu komórki powinieneś zobaczyć ID środowiska podobne do:

✓ Created environment: env_01FzWACEf9UJDL65ovBPA1zf

5. Prześlij dane przez Anthropic Files API

Teraz prześlemy zbiór danych, który agent przeanalizuje. 

Managed Agents używają Anthropic Files API do uploadu lokalnych plików, które następnie można zamontować w środowisku sesji.

W tym przewodniku używamy przykładowego, 12-wierszowego zbioru o nazwie sales_data.csv. 

Przed przesłaniem sprawdzamy, czy plik istnieje i potwierdzamy, że zawiera oczekiwaną liczbę wierszy danych.

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}"

Następnie przesyłamy plik i zapisujemy jego ID do późniejszego sprzątania.

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

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

Po uruchomieniu komórki powinieneś zobaczyć wynik podobny do:

✓ Uploaded sales_data.csv: file_011Cch3EubJkswPdo3gMBvM2 (12 rows)

6. Zainicjuj sesję wykonania agenta

Teraz utworzymy sesję. 

Sesja łączy agenta, środowisko i zasoby potrzebne do konkretnego zadania. Tutaj montujemy przesłany plik CSV pod /workspace/sales_data.csv, aby agent miał do niego dostęp w sandboxie.

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}")

Powinieneś zobaczyć ID sesji podobne do:

✓ Created session: sesn_015mNhrKhqqfe7u8VP6GuFdr

7. Strumieniuj odpowiedź agenta

Teraz wyślemy zadanie do sesji i będziemy strumieniować aktywność agenta podczas pracy. 

Utworzenie sesji tylko przygotowuje agenta i sandbox; agent zaczyna pracę, gdy otrzyma zdarzenie user.message. 

Strumień zdarzeń pozwala nam na żywo śledzić wiadomości agenta, wywołania narzędzi i końcowy status sesji. 

Prompt mówi agentowi, by przeanalizował zamontowany plik CSV, napisał i uruchomił skrypt Pythona, utworzył podsumowanie JSON i przygotował raport w Excelu. 

Tworzymy też trzy zmienne do zbierania tekstu agenta, zapisania użytych narzędzi i potwierdzenia, czy sesja zakończyła się powodzeniem.

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)

Podczas działania powinieneś zobaczyć zdarzenia narzędzi takie jak read, bash, write i edit. 

Pokazują one, że agent przegląda dostępne instrukcje i pliki, pisze skrypt analityczny, uruchamia go w sandboxie i poprawia znalezione problemy.

Sesja przechodzi w stan idle, gdy agent nie ma już nic do zrobienia. W tym przykładzie session.status_idle oznacza, że zadanie jest ukończone, więc przestajemy nasłuchiwać strumienia. 

Anthropic zarządza wykonaniem swoich wbudowanych narzędzi w sandboxie; samodzielnie obsługujesz wyniki narzędzi tylko w przypadku narzędzi niestandardowych. 

8. Pobierz wygenerowane pliki i historię zdarzeń

Gdy sesja się zakończy, możemy sprawdzić zapisaną historię zdarzeń i pobrać pliki utworzone przez agenta. 

Historia zdarzeń zapewnia pełny zapis sesji, łącznie z żądaniami do modelu, wywołaniami narzędzi, wynikami narzędzi i zmianami statusu.

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)")

Następnie listujemy pliki dołączone do sesji i pobieramy te oznaczone jako możliwe do pobrania. Pliki zapisują się lokalnie w folderze 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}")

Na końcu sprawdzamy, czy wszystkie oczekiwane wyniki zostały pomyślnie pobrane:

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)}"
)

Wygenerowany skrypt Pythona, podsumowanie JSON i raport Excel są teraz dostępne w lokalnym folderze outputs.

9. Przeanalizuj wyniki: Python, JSON i Excel

Po ukończeniu zadania przez agenta, wygenerowane pliki są pobierane do lokalnego katalogu outputs/. 

Pliki te pokazują, że agent zrobił więcej niż tylko zwrócił tekst: napisał i wykonał kod, stworzył ustrukturyzowane dane i przygotował raport arkusza kalkulacyjnego, który można niezależnie przejrzeć.

Poniższe zrzuty ekranu pokazują trzy wygenerowane artefakty.

Ten plik zawiera kod analizy, który agent napisał i wykonał, dzięki czemu workflow jest reprodukowalny i łatwy do wglądu.

Ten plik przechowuje wyniki w ustrukturyzowanym formacie, który może być użyty przez dashboardy, API lub inne programy.

Ten plik Excela przedstawia miesięczne wyliczenia wizualnie — przychody, koszty, zysk, marże, sumy oraz wykres.

Dla 12 wierszy w sales_data.csv zweryfikowane wyniki to:

• Łączne przychody: 32 900 USD
• Łączne koszty: 14 750 USD
• Łączny zysk: 18 150 USD
• Średni miesięczny zysk: 1 512,50 USD
• Najlepszy miesiąc: grudzień (2 550 USD zysku)
• Najgorszy miesiąc: styczeń (400 USD zysku)

Skoroszyt opiera się na formułach, a nie tylko na wartościach wpisanych na sztywno. 

W trakcie działania agent odczytał dołączone instrukcje umiejętności XLSX, utworzył skoroszyt, przeliczył go w LibreOffice, sprawdził formuły i naprawił problem z referencją cykliczną przed ukończeniem zadania.

10. Posprzątaj zasoby Managed Agent API

Zasoby Managed Agenta pozostają dostępne, dopóki ich nie usuniesz, więc ważne jest, by posprzątać po zakończeniu zadania. 

Aktywne zasoby — zwłaszcza działające sesje i środowiska — mogą generować koszty, jeśli pozostaną uruchomione.

Sesja musi być w stanie idle, zanim będzie można ją usunąć. 

W tym ostatnim kroku usuwamy sesję, przesłany plik i środowisko, a następnie archiwizujemy agenta. 

Każdą czynność sprzątania opakowujemy w funkcję pomocniczą, aby nieudane usunięcie jednego zasobu nie zatrzymało usuwania pozostałych.

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.")

Powinieneś zobaczyć wynik podobny do:

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

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

Kompletny projekt, w tym notatnik, przykładowy plik CSV i instrukcje setupu, jest dostępny na GitHubie. 

Możesz sklonować repozytorium i ponownie uruchomić notatnik, aby odtworzyć wyniki z tego przewodnika.

Końcowe przemyślenia

Claude Managed Agents okazały się dla mnie łatwe do skonfigurowania i użycia. 

Tworzysz agenta, dajesz mu narzędzia, umiejętności i sandbox, którego potrzebuje, a potem uruchamiasz go w sesji. 

Od tego momentu może obsłużyć kompletny workflow — napisać kod, utworzyć pliki, sprawdzić własne wyniki i zwrócić finalne artefakty.

Najpierw próbowałem użyć Modal Sandbox, bo chciałem bardziej elastyczne środowisko zewnętrzne. 

Jednak konfiguracja stała się zbyt złożona jak na zakres tego przewodnika, więc zdecydowałem się skupić ten projekt na zarządzanym chmurowym sandboxie Anthropic.

Głównym minusem był dla mnie koszt. Uruchomiłem ten przykład dwukrotnie, używając małego pliku CSV z tylko 12 wierszami, i koszt wyniósł około 0,25 USD. 

Dashboard pokazał opłatę w ramach modelu, ale nie mogłem znaleźć szczegółowego rozbicia. Jak na proste zadanie obliczeniowe i arkusz kalkulacyjny, to wydaje się drogie w porównaniu z tańszymi opcjami open source.

Podsumowując, ten projekt pokazuje pełny workflow Managed Agenta: utworzenie agenta, upload pliku CSV, uruchomienie Pythona w zarządzanym sandboxie, generowanie raportów JSON i Excel, weryfikację wyników, pobranie plików i posprzątanie zasobów po wszystkim.