Claude Managed Agents'a Genel Bakış: Agent, Environment, Session ve Ne Zaman Seçilmeli?

Sürüm notu: Bu yazıdaki kodlar .NET 10, Anthropic C# SDK 13.8.0 ve Claude API version 2026-10-21 ile derlenmiş, birim testleri çalıştırılmıştır. Testler SDK'nın gerçek client'ını ağa çıkmayan sahte bir HttpMessageHandler ile kullanıyor; agent cevabı Managed Agents belgelerindeki örnekten alınmıştır. ant apply dosyaları belgedeki biçime göre yazılmıştır. Claude Managed Agents beta'dadır (managed-agents-2026-04-01); kavramlar, fiyatlar ve sınırlar 15 Kasım 2026'da platform.claude.com belgelerinden alınmıştır. Bu yazıda resmî belgelerden yararlanılmıştır.

Önce Tahmin Et

Sitedeki serilerin ortak örnek uygulaması Bookstore (bir online kitapçı) ekibinde Selin her sabah aynı soruyu soruyor: dün hangi issue'lar açıldı, hangisi release'i engelliyor? Emre beşinci yazıdaki tool loop'unu genişletip bunu yapan bir agent yazmayı düşünüyor. Ama agent'ın repo'yu klonlaması, dosya okuması, belki komut çalıştırması gerekiyor; bunun için bir sandbox, bir zamanlayıcı, oturum geçmişini saklayan bir yer ve GitHub token'ını güvenle tutan bir mekanizma lazım.

Tahminin ne? Bu altyapının ne kadarını kendin yazmalısın? Agent'ı her sabah yeniden mi oluşturursun? GitHub token'ı system prompt'a koymanın nesi yanlış? Bu yazı Claude Managed Agents'a bir genel bakış: kavramları, C# SDK'daki minimal kullanımı ve ne zaman seçileceğini anlatıyor. Agent pattern'leri ve loop'un kendisi AI Agent'ları ve MCP (Model Context Protocol; modele tool ve veri kaynaklarını standart bir yolla bağlayan protokol) serisinde anlatıldı.

Managed Agents Nedir?

Belgeye göre Managed Agents, Claude'u otonom bir agent olarak çalıştırmak için hazır bir harness ve altyapı. Agent loop'unu, tool çalıştırmayı ve runtime'ı sen yazmıyorsun; Claude'un dosya okuyabildiği, komut çalıştırabildiği, web'de arama yapabildiği ve kod çalıştırabildiği yönetilen bir ortam alıyorsun. Harness prompt caching ve compaction gibi optimizasyonları kendisi yapıyor. Belge iki yolu açıkça ayırıyor: Messages API ince kontrol ve kendi loop'un için, Managed Agents uzun süren ve asenkron işler için.

Dört kavram var:

Bütün endpoint'ler managed-agents-2026-04-01 beta header'ını istiyor; belgeye göre SDK bunu kendisi ekliyor, testimiz de bunu doğruluyor. Hazır tool'lar bash, dosya işlemleri (okuma, yazma, düzenleme, glob, grep), web search ve web fetch ile MCP server'lar. Belgenin önemli bir notu veriyle ilgili: session'lar durum tutan kaynaklar olduğu için Managed Agents ZDR (Zero Data Retention; verinin sağlayıcıda saklanmadığı anlaşma) ve HIPAA (ABD'nin sağlık verisi düzenlemesi) kapsamında değil. İstisna, 12 Kasım 2026'da çıkan self-hosted Managed Agents: servisi, session geçmişini ve sandbox'ları kendi altyapında çalıştırıyorsun, model Anthropic'te ya da seçtiğin bir sağlayıcıda çalışıyor.

Agent: Bir Kez Oluşturulan, Versiyonlu Tanım

Belge agent'ı bir kez oluşturulup id'siyle yeniden kullanılan bir kaynak olarak tarif ediyor. Bookstore'un issue özeti agent'ı:

    public static AgentCreateParams BuildAgent() => new()
    {
        Name = "Bookstore issue digest",
        Model = BetaManagedAgentsModel.ClaudeSonnet5_5,
        System = """
            You write a short morning digest of Bookstore's open issues for the development team.
            Group the issues by area (catalog, ordering, payments, support), list what changed since yesterday,
            and flag anything that blocks a release. Do not change, close or comment on any issue.
            Write the digest to /mnt/session/outputs/digest.md.
            """,
        Tools =
        [
            new BetaManagedAgentsAgentToolset20260401Params
            {
                // Özetin ihtiyacı repo, web değil.
                Configs =
                [
                    new BetaManagedAgentsWebSearchToolConfigParams { Enabled = false },
                    new BetaManagedAgentsWebFetchToolConfigParams { Enabled = false },
                ],
            },
        ],
    };

    // Agent'ı yalnız ilk seferde oluşturur; sonraki her çağrı saklanan id'yi ve versiyonu döner.
    public async Task<AgentReference> EnsureAsync(CancellationToken cancellationToken)
    {
        if (registry.Find(RegistryKey) is { } existing)
        {
            return existing;
        }

        BetaManagedAgentsAgent created = await claude.Beta.Agents.Create(BuildAgent(), cancellationToken);
        AgentReference agent = new(created.ID, created.Version);
        registry.Save(RegistryKey, agent);
        logger.LogInformation("Created agent {AgentId} version {Version}", agent.Id, agent.Version);
        return agent;
    }

EnsureAsync, agent'ı yalnız ilk çağrıda oluşturuyor ve id ile versiyonu bir kayıtta tutuyor. Her sabah yeni bir agent oluşturmak hem gereksiz hem karışık: yüzlerce özdeş agent birikir ve hangi session'ın hangi tanımla çalıştığını takip edemezsin. Testteki sahte cevap belgedeki örnek:

{"id":"agent_01HqR2k7vXbZ9mNpL3wYcT8f","type":"agent","name":"Bookstore issue digest",
"model":{"id":"claude-sonnet-5-5","effort":{"type":"medium"},"speed":"standard"},
"system":"You write a short morning digest of Bookstore's open issues.","description":null,
"tools":[{"type":"agent_toolset_20260401","default_config":{"permission_policy":{"type":"always_allow"}}}],
"skills":[],"mcp_servers":[],"multiagent":null,"metadata":{},"version":1,
"created_at":"2026-11-15T18:24:10.412Z","updated_at":"2026-11-15T18:24:10.412Z","archived_at":null}

Cevap gönderdiğin yapılandırmayı tekrar ediyor; id, version ve tarih alanlarını ekliyor, gönderilmeyen model alanlarını (burada effort: medium) varsayılanla dolduruyor. Toolset'in default_config'inde görünen always_allow varsayılan permission policy; agent'ın tool çağrıları onay beklemeden çalışıyor. Bizim agent'ımız GitHub'a yalnız okuma yetkisiyle erişeceği için bu kabul edilebilir; yazma yetkisi olan bir agent'ta onay isteyen bir policy düşünülmeli.

version 1'den başlıyor ve yapılandırmayı değiştiren her güncellemede artıyor. Güncellemede son okuduğun versiyonu gönderirsen agent bu arada değiştiyse 409 alıyorsun; göndermezsen güncelleme koşulsuz uygulanıyor. Arşivlenen bir agent salt okunur oluyor: yeni session açılamıyor ama çalışanlar devam ediyor.

Environment, Session ve Event'ler

Environment de bir kez oluşturuluyor; birçok session aynı environment'ı kullanabiliyor ama her session kendi izole Linux container'ını alıyor. Cloud environment'ta networking limited olabiliyor; belgedeki örnek paket yöneticilerine izin vermeyi gösteriyor.

Session'ı açan istek:

    // Versiyonu sabitlemek yeni agent versiyonunun kazara değil bilinçli olarak devreye girmesini sağlar.
    public static SessionCreateParams BuildSession(AgentReference agent, string environmentId, string vaultId, DateOnly day) => new()
    {
        Agent = new BetaManagedAgentsAgentParams { ID = agent.Id, Version = agent.Version },
        EnvironmentID = environmentId,
        // Credential'lar vault'ta durur ve modelin context'i dışında eklenir; asla prompt'ta değil.
        VaultIds = [vaultId],
        Title = $"Issue digest {day:yyyy-MM-dd}",
        InitialEvents =
        [
            new BetaManagedAgentsUserMessageEventParams
            {
                Content = [new BetaManagedAgentsTextBlock { Text = $"Write the issue digest for {day:yyyy-MM-dd}." }],
            },
        ],
    };

Agent id'sini düz string olarak vermek session'ı agent'ın son versiyonuyla açıyor. Object olarak versiyonla birlikte vermek onu o versiyona sabitliyor. Belge bunu yeni versiyonların devreye alınmasını kontrol etmenin yolu olarak anlatıyor: v3'ü yazarsın, birkaç session'da denersin, sonra kayıttaki versiyonu güncellersin. initial_events ile session'ı tek çağrıda hem açıp hem başlatıyoruz; belgeye göre en fazla 50 user.message ya da user.define_outcome event'i verilebiliyor. Gönderilen gövde şu:

{"agent":{"type":"agent","id":"agent_x","version":3},"environment_id":"env_x","vault_ids":["vlt_x"],"title":"Issue digest 2026-11-16","initial_events":[{"type":"user.message","content":[{"type":"text","text":"Write the issue digest for 2026-11-16."}]}]}

Session açıldıktan sonra iletişim event'lerle yürüyor. Sen user.* event'leri gönderiyorsun; session sana durum, agent mesajı ve tool kullanımı event'lerini Server-Sent Events ile akıtıyor. İşi bitince session.status_idle geliyor. Event geçmişini sunucu saklıyor ve istediğinde baştan okuyabiliyorsun. Agent'ın ürettiği dosyalar sandbox'ta /mnt/session/outputs/ altına yazılıyor ve sekizinci yazıdaki Files API ile session id'sine göre listelenip indiriliyor.

Session'a bir bütçe de verilebiliyor: liste fiyatlarıyla hesaplanan harcama sınıra ulaşınca session yeni model isteği başlatmıyor ve budget_reached sebebiyle duruyor. Gece çalışan bir agent için bu, yedinci yazıdaki maliyet izlemenin üstüne konan sert bir tavan.

Vault: Secret Prompt'a Girmez

Agent GitHub'a erişecek; token'ı nereye koyacağız? System prompt'a ya da ilk mesaja koymak en kötü seçenek: token modelin context'ine girer, event geçmişinde saklanır ve prompt injection ile dışarı sızdırılabilir. LLM Uygulama Güvenliği serisinin üçüncü yazısındaki hidden context ifşası tam olarak bu.

Managed Agents'ın cevabı vault. Belgeye göre vault, bir son kullanıcıya ait credential'ların toplandığı bir kaynak; session açılırken vault_ids ile referans veriliyor. MCP server'lar için OAuth credential'ları saklanıyor ve token yenilemeyi Anthropic yapıyor. Ortam değişkeni türündeki credential'lar ise sandbox'ta yalnız bir yer tutucu olarak duruyor; gerçek değer, agent dışarıya bir istek gönderdiğinde çıkışta yerine konuyor. Sandbox'ta çalışan kod bile gerçek değeri görmüyor. Vault session düzeyinde verildiği için ürünü agent düzeyinde, kullanıcıları session düzeyinde yönetebiliyorsun.

Agent'ı Dosya Olarak Yönetmek: ant apply

Agent'ı C# koduyla oluşturmak tek seçenek değil. ant CLI'ın ant apply komutu agent'ları, environment'ları, skill'leri ve deployment'ları repo'daki dosyalardan oluşturup güncelliyor; değişiklikler kodla aynı review'dan geçiyor. Bookstore repo'suna claude/ klasörü ekledik. Agent bir Markdown dosyası: frontmatter yapılandırma, gövde system prompt:

---
name: Bookstore issue digest
model: claude-sonnet-5-5
tools:
  - type: agent_toolset_20260401
    configs:
      - name: web_search
        enabled: false
      - name: web_fetch
        enabled: false
---
You write a short morning digest of Bookstore's open issues for the development team.
Group the issues by area (catalog, ordering, payments, support), list what changed since yesterday,
and flag anything that blocks a release. Do not change, close or comment on any issue.
Write the digest to /mnt/session/outputs/digest.md.

Environment bir YAML (insan tarafından okunabilir bir yapılandırma biçimi) dosyası:

# yaml-language-server: $schema=https://platform.claude.com/schemas/ant/beta/environment.json
name: bookstore-digest-env
description: Cloud container with limited networking for the nightly issue digest.
config:
  type: cloud
  networking:
    type: limited
    allow_package_managers: false

Sabah özetini her iş günü saat 06:00'da başlatan scheduled deployment:

---
name: Nightly issue digest
agent: ../agents/issue-digest.md
environment_id: ../environments/bookstore-cloud.yaml
schedule:
  type: cron
  expression: "0 6 * * 1-5"
  timezone: Europe/Istanbul
---

Write the issue digest for today.

Belgeye göre dosyalar birbirine göreli yolla referans veriyor; ant apply agent referansını o çalıştırmada uyguladığı versiyona sabitliyor. Cron ifadesi bir saat diliminde yorumlanıyor ve en küçük aralık bir dakika. ant apply önce bir plan gösterip onay istiyor, --dry-run hiçbir şey değiştirmeden planı yazdırıyor. İlk çalıştırma, hangi dosyanın hangi kaynağı oluşturduğunu kaydeden bir claude-lock.json yazıyor. Belge bu dosyanın commit'lenmesini istiyor; bir sonraki çalıştırma, senin makinende ya da CI'da, kaynakları yeniden oluşturmak yerine bu dosyadan buluyor. EnsureAsync'teki kaydın dosya karşılığı bu.

Deployment kullanınca session'ı açan kod bile gerekmiyor; yukarıdaki StartAsync, aynı işi Bookstore.Api'den tetiklemek istediğin durumlar için.

Ne Zaman Managed Agents?

Seri boyunca dört farklı yol gördük, beşincisi de Claude Code serisinin planlanan on ikinci yazısında:

Maliyet iki parçalı. Token'lar normal model fiyatıyla faturalanıyor ve prompt caching çarpanları aynen geçerli; batch indirimi yok, çünkü session'lar etkileşimli. Buna ek olarak session çalışma süresi var: belgeye göre session başına saatte 0,08 USD, yalnız session running durumundayken sayılıyor; idle, rescheduling ve terminated süreleri sayılmıyor. Managed Agents'ta dokuzuncu yazıdaki code execution container saati ayrıca faturalanmıyor.

Vendor bağımlılığı da hesaba girmeli. Agent tanımı, event modeli ve vault Anthropic'e özgü. Bookstore'un issue özeti gibi iç bir iş için bu kabul edilebilir; ürünün çekirdeğindeki bir agent için Microsoft Agent Framework gibi sağlayıcıdan bağımsız bir yolun da değerlendirilmesi gerekir. Self-hosted seçenek veriyi yerinde tutuyor ama bağımlılığı ortadan kaldırmıyor.

Planın kapsadığı ama burada yalnız adını andığımız özellikler: outcome'lar (bir rubric ile sonucu ayrı bir context'te değerlendiren grader ve agent'ın hedefe kadar tekrar denemesi), multiagent orchestration ve dynamic workflow'lar (agent'ın işi alt agent'lara dağıtması), memory store'lar. Hepsi aynı beta header altında.

Üretimde Dikkat

Agent ve environment id'lerini kalıcı sakla. Bellek içi kayıt bu yazının örneği; production'da bir tablo ya da claude-lock.json.

Versiyonu sabitle. Session'ları belirli bir agent versiyonuyla aç ve yeni versiyonu bilinçli olarak devreye al. Deployment'larda ant apply bunu senin yerine yapıyor.

Bütçe koy. Gece çalışan bir agent'ın döngüye girip saatlerce çalışması hem token hem session saati demek. Session bütçesi bunun tavanı.

Permission policy'yi gözden geçir. Varsayılan always_allow. Agent'ın yazma yetkisi olan bir tool'u varsa onay isteyen bir policy kullan.

Event geçmişini sil. Session'lar ve transcript'ler sen silene kadar saklanıyor; içinde müşteri verisi olabilecek session'ları iş bitince sil.

Sık Düşülen Tuzaklar

Her çalıştırmada yeni agent oluşturmak. Agent bir kez oluşturulur; session her çalıştırmada açılır.

Secret'ı prompt'a koymak. Token context'e ve event geçmişine girer. Vault kullan.

Session'ı agent'ın son versiyonuyla açmak. Agent'ı güncelleyen herkes production davranışını da değiştirmiş olur.

claude-lock.json'ı commit'lememek. Bir sonraki ant apply kaynakları yeniden oluşturur.

Managed Agents'ı her agent ihtiyacına seçmek. Birkaç turluk, process içi bir iş için beşinci yazıdaki loop daha basit ve daha ucuz.

Küçük Bir Deneme

★☆☆ IssueDigestAgent.BuildSession'a bir bütçe ekle. SDK'daki BetaManagedAgentsBudgetLimit tipine bak, belgedeki örnekle aynı JSON'u ürettiğini bir testle doğrula.

★★☆ IAgentRegistry'ye versiyon güncelleme ekle: claude.Beta.Agents.Update ile system prompt'u değiştir, dönen yeni versiyonu kaydet. Sahte handler'a 409 cevabı ekleyip eşzamanlı güncelleme durumunu test et.

★★★ Session event'lerini okuyan bir BackgroundService tasarla: event stream'i aç, agent.message metinlerini topla, session.status_idle gelince /mnt/session/outputs/digest.md dosyasını Files API ile indirip ekibe gönder. Bağlantı koparsa geçmişi baştan okuyarak kaldığın yerden nasıl devam edeceğini yaz.

Managed Agents ile serinin özellik turu bitti. On birinci ve son yazıda bütün bu parçaları production'a taşıyoruz: SDK'nın exception hiyerarşisi, otomatik retry'lar ve rate limit'ler, istek başına maliyet takibi, OpenTelemetry ve Claude'u Microsoft.Extensions.AI'a bağlayan IChatClient köprüsü.