Claude Sonnet 5 ile Claude Managed Agents Nasıl Oluşturulur

Hiç bir Python betiğinden, modelin araçlara, dosyalara, becerilere ve talimatlara erişimi olan yönetilen bir ortamda çalışabildiği Claude Code tarzı bir iş akışını yürütmek istediniz mi?

Claude Managed Agents tam da bu tür iş akışları için tasarlanmıştır; kontrollü bir ortamda çok adımlı görevleri yerine getirebilen aracılar oluşturmanıza yardımcı olur.

Bu derste, gelişmiş akıl yürütme, kodlama ve veri analizi görevleri için tasarlanmış Anthropic’in en yeni modellerinden Claude Sonnet 5’i nasıl kullanacağınızı göstereceğim. Bu model, aracının verileri inceleme, araçları kullanma, kod yazıp çalıştırma ve yapılandırılmış çıktılar üretme becerisini sağlar.

Bir Managed Agent oluşturacak, ortamını yapılandıracak, bir CSV dosyası yükleyecek ve aracıya araçlara ve bir XLSX becerisine erişim vereceksiniz. 

Aracı verileri analiz edecek, Python, JSON ve Excel dosyaları oluşturacak, sonuçları doğrulayacak ve tamamlanan çıktıları indirilebilir hale getirecek.

Claude’a tamamen yeniyseniz, önce Claude Code 101 kursuna göz atmanızı öneririm.

Claude Managed Agents Nedir?

Claude Managed Agents, Claude’u otonom bir aracı olarak çalıştırmaya yönelik Anthropic’in yönetilen çerçevesidir. 

Kendi döngünüzü yazıp istemler göndermek, araç çağrılarını yürütmek, sonuçları kaydetmek ve çalışma zamanını yönetmek yerine, aracı tanımlarsınız ve bu altyapıyı Anthropic yönetir. 

Modelin işi tamamlamadan önce birden çok aracı kullanması gerekecek daha uzun, çok adımlı görevler için tasarlanmıştır.

Managed Agents dört ana bileşen etrafında yapılandırılmıştır:

• Agent: model, sistem istemi, araçlar, MCP sunucuları ve becerileri içeren, yeniden kullanılabilir yapılandırmadır.
• Environment: aracıların çalıştığı yerdir; Anthropic’in bulut sandbox’ında ya da kendi barındırdığınız sandbox’ta olabilir.
• Session: belirli bir görevi yerine getiren çalışır durumdaki aracı örneğidir.
• Events: oturum sürerken değiş tokuş edilen iletiler, araç çağrıları, sonuçlar ve durum güncellemeleridir.

1. Claude Agent Çalışma Alanınız İçin Önkoşullar

Bu eğitimi takip etmek için bilgisayarınıza Python 3.12 veya üzeri ve Jupyter Notebook kurun. Managed Agent’ı adım adım oluşturmak, çalıştırmak ve incelemek için bir Jupyter Notebook kullanacağız.

Ayrıca bir Anthropic Console hesabına da ihtiyacınız olacak. 

Console’da yeni bir API anahtarı oluşturun, en az 5 $ API kredisi ekleyin ve anahtarı güvenli şekilde saklayın. 

Managed Agents tek bir oturumda birden fazla model ve araç çağrısı yapabilir; bu nedenle standart bir API isteğinden daha fazla maliyet oluşturabilir.

Anahtarı doğrudan not defterine eklemek veya GitHub’a göndermek yerine bir ANTHROPIC_API_KEY ortam değişkeni olarak saklayın.

macOS, Linux veya WSL için terminalinizde şunu çalıştırın:

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

Windows PowerShell için şunu kullanın:

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

2. Anthropic Python SDK’sını Kurun

Bir Managed Agent oluşturmadan önce, resmi Anthropic Python SDK’sını kurun ve bu not defteri için gereken modülleri içe aktarın. 

SDK, bu not defterinde aracıları, ortamları, dosyaları ve oturumları oluşturmak için kullanacağınız Anthropic istemcisini sağlar. 

%pip install -q --upgrade anthropic

Ardından, Anthropic API anahtarınızı bir ortam değişkeninden yükleyin. 

Anahtarı kodun içine koymak yerine not defterinin dışında tutmak, özellikle projeyi paylaşmayı veya GitHub’a göndermeyi planlıyorsanız daha güvenlidir.

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 şu anda Anthropic’in beta API’si üzerinden erişilmektedir. managed-agents-2026-04-01 beta bayrağı bu özelliği etkinleştirir; ancak resmi SDK, Managed Agents istekleri için gereken beta başlığını otomatik olarak gönderir. 

Bu bayrağı not defterinde tutuyoruz çünkü ileride oturum dosyalarını listelerken ve indirirken gerekecek.

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

client = Anthropic(api_key=api_key)

Son olarak, eğitim sırasında oluşturulan her kaynağın kimliğini saklamak için bir sözlük oluşturun. 

Buna aracı, ortam, yüklenen dosya ve oturum dahildir. Bu kimlikleri kaydetmek, ilerleyen bir adım başarısız olsa bile, sonunda temizliği kolaylaştırır.

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

İstemci artık hazır. 

3. Managed Agent’ı Oluşturun

Managed Agent, iş akışınız için yeniden kullanılabilir yapılandırmadır. 

Bir tane oluştururken Claude modelini seçer, rolünü ve talimatlarını tanımlayan sistem istemini yazarsınız ve kullanabileceği araçları ve becerileri eklersiniz. 

Böylece aynı yapılandırmayı her seferinde yeniden oluşturmadan aracı birden çok oturumda tekrar kullanabilirsiniz. 

Aracımıza Sonnet 5 Data Analyst adını vereceğiz ve claude-sonnet-5 kullanacağız. 

Sistem istemi ona dikkatli bir veri analisti gibi davranmasını söyler: /workspace içine bağlanan dosyaları incele, analiz için kod yürütmeyi kullan, sonuçlarını özlü tut ve nihai dosyaları /mnt/session/outputs konumuna kaydet.

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 aracıya bir oturumda Anthropic’in yerleşik araçlarına erişim verir; xlsx becerisi ise Excel çalışma kitapları oluşturma ve analizine yönelik görev odaklı rehberlik sağlar. 

Anthropic ayrıca PowerPoint, Word ve PDF iş akışları için de hazır beceriler sunar.

Son olarak, aracı kimliğini kaydedin. 

Bunu daha sonra bir oturum oluştururken kullanacaksınız; ayrıca, eğitim tamamlandığında temizleme bölümünün aracıyı arşivlemesine de olanak tanır.

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

Şuna benzer bir çıktı görmelisiniz:

✓ Created agent: agent_01EVcgvQsAkLxNnJFp6aynwm

4. Anthropic Cloud Sandbox’ını Yapılandırın

Sırada, Managed Agent’ın bir oturum sırasında çalışacağı ortamı oluşturacağız. 

Bir ortam, aracıya bağlanan dosyaları okuması, kod yazması ve komutları çalıştırması için ayrı bir çalışma alanı sağlayan güvenli bir sandbox görevi görür.

Sınırlı ağ erişimine sahip Anthropic’in bulut ortamını kullanacağız. Aracı bu sandbox’ı daha sonra yüklenen CSV dosyasını Python ile analiz etmek için kullanacak.

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

Hücreyi çalıştırdıktan sonra, şuna benzer bir ortam kimliği görmelisiniz:

✓ Created environment: env_01FzWACEf9UJDL65ovBPA1zf

5. Anthropic Files API ile Verileri Yükleyin

Şimdi, aracının analiz edeceği veri kümesini yükleyeceğiz. 

Managed Agents, yerel dosyaları yüklemek için Anthropic’in Files API’sini kullanır; bu dosyalar daha sonra oturum ortamının içine bağlanabilir.

Bu rehberde, sales_data.csv adlı 12 satırlık örnek veri kümesini kullanıyoruz. 

Yüklemeden önce, dosyanın mevcut olduğunu kontrol ediyor ve beklenen sayıda veri satırı içerdiğini doğruluyoruz.

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

Ardından dosyayı yüklüyor ve kimliğini daha sonra temizlik için saklıyoruz.

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

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

Hücreyi çalıştırdıktan sonra, şuna benzer bir çıktı görmelisiniz:

✓ Uploaded sales_data.csv: file_011Cch3EubJkswPdo3gMBvM2 (12 rows)

6. Bir Aracı Yürütme Oturumu Başlatın

Şimdi bir oturum oluşturacağız. 

Bir oturum, aracı, ortam ve belirli bir görev için ihtiyaç duyduğu kaynakları birbirine bağlar. Burada yüklenen CSV dosyasını /workspace/sales_data.csv konumuna bağlıyoruz; böylece aracı ona sandbox içinden erişebilir.

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

Şuna benzer bir oturum kimliği görmelisiniz:

✓ Created session: sesn_015mNhrKhqqfe7u8VP6GuFdr

7. Aracının Yanıtını Akışla İzleyin

Şimdi görevi oturuma gönderecek ve aracı çalışırken etkinliğini akışla izleyeceğiz. 

Bir oturum oluşturmak yalnızca aracı ve sandbox’ı hazırlar; aracı, bir user.message olayı aldığında çalışmaya başlar. 

Olay akışı, aracının iletilerini, araç çağrılarını ve nihai oturum durumunu gerçek zamanlı görmemizi sağlar. 

İstem, aracının bağlı CSV dosyasını analiz etmesini, bir Python betiği yazıp çalıştırmasını, bir JSON özeti oluşturmasını ve bir Excel raporu hazırlamasını söyler. 

Ayrıca, aracının metnini toplamak, kullandığı araçları kaydetmek ve oturumun başarıyla tamamlanıp tamamlanmadığını doğrulamak için üç değişken oluşturuyoruz.

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)

Çalışma sırasında read, bash, write ve edit gibi araç olaylarını görmelisiniz. 

Bunlar, aracının mevcut talimat ve dosyaları incelediğini, analiz betiğini yazdığını, bunu sandbox içinde çalıştırdığını ve bulduğu sorunları düzelttiğini gösterir.

Aracı yapacak başka bir işi kalmadığında oturum boşta (idle) durumuna geçer. Bu örnekte, session.status_idle görevin tamamlandığını belirtir; bu nedenle akışı dinlemeyi bırakıyoruz. 

Anthropic, yerleşik araçları sandbox içinde kendisi yürütür; yalnızca özel araçlar kullandığınızda araç sonuçlarını kendiniz işlemeniz gerekir. 

8. Oluşturulan Dosyaları ve Olay Geçmişini Alın

Oturum tamamlandığında, kaydedilen olay geçmişini inceleyebilir ve aracının oluşturduğu dosyaları indirebiliriz. 

Olay geçmişi; model istekleri, araç çağrıları, araç sonuçları ve durum değişiklikleri dâhil olmak üzere oturumun tam kaydını sunar.

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

Sonra, oturuma bağlı dosyaları listeliyor ve indirilebilir olarak işaretlenenleri indiriyoruz. Dosyalar yerel olarak bir outputs klasörüne kaydedilir.

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

Son olarak, beklenen tüm çıktılarının başarıyla indirilip indirilmediğini kontrol ediyoruz:

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

Oluşturulan Python betiği, JSON özeti ve Excel raporu artık yerel outputs klasöründe mevcut.

9. Python, JSON ve Excel Çıktılarını İnceleyin

Aracı görevi tamamladıktan sonra, oluşturulan dosyalar yerel outputs/ dizinine indirilir. 

Bu dosyalar, yalnızca bir metin yanıtından fazlasının yapıldığını gösterir: aracı kod yazıp çalıştırmış, yapılandırılmış veri üretmiş ve bağımsız olarak incelenebilecek bir hesap tablosu raporu oluşturmuştur.

Aşağıdaki ekran görüntüleri oluşturulan üç eseri göstermektedir.

Bu dosya, aracının yazıp yürüttüğü analiz kodunu içerir; iş akışını yeniden üretilebilir ve kolay incelenebilir kılar.

Bu dosya, sonuçları panolar, API’ler veya diğer programlar tarafından kullanılabilecek yapılandırılmış bir biçimde saklar.

Bu Excel dosyası aylık hesaplamaları görsel olarak sunar: gelir, maliyet, kâr, marjlar, toplamlar ve bir grafik.

sales_data.csv içindeki 12 satır için doğrulanmış sonuçlar:

• Toplam gelir: 32.900 $
• Toplam maliyet: 14.750 $
• Toplam kâr: 18.150 $
• Aylık ortalama kâr: 1.512,50 $
• En iyi ay: Aralık (2.550 $ kâr)
• En kötü ay: Ocak (400 $ kâr)

Çalışma kitabı, yalnızca sabit değerlerle yetinmek yerine formüle dayalıdır. 

Çalışma sırasında aracı, ekli XLSX beceri talimatlarını okudu, çalışma kitabını oluşturdu, LibreOffice ile yeniden hesapladı, formülleri kontrol etti ve görevi tamamlamadan önce bir dairesel başvuru sorununu düzeltti.

10. Managed Agent API Kaynaklarını Temizleyin

Managed Agent kaynakları siz kaldırana kadar kullanılabilir durumda kalır; bu nedenle görev tamamlandığında temizlemek önemlidir. 

Özellikle çalışan oturumlar ve ortamlar etkin bırakılırsa maliyet oluşturmaya devam edebilir.

Bir oturum, silinmeden önce boşta olmalıdır. 

Bu son adımda, oturumu, yüklenen dosyayı ve ortamı siliyor, ardından aracıyı arşivliyoruz. 

Her temizleme işlemi, daha sonra bir silme başarısız olsa bile kalan kaynakların kaldırılmasını engellemeyecek şekilde bir yardımcı işlevle sarmalanmıştır.

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

Şuna benzer bir çıktı görmelisiniz:

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

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

Not defteri, örnek CSV dosyası ve kurulum talimatları dahil eksiksiz proje GitHub’da mevcuttur. 

Bu depoyu klonlayabilir ve bu rehberdeki sonuçları yeniden oluşturmak için not defterini tekrar çalıştırabilirsiniz.

Son Düşünceler

Claude Managed Agents’ı kurmanın ve onlarla çalışmanın kolay olduğunu gördüm. 

Bir aracı oluşturuyor, ona ihtiyaç duyduğu araçları, becerileri ve sandbox’ı veriyor, ardından bir oturumda çalıştırıyorsunuz. 

Bundan sonra, kod yazma, dosya oluşturma, kendi çıktısını kontrol etme ve nihai sonuçları döndürme gibi eksiksiz bir iş akışını yönetebiliyor.

İlk olarak, daha esnek bir harici ortam istediğim için bir Modal Sandbox kullanmayı denedim. 

Ancak kurulum, bu rehberin kapsamı için fazla karmaşık hale geldi; bu yüzden projeyi Anthropic’in yönetilen bulut sandbox’ına odaklı tuttum.

Benim için temel dezavantaj maliyetti. Yalnızca 12 satırlık küçük bir CSV dosyasıyla bu örneği iki kez çalıştırdım ve yaklaşık 0,25 $ tuttu. 

Gösterge paneli ücreti model altında gösterdi, ancak ayrıntılı bir döküm bulamadım. Basit bir hesaplama ve e-tablo görevi için, daha düşük maliyetli açık kaynak seçeneklerle karşılaştırınca pahalı hissettiriyor.

Genel olarak, bu proje Managed Agent iş akışının tamamını gösteriyor: bir aracı oluşturma, bir CSV dosyası yükleme, yönetilen bir sandbox içinde Python çalıştırma, JSON ve Excel raporları üretme, çıktıları doğrulama, dosyaları indirme ve ardından kaynakları temizleme.