Teams Agent Kurulumu Artık Tek Komutla Tamam
Geçen ay bir finans kuruluşunun IT ekibiyle masadaydık. Adam bana dönüp, “Aşkın bey, biz Teams’e basit bir FAQ botu eklemek istiyoruz. Şu kayıt sürecini gören ekip arkadaşlarım vazgeçti” dedi. Gülmedim, çünkü haklıydı. Azure Portal’da App Registration, Developer Portal’da manifest, editörde wiring… Hani tek tek bakınca zor değil. Üç ayrı yerde zıplıyorsun; bir süre sonra asıl işten kopuyorsun, yani bot ne yapacak sorusu arkada kalıyor.
📋 İçindekiler
CICD Tarafına da Oturuyor mu?
Evet, oturuyor gibi duruyor çünkü her CLI komutu --json çıktısı verebiliyor. Bu ne demek? Azure DevOps ya da GitHub Actions içine rahatça bağlayabilirsiniz demek oluyor. Bot deployment işini otomatikleştirmek isteyenler için fena değil.
Burada önemli fark şu: CLI sadece yerel geliştirmeyi kolaylaştırmıyor, aynı anda pipeline mantığına da uyuyor. Yani bir ekipte “kim bot kurdu, hangi tenant’a kurdu, manifest versiyonu neydi” gibi soruların cevabını kaybetmek istemiyorsanız, JSON çıktısını sonraki adıma beslemek ciddi rahatlık sağlıyor. Büyük kurumlarda bunu görünce gözler parlar; çünkü tekrar eden işin otomasyonu her zaman güven verir.
# GitHub Actions örneği
name: Teams Bot Provisioning
on:
push:
branches:
- main
workflow_dispatch:
jobs:
build-and-provision:
runs-on: ubuntu-latest
env:
BOT_NAME: ${{ vars.BOT_NAME }}
BOT_ENDPOINT: ${{ vars.BOT_ENDPOINT }}
TEAMS_TENANT_ID: ${{ vars.TEAMS_TENANT_ID }}
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: '20'
- name: Install Teams CLI
run: npm install -g @microsoft/teams.cli@preview
- name: Validate required secrets
run: |
test -n "${{ secrets.AZURE_CLIENT_ID }}"
test -n "${{ secrets.AZURE_CLIENT_SECRET }}"
test -n "${{ secrets.AZURE_TENANT_ID }}"
- name: Login to Teams CLI
run: |
teams login --service-principal \
--client-id "${{ secrets.AZURE_CLIENT_ID }}" \
--client-secret "${{ secrets.AZURE_CLIENT_SECRET }}" \
--tenant-id "${{ secrets.AZURE_TENANT_ID }}"
- name: Create Teams App
run: |
teams app create \
--name "${{ env.BOT_NAME }}" \
--endpoint "${{ env.BOT_ENDPOINT }}" \
--tenant-id "${{ env.TEAMS_TENANT_ID }}" \
--env.env \
--json > app-output.json
- name: Verify output
run: |
cat app-output.json
node -e "const fs=require('fs'); const o=JSON.parse(fs.readFileSync('app-output.json')); if(!o.appId) process.exit(1); console.log('AppId:', o.appId)"
İlginç olan şu ki JSON çıktısını parse edip sonraki adıma besleyebiliyorsunuz; kurumsal tarafta çalışan biriyseniz bunun kıymeti hemen belli oluyor çünkü aynı işleri tekrar tekrar yapmak artık biraz eziyet gibi geliyor. Azure DevOps Git Policy Yönetimi: 10x Hız Kazanmanın Yolu, bu konudaki otomasyon yaklaşımını anlattığım başka bir yazıydı; ayrıca GPT-5.5 ve Microsoft Foundry: Kurumsal AI Artık Ciddi‘ye de göz atabilirsiniz.
Burada bir küçük pratik not daha var: Secrets ile vars ayrımını düzgün yapmak gerekiyor. Ben bir pipeline’da env var’ı secret sanıp tersine koyunca çıktı üretilmiş gibi görünüp aslında tenant doğrulaması fail olmuştu. Hani “çalışıyor gibi” görünen ama aslında yarım çalışan işler vardır ya, işte tam o kategori.
Ai Coding Agent’larla Birleşince Ne Oluyor?
Burası işin enteresan kısmı aslında. teams-dev, Copilot, Claude Code. Cursor gibi AI coding agent’larla birlikte çalışabiliyor. Yani doğal dille — İngilizce ya da Türkçe fark etmez — Teams bot kurdurabiliyorsunuz. Peki sonra?
“Help me build a Teams agent that answers FAQs from our company knowledge base”
Bitti gibi düşünebilirsiniz hatta. AI agent gerisini hallediyor; gerekli CLI komutlarını koşturuyor, hata çıkarsa üstünden geçiyor, hatta Teams SDK best practice’lerine göre uygulama mantığını kurarken size eşlik ediyor. Şey… burada biraz dikkat lazım tabii.
Kurulum tarafı da çok dolanmıyor:
/plugin marketplace add microsoft/teams-sdk
/plugin install teams-sdk@teams-skills
Benzer bir şeyi bir içerik arama botu için denedim; agent’a “şu SharePoint dokümanlarından cevap versin” dedim, o da manifest, bot endpoint ve mesaj işleme akışını oldukça düzgün bir başlangıçla kurdu. Sonra ben devreye girip şirket içi auth katmanını sıkılaştırdım. Yani işin tamamını AI’a bırakmıyorsunuz, ama ilk iskeleti kurdurtmak ciddi zaman kazandırıyor.
Burada küçük bir uyarı ekleyeyim: AI coding agent bazen komutu doğru çalıştırsa bile yanlış tenant’ta login olabiliyor ya da manifest’i eski sürümle hazırlayabiliyor. O yüzden ben bu tarz akışlarda önce doctor komutunu çalıştırıp sonra create aşamasına geçiyorum. Bu, “her şeyi otomatik yapalım” ile “bir yerde insan gözü olsun” arasında bence sağlıklı denge.
Kime Fayda Sağlıyor? Startup mı Enterprise mı?
Açık konuşayım, herkes için etkisi aynı değil. Startup tarafında bu araç resmen nefes aldırıyor; küçük ekipler iki kişilik bir sprint içinde fikirden canlı demo’ya geçmek istiyor, burada hız farkı hemen hissediliyor. Enterprise tarafında ise iş biraz daha temkinli, çünkü güvenlik ve onay kapıları devreye giriyor. Yani araç iyi, ama kurumsal gerçeklik her zaman biraz daha ağır.
| Senaryo | Startup / Küçük Ekip | Enterprise / Büyük Kurum |
|---|---|---|
| Kurulum hızı | 25 dk -> 2 dk fark net İş görür yani. |
Daha sınırlı etki — internal scriptler zaten var. Ama yine de nefes aldırır. |
| CICD entegrasyonu | Şart olmayabilir Biraz rahatlatır sadece. |
Ciddi kritik — --json altın değerde.En çok da büyük yapılarda kurtarıcı olabiliyor. |
| AI agent skill | Kurtarıcı, dev sayısı azsa daha iyi Hızlı deneme yaparsınız. |
Temkinli, güvenlik kapıları devreye girer Onay mekanizması şart olur. |
| Maliyet etkisi | Hayat kurtarıyor Saat bazında geri dönüş hissediliyor. |
Monitoring araçları zaten yanında. Ama operasyonel karmaşayı azaltması kıymetli. |
Ben bunu bir de 2024’te bir enerji şirketi PoC’inde gördüm. Küçük ekip, iç kullanım için bot istiyor; ama IT güvenlik tarafı “önce göster, sonra konuşalım” modunda. teams app doctor ile önden kontrol edip, teams app create ile hızlıca demo çıkınca havanın nasıl değiştiğini bilirim. İnsanlar teknik ayrıntıdan çok, işin hızını hissediyor.
Öte yandan büyük kurumlarda bu hız tek başına yeterli olmuyor; tenant politikaları, sideload izinleri, application consent ve loglama ihtiyaçları devreye giriyor. Yani araç güzel, ama “her şeyi çözer” demek abartı olur. Bence doğru kullanım alanı, ekip küçükse ve fikir tazeyse çok daha parlak görünüyor.
Bu Komut Çalışmazsa: 5 Tipik Hata
Burada da dürüst olayım; CLI iyi ama kusursuz değil. İlk günlerimde birkaç kez “neden olmuyor?” diye ekran başında kaldım. Sonra anladım ki hata çoğu zaman araçta değil, çevresindeki kurulumda. En sık gördüğüm beş senaryo şunlar:
1) .env dosyasında BOT_ID / BOT_PASSWORD eksik
Belirti: app create çalışır gibi olur ama bot kimliği bağlanmaz. Sahte çıktı böyle görünür: Error: Missing required environment variable BOT_ID. Çözüm basit; CLI’nın oluşturduğu değerleri doğru .env dosyasına koyup tekrar deneyin.
2) Manifest schema mismatch
Belirti: 1.16 manifest ile 1.17 şemasını karıştırdığınızda sideload aşamasında sessizce patlar. Sahte çıktı: Manifest validation failed: property 'authorization' is not allowed in schema 1.16. Çözüm: manifest version’ı ve alanları uyumlu hale getirin; migration sonrası özellikle eski alanları temizleyin.
3) Endpoint TLS sertifikası geçersiz / self-signed
Belirti: Bot dışarıdan erişilemiyor gibi görünür, doctor ise TLS uyarısı verir. Sahte çıktı: Endpoint check failed: certificate chain not trusted. Çözüm: ngrok gibi geçerli tünel kullanın ya da geliştirme sertifikanızı güvenilir hale getirin.
4) teams login yanlış tenant’a geldi
Belirti: Multi-tenant hesapla giriş yapınca CLI başka dizinde işlem yapar, siz de “neden app görünmüyor?” dersiniz. Sahte çıktı: Signed in tenant: fabrikam.onmicrosoft.com. Çözüm: --tenant-id ile açık hedef verin ve login sonrası tenant adını doğrulayın.
5) Sideload izni admin tarafında kısıtlı
Belirti: Paket oluşturulur ama Teams içinde yükleme izni çıkmaz. Sahte çıktı: Upload blocked by organization policy. Çözüm: IT admin ile Teams app permission policy ve setup policy tarafını kontrol edin; burada kullanıcı değil tenant ayarı konuşur.
Alternatifler: teams CLI vs Yeoman vs Toolkit vs Power Platform
Şunu dürüstçe söyleyeyim: Her ekip için tek doğru araç yok. Ben bazen CLI ile başlarım, bazen VS Code’da Toolkit açarım, bazen de “bu iş low-code ile daha hızlı olur” derim. Burada mesele araçların iyi-kötü olması değil; hangi işte hangisinin daha az sürtünme yarattığı.
| Araç | Güçlü Yanı | Zayıf Yanı |
|---|---|---|
| teams CLI | Yeni, preview, hızlı, AI-ready, CICD’ye çok uygun | Preview olduğu için süreçleri biraz dikkat ister |
| Yeoman generator-teams | Eski klasik, hala çalışıyor, geniş örnek ekosistemi var | Dağınık hissettirebilir; adımlar çok parça parça |
| Teams Toolkit (VS Code) | GUI sevenler için rahat, scaffold ve debug iyi | Terminal odaklı çalışan ekiplerde biraz ağır gelebilir |
| Power Platform CLI | Low-code, Power Apps ve Teams entegrasyonu için doğal seçim | Saf code-first bot senaryolarında sınırlı kalabilir |
Benim kaba ayrımım şöyle: küçük PoC ve hızlı demo için teams CLI çok iyi duruyor. Kurumsal CI/CD ve tekrar eden kurulumlarda da eli kuvvetli. Eğer ekip Power Platform ekosistemine zaten alışkınsa, oradan devam etmek daha mantıklı olabilir; sırf yeni araç var diye her şeyi değiştirmeye gerek yok, açık konuşayım bu da bazen gereksiz heves oluyor. VS Code’da rahat çalışan geliştiriciler için de Toolkit hâlâ çok temiz bir seçenek.
Yeoman ise “eski ama unutulmuş değil” kategorisinde. Bir sürü mevcut proje onun üstünde duruyor; migrate etmek zorunda değilsiniz. Hatta bazı eski kurumsal projelerde hâlâ mantıklı seçim oluyor, çünkü team zaten onu biliyor. İşi bilen ekip için doğru araç, çoğu zaman yeni olan değil; alışılmış sürtünmesi en düşük olandır.
Sık Sorulan Sorular
Bu CLI ücretsiz mi?
Evet, CLI tarafı ücretsiz gibi kullanılabiliyor. Ama tabi arka tarafta Azure, Teams policy’leri ya da başka servisler devreye girerse onların kendi maliyeti olabilir. Yani araç bedava diye tüm çözüm bedava olmuyor.
Preview olduğu için production’a alır mıyız?
Açık konuşayım, ben temkinli yaklaşırım. PoC, internal pilot ve kontrollü kurulumlarda gayet iş görür; ama üretimde kullanacaksanız release notes ve değişiklikleri yakından takip etmek lazım. Preview kelimesi burada süs değil, gerçek bir uyarı.
Mevcut Yeoman bot’larımı migrate etmek zorunda mıyım?
Hayır, zorunda değilsiniz. Çalışan bot’u sırf yeni araç çıktı diye bozmak pek akıllıca değil. Yeni proje, yeni PoC veya yeniden kurulum ihtiyacı varsa düşünmek daha mantıklı.
Tenant admin onayı gerekiyor mu sideload için?
Çoğu kurumsal ortamda evet, en azından policy tarafında bir kontrol olur. Küçük hesaplarda daha rahat görünse de büyük organizasyonlarda izinler genelde sıkıdır. Burada Teams uygulama politikası belirleyici olur.
Local development için ngrok şart mı?
Şart değil ama pratikte çok işe yarıyor. Lokal endpoint’i Teams’e göstermek için dışarıdan erişilebilir bir adres gerekir; ngrok bunu hızlı çözer. Ben demo zamanlarında hâlâ çok kullanıyorum, çünkü hız kazandırıyor.
Multi-tenant senaryosunda nasıl davranıyor?
Login olduğunuz tenant ve verdiğiniz parametreler belirleyici olur. Eğer yanlış tenant’a giriş yaparsanız app orada oluşturulur ve sonra “nerede bu kayıt?” diye dolaşırsınız. O yüzden teams login sonrası tenant doğrulamak bence alışkanlık olmalı.
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.
4 comments