Cum să construiești Claude Managed Agents cu Claude Sonnet 5

Ți-ai dorit vreodată să rulezi un flux de lucru în stil Claude Code dintr-un script Python, în care modelul poate lucra într-un mediu gestionat cu acces la unelte, fișiere, abilități și instrucțiuni?

Claude Managed Agents sunt concepute pentru acest tip de flux, ajutându-te să construiești agenți care pot duce la capăt sarcini în mai mulți pași într-un mediu controlat.

În acest tutorial, îți voi arăta cum să folosești Claude Sonnet 5, un model recent de la Anthropic conceput pentru raționament avansat, programare și analiză de date. El alimentează abilitatea agentului de a inspecta date, a folosi unelte, a scrie și executa cod și a produce rezultate structurate.

Vei crea un Managed Agent, îi vei configura mediul, vei încărca un fișier CSV și îi vei oferi agentului acces la unelte și la o abilitate XLSX. 

Agentul va analiza datele, va genera fișiere Python, JSON și Excel, va verifica rezultatele și va pune la dispoziție ieșirile finale pentru descărcare.

Dacă ești complet nou în Claude, îți recomand mai întâi să consulți cursul Claude Code 101.

Ce sunt Claude Managed Agents?

Claude Managed Agents este frameworkul gestionat al Anthropic pentru a rula Claude ca agent autonom. 

În loc să-ți scrii propriul loop pentru a trimite prompturi, a executa apeluri de unelte, a salva rezultate și a gestiona runtime-ul, definești agentul și lași Anthropic să se ocupe de acea infrastructură. 

Este conceput pentru sarcini mai lungi, în mai mulți pași, în care modelul poate avea nevoie să folosească mai multe unelte înainte de a finaliza munca.

Managed Agents sunt construite în jurul a patru părți principale:

• Agent: configurația reutilizabilă care conține modelul, promptul de sistem, uneltele, serverele MCP și abilitățile.
• Mediu: locul unde rulează agentul, fie în sandbox-ul în cloud al Anthropic, fie în propriul tău sandbox self-hosted.
• Sesiune: o instanță în execuție a agentului care îndeplinește o sarcină specifică.
• Evenimente: mesajele, apelurile de unelte, rezultatele și actualizările de stare schimbate în timpul rulării sesiunii.

1. Cerințe preliminare pentru spațiul tău de lucru Claude Agent

Pentru a urma acest tutorial, instalează Python 3.12 sau o versiune mai nouă și Jupyter Notebook pe computerul tău. Vom folosi un Jupyter Notebook pentru a crea, rula și inspecta Managed Agent pas cu pas.

Vei avea nevoie și de un cont Anthropic Console. 

Creează o cheie API nouă în Console, adaugă cel puțin 5 $ în credite API și salvează cheia în siguranță. 

Managed Agents pot face mai multe apeluri de model și unelte într-o singură sesiune, așa că pot costa mai mult decât o cerere standard către API.

Stochează cheia ca variabilă de mediu ANTHROPIC_API_KEY în loc să o adaugi direct în notebook sau să o comiți pe GitHub.

Pentru macOS, Linux sau WSL, rulează asta în terminal:

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

Pentru Windows PowerShell, folosește:

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

2. Configurează SDK-ul Anthropic pentru Python

Înainte de a crea un Managed Agent, instalează SDK-ul oficial Anthropic pentru Python și importă modulele necesare pentru acest notebook. 

SDK-ul oferă clientul Anthropic, pe care îl vei folosi pentru a crea agenți, medii, fișiere și sesiuni. 

%pip install -q --upgrade anthropic

Apoi, încarcă cheia ta Anthropic API dintr-o variabilă de mediu. 

Păstrarea cheii în afara notebook-ului este mai sigură decât plasarea ei direct în cod, mai ales dacă plănuiești să partajezi proiectul sau să-l urci pe 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 este accesibil în prezent prin API-ul beta al Anthropic. Steagul beta managed-agents-2026-04-01 activează această funcție, deși SDK-ul oficial trimite automat headerul beta necesar pentru cererile Managed Agents. 

Păstrăm steagul în notebook pentru că va fi necesar mai târziu când listăm și descărcăm fișierele sesiunii. 

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

client = Anthropic(api_key=api_key)

În final, creează un dicționar pentru a stoca ID-urile fiecărei resurse create în timpul tutorialului. 

Acesta include agentul, mediul, fișierul încărcat și sesiunea. Salvarea acestor ID-uri face curățarea mai ușoară la final, chiar dacă un pas ulterior eșuează.

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

Clientul este acum gata. 

3. Creează Managed Agent-ul

Un Managed Agent este configurația reutilizabilă pentru fluxul tău de lucru. 

Când creezi unul, alegi modelul Claude, scrii promptul de sistem care îi definește rolul și instrucțiunile și atașezi uneltele și abilitățile pe care le poate folosi. 

Apoi poți reutiliza același agent în mai multe sesiuni în loc să recreezi configurația de fiecare dată. 

Îi vom numi agentului nostru Sonnet 5 Data Analyst și vom folosi claude-sonnet-5. 

Promptul de sistem îi spune să se comporte ca un analist de date atent: să inspecteze fișierele montate în /workspace, să folosească execuția de cod pentru analiză, să-și păstreze rezultatele concise și să salveze fișierele finale în /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 oferă agentului acces la uneltele integrate ale Anthropic într-o sesiune, în timp ce abilitatea xlsx furnizează îndrumare specifică sarcinilor pentru crearea și analizarea foilor de calcul Excel. 

Anthropic oferă, de asemenea, abilități predefinite pentru fluxuri PowerPoint, Word și PDF.

În final, salvează ID-ul agentului. 

Îl vei folosi când creezi o sesiune mai târziu și permite și secțiunii de curățare să arhiveze agentul după ce tutorialul este complet.

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

Ar trebui să vezi o ieșire similară cu:

✓ Created agent: agent_01EVcgvQsAkLxNnJFp6aynwm

4. Configurează Anthropic Cloud Sandbox

În continuare, vom crea mediul în care rulează Managed Agent în timpul unei sesiuni. 

Un mediu acționează ca un sandbox securizat, oferind agentului un spațiu de lucru separat pentru a citi fișiere montate, a scrie cod și a rula comenzi.

Vom folosi mediul în cloud al Anthropic cu rețea limitată. Agentul va folosi acest sandbox mai târziu pentru a analiza fișierul CSV încărcat cu 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}")

După rularea celulei, ar trebui să vezi un ID de mediu similar cu:

✓ Created environment: env_01FzWACEf9UJDL65ovBPA1zf

5. Încarcă date cu Anthropic Files API

În continuare, vom încărca setul de date pe care îl va analiza agentul. 

Managed Agents folosesc Anthropic Files API pentru a încărca fișiere locale, care apoi pot fi montate în interiorul mediului sesiunii.

Pentru acest ghid, folosim setul de date exemplu cu 12 rânduri numit sales_data.csv. 

Înainte de a-l încărca, verificăm că fișierul există și confirmăm că are numărul așteptat de rânduri de date.

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

Apoi încărcăm fișierul și îi stocăm ID-ul pentru curățarea de mai târziu.

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

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

După rularea celulei, ar trebui să vezi o ieșire similară cu:

✓ Uploaded sales_data.csv: file_011Cch3EubJkswPdo3gMBvM2 (12 rows)

6. Inițializează o sesiune de execuție a agentului

Acum, vom crea o sesiune. 

O sesiune conectează agentul, mediul și resursele de care are nevoie pentru o sarcină specifică. Aici, montăm fișierul CSV încărcat la /workspace/sales_data.csv, astfel încât agentul să poată accesa fișierul din interiorul sandbox-ului.

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

Ar trebui să vezi un ID de sesiune similar cu:

✓ Created session: sesn_015mNhrKhqqfe7u8VP6GuFdr

7. Transmite în flux răspunsul agentului

Acum, vom trimite sarcina către sesiune și vom transmite în flux activitatea agentului pe măsură ce lucrează. 

Crearea unei sesiuni doar pregătește agentul și sandbox-ul; agentul începe să lucreze după ce primește un eveniment user.message. 

Fluxul de evenimente ne permite să vedem în timp real mesajele agentului, apelurile de unelte și starea finală a sesiunii. 

Promptul îi cere agentului să analizeze fișierul CSV montat, să scrie și să ruleze un script Python, să creeze un rezumat JSON și să construiască un raport Excel. 

Creăm, de asemenea, trei variabile pentru a colecta textul agentului, a înregistra uneltele folosite și a confirma dacă sesiunea se încheie cu succes.

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)

În timpul rulării, ar trebui să vezi evenimente de unelte precum read, bash, write și edit. 

Acestea arată că agentul inspectează instrucțiunile și fișierele disponibile, scrie scriptul de analiză, îl rulează în sandbox și corectează problemele pe care le găsește.

O sesiune devine inactivă când agentul nu mai are lucru de făcut. În acest exemplu, session.status_idle indică faptul că sarcina este completă, așa că ne oprim din a asculta fluxul. 

Anthropic gestionează execuția pentru uneltele integrate în interiorul sandbox-ului; trebuie să gestionezi tu rezultatele uneltelor doar când folosești unelte personalizate. 

8. Recuperează fișierele generate și istoricul evenimentelor

După ce sesiunea este completă, putem inspecta istoricul de evenimente salvat și descărca fișierele create de agent. 

Istoricul evenimentelor oferă o înregistrare completă a sesiunii, incluzând cereri ale modelului, apeluri de unelte, rezultate ale uneltelor și schimbări de stare.

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

În continuare, listăm fișierele atașate sesiunii și descărcăm orice fișiere marcate ca descărcabile. Fișierele sunt salvate local într-un folder 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}")

În final, verificăm că toate ieșirile așteptate au fost descărcate cu succes:

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

Scriptul Python generat, rezumatul JSON și raportul Excel sunt acum disponibile în folderul local outputs.

9. Analizează ieșirile Python, JSON și Excel

După ce agentul finalizează sarcina, fișierele generate sunt descărcate în directorul local outputs/. 

Aceste fișiere arată că agentul a făcut mai mult decât să returneze un răspuns în text: a scris și a executat cod, a creat date structurate și a produs un raport în foaie de calcul care poate fi revizuit independent.

Capturile de ecran de mai jos arată cele trei artefacte generate.

Acest fișier conține codul de analiză pe care agentul l-a scris și l-a executat, făcând fluxul de lucru reproductibil și ușor de inspectat.

Acest fișier stochează rezultatele într-un format structurat care poate fi folosit de dashboard-uri, API-uri sau alte programe.

Acest fișier Excel prezintă vizual calculele lunare, cu venituri, costuri, profit, marje, totaluri și un grafic.

Pentru cele 12 rânduri din sales_data.csv, rezultatele verificate sunt:

• Venit total: 32.900 $
• Costuri totale: 14.750 $
• Profit total: 18.150 $
• Profit mediu lunar: 1.512,50 $
• Cea mai bună lună: decembrie (profit 2.550 $)
• Cea mai slabă lună: ianuarie (profit 400 $)

Workbook-ul este bazat pe formule, nu doar pe valori hardcodate. 

În timpul rulării, agentul a citit instrucțiunile din abilitatea XLSX atașată, a creat workbook-ul, l-a recalculat cu LibreOffice, a verificat formulele și a remediat o problemă de referință circulară înainte de a finaliza sarcina.

10. Curăță resursele Managed Agent API

Resursele Managed Agent rămân disponibile până când le elimini, așa că este important să le cureți după ce sarcina este completă. 

Resursele active, în special sesiunile și mediile în execuție, pot continua să genereze costuri dacă sunt lăsate să ruleze.

O sesiune trebuie să fie inactivă înainte de a putea fi ștearsă. 

În acest ultim pas, ștergem sesiunea, fișierul încărcat și mediul, apoi arhivăm agentul. 

Fiecare acțiune de curățare este încapsulată într-o funcție helper astfel încât o ștergere eșuată să nu oprească eliminarea celorlalte resurse.

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

Ar trebui să vezi o ieșire similară cu:

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

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

Proiectul complet, inclusiv notebook-ul, fișierul CSV de exemplu și instrucțiunile de configurare, este disponibil pe GitHub. 

Poți clona repository-ul și poți rerula notebook-ul pentru a recrea rezultatele din acest ghid.

Gânduri finale

Am descoperit că Claude Managed Agents sunt ușor de configurat și de folosit. 

Creezi un agent, îi dai uneltele, abilitățile și sandbox-ul de care are nevoie, apoi îl rulezi într-o sesiune. 

De acolo, poate gestiona un flux de lucru complet, precum scrierea de cod, crearea de fișiere, verificarea propriilor ieșiri și returnarea rezultatelor finale.

Inițial am încercat să folosesc un Modal Sandbox pentru că îmi doream un mediu extern mai flexibil. 

Totuși, configurarea a devenit prea complexă pentru scopul acestui ghid, așa că am decis să păstrez proiectul concentrat pe sandbox-ul în cloud gestionat de Anthropic.

Principalul dezavantaj pentru mine a fost costul. Am rulat acest exemplu de două ori folosind un CSV mic cu doar 12 rânduri și a costat aproximativ 0,25 $. 

Dashboard-ul a arătat costul sub model, dar nu am putut găsi o defalcare detaliată. Pentru o sarcină simplă de calcul și foaie de calcul, pare scump în comparație cu opțiunile open-source mai ieftine.

Per total, acest proiect arată întregul flux Managed Agent: crearea unui agent, încărcarea unui fișier CSV, rularea Python într-un sandbox gestionat, generarea de rapoarte JSON și Excel, verificarea ieșirilor, descărcarea fișierelor și curățarea resurselor ulterior.