Açık konuşayım: Microsoft Teams için bir agent yazmak, bugüne kadar koddan çok kayıt işi demekti. Hani asıl heyecan, agent’ın ne yaptığı olmalıydı, değil mi? FAQ cevaplayan bir bot, standup toplayan bir asistan, ya da SharePoint’ten bilgi çeken bir yardımcı… Ama daha o mantığa gelmeden Azure portalı ile Developer Portal arasında gidip geliyordunuz.
Geçen hafta Logosoft’ta, bankacılık tarafındaki bir müşteride aynı duvara biz de çarptık. Ekipteki bir geliştirici arkadaş Teams’e basit bir bilgi tabanı agent’ı bağlayacaktı — kod tarafı belki 200 satırdı, yanı öyle göz korkutan bir şey değildi — ama kayıt, kimlik, manifest, sideload derken ilk gün böyle geçti. İkinci gün hâlâ debug yapıyorduk. Üçüncü gün iş bana geldi.
İşte tam da bu noktada devreye giriyor.
İşte Microsoft 365 Developer ekibinin yeni duyurduğu teams-dev agent skill. Yenilenen Teams CLI, tam da bu uğraşı azaltmaya geliyor. En azından anlatılan bu. Ben de oturup denedim; bazı yerleri baya iş görüyor, bazı kısımları içinse “biraz daha pişmesi lazım” dedim açıkçası. Anlatayım.
Bugünkü Durum: Neden Bu Kadar Acı Verici?
Teams için bir agent kaydetmeye kalkınca, insan önce “tamam ya, iki üç ayar yaparım” diye düşünüyor. Sonra olay uzuyor. Birden kendinizi Azure portalında App Registration açarken buluyorsunuz, ardından başka bir ekranda client ID ile client secret üretip not ediyorsunuz, derken Bot Framework tarafında ayrı bir bot kaydı, sonra messaging endpoint, sonra Developer Portal’da manifest… Evet, baya dağılıyor.
- Azure portalında bir App Registration oluştur
- Client ID ve client secret üret, bir kenara not et
- Bot Framework tarafında bot kaydı yap (ayrı bir blade) — ciddi fark yaratıyor
- Messaging endpoint’i tanımla — ciddi fark yaratıyor
- Developer Portal’a geç, manifest yaz
- İzinleri (RSC permissions, valid domains, vs.) ayarla
- App package’ı zıp’le
- Teams’e sideload et
- Hata aldığında… başa dön
Lafı gevelemeden söyleyeyim: tek tek bakınca bu adımlar öyle korkunç görünmüyor. Ama işin aslı şu ki, gerçek hayatta üç farklı portal arasında zıplıyorsunuz; bir sekmede manifest JSON’u açık, diğerinde Azure var, bir başkasında Teams duruyor (arada GUID kopyalamayı unutuyorsunuz tabii), sonra manifest reddediliyor. İşte, peki neden? Çünkü “valid domain” kısmına ufak bir format hatası girince her şey sessizce bozulabiliyor; agent yükleniyor ama mesajları alamıyor. Şey… can sıkıcı biraz.
“Bir Teams agent’ı çalışır hâle getirmek için harcanan zamanın yaklaşık %70’i, agent’ın ne yaptığıyla alakasız altyapı işleridir.” — Bu cümle Microsoft’tan değil, benden. Ama saha gerçeği bu.
Evet. Ve en sınır bozucu kısmı da bu zaten.
Bazen küçük gıbı duran bir detay bütün akışı bozuyor; mesela yanlış tenant seçiyorsunuz ya da izinleri eksik bırakıyorsunuz, sonra uğraş dür (ciddiyim). Az önce basit dedim ama tam öyle değil aslında: kurgu sade görünüyor, pratikte işe insanı sürekli geri çektiren minicik taşlar var yolda.
Araya gireyim: Neyse, çok dağıtmadan toparlayayım: Teams agent işi koddan çok kurulum ritüeline dönüyor. Şimdi, siz ne dersiniz?
Coding Agent’a Devret: teams-dev Skill
Küçük bir detay: Yeni yaklaşımın özü şu aslında: Madem Copilot, Claude Code ya da Cursor. Elinin altında duruyor, o zaman kayıt işini de onlara bırak. teams-dev agent skill tam olarak bunu yapıyor, yanı senin yerinde koşturup duruyor.
İnanın, Bak şimdi, kod editörüne şunu yazıyorsun:
- Bana FAQ cevaplayan bir Teams agent’ı kur”
- Agent’ım Teams’te yüklenmiyor, neden bakar mısın?”
- Bunu production’a hazırla” — bunu es geçmeyin
Skill arka planda CLI’ı kullanıyor; sign-in’den çalışan agent’a kadar işi toparlıyor, bir yerde patlarsa troubleshooting tarafına da giriyor. Sadece altyapıyı değil, Teams SDK best practice’lerine uygun application logic yazmayı da destekliyor; hani bazen insan “bu iş sadece deploy mu?” diye düşünüyor ya, değil işte.
Pratikte Nasıl Hissettiriyor?
Hafta sonu evde denedim. Cursor’da basit bir prompt yazdım: “Bir Teams agent yap, kullanıcı ‘standup’ yazınca takım üyelerinden bugünkü işlerini sorsun.” Üç dakika sonra hem kod hem de çalışan kayıt elimdeydi. Manifest’i hiç açmadım. Azure portalına hiç girmedim. Şaşırdım açıkçası.
Garip gelecek ama, Ama dür bir saniye — burada kara kutu hissi de var. İlk agent’ı kurarken arkada ne olduğunu görmek istiyorsanız (ben çoğu müşteride bunu öneriyorum), CLI’ı doğrudan kullanmak daha mantıklı geliyor; skill işe üstüne bir abstraction katmanı koyuyor. Bu katman pratik ama öğrenme tarafında biraz fren olabiliyor.
Bakın, burayı atlarsanız yazının kalanı anlamsız kalır.
CLI Tarafı: Tek Komutla Kayıt
Skill’in altında çalışan asıl iş, yenilenmiş Teams CLI. Direkt kontrol sevenler için, hani bence en ilginç taraf da burada başlıyor. Kurulum da öyle göz korkutmuyor:
npm install -g @microsoft/teams.cli@preview
teams loginSonra o eski 9 adımlık dolaşma, tek komuta iniyor. Şaşırtıcı ama öyle:
teams app create --name "My Bot" \
--endpoint https://my-bot.example.com/api/messages \
--env.envBu komut sessiz sedasız app registration açıyor, credential üretiyor, manifest hazırlıyor, valid domain ayarlarını yazıyor ve .env dosyasına gereken environment variable’ları basıyor; yanı ne AZURE_CLIENT_ID‘yi elle kopyalayıp duruyorsun ne de secret manager’a tek tek ekleme yapıyorsun. Açık konuşayım, baya iş görüyor.
Kurulum Linki: Zıp Devri Bitiyor mu?
Eskiden agent’ı Teams’e sokmak için app package zipleyip sideload yapardık, sonra da “appsource’a yüklemek için tekrar paketle” diye dönüp dururduk (en azından benim deneyimim böyle). Yeni CLI’da app create sonrası sana doğrudan bir installation link veriyor; linki açıyorsun, Teams kurulumu kendi hallediyor. Manuel zıp işi yok. Burada, peki neden?
Bunu Türkiye’deki şirketler açısından düşününce tablo biraz netleşiyor. En çok da birden fazla tenant’a deploy yapan ISV’ler için bu ciddi rahatlık; mesela bir telekom müşterimizde Teams app’i dört farklı child tenant’a yayıyorduk, her tenant için ayrı zıp ve manuel admin onay süreci vardı, iş uzadıkça uzuyordu ama installation link modeli bunu belirgin biçimde sadeleştiriyor. Yine de bir şey var: enterprise tenant’larda admin consent. App policy katmanları hâlâ devrede, yanı link sihirli değnek değil.
Peki neden?
Hata Ayıklama: app doctor Komutu
Bu kısmı açık konuşayım, baya hoşuma gitti. Yeni CLI’da teams app doctor diye bir komut var; agent’ın kayıt durumunu, credential’ları, endpoint erişilebilirliğini (ciddiyim). Manifest’i tek tek yokluyor, yanı tek (söylemesi ayıp) ekranda “neresi bozuk” sorusuna fena olmayan bir cevap veriyor. İşte tam da aradığımız şey bu.
| Kontrol | Durum | Detay |
|---|---|---|
| App Registration | ✅ OK | Client ID geçerli |
| Credentials | ⚠️ Uyarı | Secret 12 gün içinde dolacak |
| Endpoint | ❌ Hata | HTTPS 503 dönüyor |
| Manifest | ✅ OK | Schema 1.17 valid |
Evet. Geçen ay bir müşteride tam buna ihtiyacım vardı. Agent çalışıyordu, sonra bir gün sessizce durdu; herkes loglara bakıyor, servis mi çöktü diye uğraşıyor, ama işin aslı secret expire olmuş ve bunu kimse fark etmemişti. app doctor elimizde olsaydı, o klasik iki saatlik kazı yerine beş dakikada kök sebebi görürdük; hatta belki kahve daha soğumadan mesele kapanırdı (ki bu çoğu kişinin gözünden kaçıyor)
Kısacası, peki neden? Çünkü bu komut tek başına bile CLI’a geçmek için yeterli bir sebep gıbı duruyor, abartmıyorum. Bir de güzel tarafı şu: her CLI komutu --json output destekliyor,. Çıktıyı alıp CI pipeline’larda parse edebiliyorsunuz; Azure DevOps tarafında teams app doctor --json sonucunu okuyup secret süresi dolmadan otomatik yenileme tetiklemek gıbı senaryolar gayet rahat kuruluyor. Şey… eskiden bunun için üç ayrı script yazardık, şimdi iş biraz daha derli toplu gidiyor.
Bir dakika — bununla bitmedi.
Türkiye’deki Kurumsal Yapılar İçin Pratik Notlar
Şimdi işin yerel tarafına gelelim. Kurumsal müşterilerde gördüğüm tablo biraz böyle: Türkiye’de Teams agent’ları, açık konuşayım, hâlâ tam oturmamış bir kullanım alanında duruyor. Çoğu büyük firma Teams’i mesajlaşma için kullanıyor, ama platform tarafını pek kurcalamıyor; yanı işin aslı, agent geliştirmek hâlâ niş kalıyor.
Ne var ki son 6-8 ayda hava değişti. Mesela finans. Sigorta tarafında Copilot ile agent senaryoları masaya daha sık geliyor (bunu birkaç toplantıda birebir gördüm), şu anda iki müşterimde Teams üzerinden çalışan internal agent projesi de dönüyor — biri İK politikalarını cevaplıyor, diğeri compliance sorularını toparlıyor. Evet, bayağı somut örnekler bunlar.
Çok konuştum, örnekle göstereyim.
Küçük Ekip mi, Enterprise mı? Senaryo Karşılaştırması
İlginç olan şu ki, Burada tek doğru yok, ona göre bakalım. Hangı yaklaşımı seçeceğiniz biraz ekip yapınıza, biraz da sabrınıza bağlı; çünkü küçük ekipte hız kazanmak istiyorsunuz, büyük yapıda işe aynı işi herkesin aynı şekilde anlaması gerekiyor.
- 2-5 kişilik startup / ürün ekibi: teams-dev skill + Cursor/Copilot kombinasyonuna direkt gidin. Time-to-first-prototype saatler içinde gelir. Manifest nedir diye kafa yormanız gerekmez; önce bir şey çalışsın yeter. Hız her şey.
- 20-50 kişilik orta ölçek: CLI’ı doğrudan kullanın. Skill güzel ama bir abstraction katmanı daha ekliyor; ekipteki herkesin aynı mental model’e sahip olması işinizi rahatlatır.
teams app create+teams app doctorikilisi çoğu yerde yeterli oluyor. - Enterprise / büyük kurumsal: CLI’ı kullanın ama CI/CD pipeline’ınıza gömün. Manuel
teams loginyerine service principal ile auth kurun,--jsonçıktısını parse eden custom validation script’leri ekleyin, secret rotation otomasyonunu da unutmayın; çünkü tenant policy’leriniz var, app catalog onay süreçleri var ve skill’in “ben hallederim” tavrı burada duvara tosluyor.
Maliyet Açısından Bir Bakış
Kısa cevap: CLI ve skill ücretsiz. Uzun cevap biraz farklı; agent’ı çalıştırırken arkada Azure tarafında maliyet birikiyor. Bu iş bazen sessizce — itiraz edebilirsiniz tabi — şişebiliyor (özellikle log, model çağrısı ve altyapı üçlüsü aynı anda devreye girince). Tipik bir Teams agent setup’ı için tablo aşağı yukarı şöyle:
- App Service (B1 tier): Aylık ~13 USD — düşük trafikli iç agent için gayet yeterli oluyor
- Azure Bot Service (F0 tier): Standart kanallar için ücretsiz kalıyor
- Application Insights: İlk 5 GB ücretsiz, sonrası ~3 USD/GB civarına çıkıyor
- Azure OpenAI (eğer kullanıyorsanız): Token bazlı çalışıyor; GPT-4o ile binlerce kullanıcılı bir FAQ bot için aylık 100-500 USD bandı görülebiliyor (bu kritik)
Şahsen, TL bazında düşününce küçük bir iç agent ayda kabaca 500-1500 TL bandında dönebiliyor. Bütçe sıkışıksa App Service yerine Azure Functions consumption plan’a geçmeyi düşünebilirsiniz; çünkü agent trafiği çoğu zaman sürekli değil, aralıklı geliyor ve serverless burada baya iş görüyor. Bu konuyu daha detaylı anlattığım Cosmos DB Maliyet Optimizasyonu: AI Yüklerinde 7 Taktık yazısında benzer mantığı veri katmanı için de işlemiştim.
Evet.
Şimdi, peki neden? Visual Studio 18.5: VSIX Projeleri Artık SDK-Style yazımızda bu konuya da değinmiştik.
İlk Adımlar: Bugün Ne Yapmalısınız?
Lafı gevelemeden söyleyeyim, eğer denemek istiyorsanız işin sırası baya net. Önce ortamı toparlayın, sonra ufak bir şey çalıştırın, en sonda da daha karışık kısma geçin; yoksa ilk hatada neyin patladığını anlamak biraz sınır bozuyor.
- Bir test tenant’ı bulun (production tenant’ında ilk denemeyi yapmayın, ricam) (bu kritik)
- CLI’ı kurun:
npm install -g @microsoft/teams.cli@preview(bu kritik) teams loginile kimliğinizi verin- Basit bir echo bot ile başlayın:
teams app create --name "EchoBot" --endpoint <your-tunnel-url> - Local’de tunnel için ngrok ya da dev tunnel kullanın
- Verilen installation link’i Teams’te açın, kurun
- İlk mesajı atın, çalışıyorsa skill kısmına geçin (bu kritik)
Evet, bu kadar basit görünüyor. Kısacası, ama işin aslı biraz başka; ben şahsen önce CLI tarafını bir iki kez çevirmenizi öneriyorum, çünkü skill’e direkt atlarsanız ve bir şey bozulursa (ki genelde ufak bir ayar yüzünden bozuluyor), debug ederken elinizde tutacak sağlam bir referans kalmıyor. İlginç, değil mi? Neyse uzatmayayım, burada amaç önce zemini görmek. DSC v3.2.0 Çıktı: Windows Resource’ları, Bicep ve Daha yazımızda bu konuya da değinmiştik. Daha fazla bilgi için Copilot Code Review Faturalandırması: Actions Dakikası Devri yazımıza bakabilirsiniz.
Agent framework’lerle ilgili daha geniş bir perspektif için Microsoft Agent Framework’te Chat History: Nerede yazımı da okuyabilirsiniz; oradaki mental model burada da işinize yarar. Hatta bazen beklemediğiniz kadar yarar,. Konuşma geçmişiyle uygulama davranışı arasındaki bağ sandığınızdan daha sıkı oluyor. Siz ne dersiniz?
Çok konuştum, örnekle göstereyim.
Eksik Bulduğum Yanlar
Size bir şey söyleyeyim, Tarafsız olayım dedim,. Bazı yerlerde açık konuşayım; beğenmediğim noktalar var, hatta birkaç tanesi baya can sıkıyor.
Birinçisi, preview etiketi öyle kenarda dursun denecek bir şey değil. CLI bazı edge case’lerde patlıyor — özellikle proxy arkasındaki kurumsal makinelerde teams login bazen takılı kalıyor, ilk denememde bende de MFA ekranı popup olarak açılmadı; sonra environment variable ile çözdüm. Dokümantasyonda buna dair tek satır göremedim.
Evet.
İkincisi, teams app doctor fena olmayan bir komut, iş görüyor da diyebilirim, fakat şu an Bot Framework Channel sağlık kontrolünü yapmıyor; yanı Teams kanalı bağlı mı, statüs ne durumda — bunu hâlâ Azure portalında bakarak anlıyorsunuz, biraz tuhaf kaçıyor doğrusu. Bu tarafın eklenmesi lazım.
Peki neden?
Üçüncüsü ve bence en hayatı kısım şu: skill’in coding agent’a verdiği talimatlar bazen fazla sert davranıyor. Cursor’da denerken benden izin istemeden dosyalar oluşturdu, üstüne bir de package.json’a paketler ekledi; küçük projede çok sorun olmayabilir ama büyük bir mono-repo’da bu iş biraz baş ağrıtıyor. Skill seviyesinde “ask before write” gıbı bir mod olsa daha yerinde ölür.
Tam da öyle.
Sıkça Sorulan Sorular
teams-dev skill ile Teams Toolkit arasında ne fark var?
Bak şimdi, Teams Toolkit aslında Visual Studio Code içinde grafik arayüzlü, scaffold odaklı bir extension. teams-dev skill işe Copilot, Claude Code, Cursor gıbı AI coding agent’larıyla konuşma diliyle çalışıyor ve altta yenilenmiş CLI’ı kullanıyor. Toolkit hâlâ destekleniyor; yanı skill onun yerine geçmiyor, bence güzel bir tamamlayıcı alternatif sunuyor.
Mevcut Teams agent’larımı yeni CLI’a taşımam şart mı?
Hayır, zorunlu değil. Eski yöntemle kayıtlı agent’larınız zaten çalışmaya devam ediyor. Ama açıkçası yeni geliştirmelerde CLI’ı kullanmak ciddi zaman kazandırıyor; üstelik app doctor gıbı komutlar mevcut agent’larınızı da inceleyebiliyor (en azından benim deneyimim böyle)
CLI production deploy için uygun mu, yoksa sadece dev ortamına mı bakıyor?
Şimdi, size bir şey söyleyeyim, Production için tasarlandı. Burada, en çok da --json çıktıları ve service principal authentication desteği CI/CD’ye sokmak için var. Yanı bu tarafı düşünülmüş. Ama şu an üstünde preview etiketi var; tecrübeme göre kritik production iş yüklerinizde önce bir staging tenant’ında test etmenizi öneririm.
Skill kullanırken hassas verilerim coding agent’a gidiyor mu?
teams-dev skill yerel makinenizdeki CLI’ı çağırıyor. Ama hani Copilot, Claude gıbı coding agent’ların kendi telemetri ve veri politikaları da devreye giriyor. Kurumsal ortamlarda büyük ihtimalle coding agent’ın enterprise modunu. Data residency ayarlarını kontrol edin; bence bu adımı atlamayın.
Hangı Node.js versiyonu lazım?
Node.js 18 LTS ve üzeri destekleniyor. Ben Node 20 LTS ile test ettim, sorunsuz çalıştı. Node 16 ve altında npm install aşamasında hata alıyorsunuz, dikkat edin (buna dikkat edin)
Kaynaklar ve İleri Okuma
Bakın, From prompt to production: Teams agent setup, simplified — Microsoft 365 Developer Blog
Teams CLI Resmî Dokümantasyonu
Microsoft Teams SDK GitHub Reposu (issue ve discussion için)
Bakın, küçük bir detay: Microsoft Teams Platform Developer Documentation (şaşırtıcı ama gerçek)
20+ yıl deneyimli Azure Solutions Architect. Microsoft sertifikalı bulut mimari ve DevOps danışmanı. Azure, yapay zekâ ve bulut teknolojileri üzerine Türkçe teknik içerikler üretiyor.
İlgili Yazılar
Bu içerik işinize yaradı mı?
Benzer içerikleri kaçırmamak için beni sosyal medyada takip edin.
