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.
İşte Microsoft da bu sürtünmeyi azaltmak için yeni bir yol açmış. teams-dev agent skill ve arkasındaki Teams CLI ile artık tek komutla bot kaydından manifest üretimine, credential yönetiminden sideloading’e kadar pek çok şey akıyor. Ben bunu ilk denediğimde — açık konuşayım — “bu kadar mı?” dedim. Evet, bayağı bu kadar.
Ve işler burada ilginçleşiyor.
Bir dakika — bununla bitmedi.
Eskiden Nasıldı Bu İş?
Peki neden bu kadar can sıkıcıydı? Çünkü Teams’e bir agent eklemek istediğinizde zincir uzayıp gidiyordu (bu konuda ikircikliyim). Önce Azure Portal’a girip App Registration açıyordunuz, ardından Client ID ve Client Secret alıyordunuz; sonra Developer Portal’a geçip manifest dosyasını elle yazıyordunuz (bir virgül eksikse geçmiş olsun), en sonunda da package’ı zipleyip Teams’e sideload ediyordunuz.
Bunu bir kere yapınca insan öğreniyor tabiî (şaşırtıcı ama gerçek). Ama her yeni botta aynı döngüye girmek başka mesele. 2023’te bir telekom projesinde ekip dört farklı bir düşüneyim… Teams botu geliştiriyordu; dördüncüde junior arkadaş bana dönüp, “abi biz bot mu yazıyoruz yoksa DevOps mu yapıyoruz?” dedi. Haklıydı. Biraz sert geldi ama yerindeydi.
Bakın, burayı atlarsanız yazının kalanı anlamsız kalır. Çünkü teknik olarak zorluk çoğu zaman koddan gelmiyor; konfigürasyonların farklı panolara dağılmasından geliyor. İnsan bir süre sonra “ben bu botu kuruyorum ama niye yarım günüm başka ekranlarda gidiyor?” diye sorguluyor. Burada şirketler genelde hızlı bir PoC ister, ama süreçler kurumsal alışkanlıklarla ağır ilerler; tam o çatışma sürtünme yaratıyor.
2024’te Logosoft tarafında bir enerji şirketi PoC’inde de aynı hissi yaşadık. Ekip, saha teknisyenleri için basit bir Teams agent istiyordu. Asıl senaryo çok netti: “Sık sorulan bakım sorularını cevaplasın, bir de ticket açma linkini göstersin.” Ama ilk yarım saatin üçte biri manifest mi, app registration mı, sideload policy mi derken gitti. Açık konuşayım, bu kısım çoğu zaman proje sunumunda görünmeyen emektir; fakat işi bilen biri için en pahalı yer tam da burasıdır.
Teams CLI Tek Komutta Ne Yapıyor?
Küçük bir detay: Açıkçası, @microsoft/teams.cli diye bir araç çıkarmışlar; şu an preview’da dönüyor. Kurulum da çok uzatmıyor:
npm install -g @microsoft/teams.cli@preview
teams loginAraya gireyim: Login olduktan sonra tek komutla işi toparlayabiliyorsunuz: (kendi tecrübem)
teams app create --name "FAQ Bot" --endpoint https://my-bot.example.com/api/messages --env.envBence, bu komut arka planda neler yapıyor? App Registration açıyor, credential tarafını hazırlıyor, manifest’i oluşturuyor; yani birkaç ayrı adımı tek seferde bağlıyor (şaşırtıcı ama gerçek). Bitince de size bir installation link veriyor, tıklıyorsunuz ve Teams içinde kurulum tamamlanıyor. Zıp yok, manuel upload yok. Rahatlık burada.
Ben ilk testte endpoint olarak localhost üzerindeki ngrok tunnel’ımı verdim. 15 saniye bile sürmedi, bot Teams içinde ayağa kalktı (yanlış duymadınız). Eskiden bu iş bana 20-25 dakika yedirirdi — abartmıyorum. Tabi ilk seferde ufak bir hata da aldım: .env dosyasında BOT_ID ve BOT_PASSWORD key’lerini önceden koymam gerektiğini atlamışım. CLI bunları oluşturuyor ama dosya yoksa takılıyor; belgede yazıyor gerçi ama ilk bakışta kim okuyor ki…
Ngrok tarafını da özellikle söyleyeyim; burada çoğu geliştirici “nasıl olsa localhost çalışıyor” diye düşünüyor ama Teams dışarıdan erişilebilir bir endpoint istiyor. Ben ngrok http 3978 ile denediğimde tünel URL’si saniyeler içinde hazır oldu, o yüzden PoC’lerde hâlâ çok pratik. Evet, production değil, ama demo günü kurtarıyor. Hatta bir müşteri toplantısında tünel kopunca herkes birbirine baktı; ben de gülerek “işte gerçek hayat bu” dedim, haklıydı atmosfer biraz gergindi.
Doctor Komutu Ne İşe Yarıyor?
teams app doctor komutu var bir de; bence en az app create kadar işe yarıyor (buna dikkat edin). Tahmin eder misiniz? Agent’ın registration durumuna bakıyor, credential’ları kontrol ediyor, endpoint erişilebilir mi diye yokluyor. Manifest tarafında gariplik varsa gösteriyor.
İnanın, geçen hafta Logosoft’ta demo hazırlarken endpoint URL’sını yanlış yazmışım. Bot yüklenmiyor ama ortada düzgün hata da yok; sadece sessizlik var gibi düşünün (yanlış duymadınız). teams app doctor‘ı çalıştırdım ve direkt “endpoint unreachable” dedi. İki dakikada çözdüm işi. Eskiden böyle durumlarda Azure Portal’da Application Insights loglarına dalardım; yarım saat gitmesi normaldi.
Gerçekçi bir çıktı örneği de bırakayım; çünkü bence işin tadı burada çıkıyor. Komutun her satırı size başka bir yerden sorun gösteriyor, yani körlemesine uğraşmıyorsunuz:
teams app doctor
Checking Teams development environment...
✔ Teams CLI version: 1.0.0-preview.3
✔ Signed in account: sen.askin@contoso.com
✔ Tenant: contoso.onmicrosoft.com
✔ App registration found: FAQ Bot
✔ Manifest schema: 1.17
⚠ Endpoint validation: https://faq-bot-dev.contoso.com/api/messages
✖ Endpoint unreachable (timeout after 5000ms)
✔ Sideload package: ready
✔ Permission consent: granted
Summary: 7 checks passed, 1 warning, 1 error
Recommendation: Verify endpoint DNS/TLS and retry app create.Şu tek satırlık “Recommendation” kısmı bile bazen gün kurtarıyor. Özellikle kurumsal tarafta, herkesin aynı anda üç farklı log ekranına bakıp birbirini oyaladığı anlarda bu tip yönlendirme altın değerinde oluyor. çapraz platform agent iletişimi yazımızda bu konuya da değinmiştik.
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. kurumsal AI altyapısı yazımızda bu konuya da değinmiştik.
# 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. Daha fazla bilgi için Microsoft 365 geliştirici araçlarındaki AI yenilikleri yazımıza bakabilirsiniz.
Kurulum tarafı da çok dolanmıyor:
/plugin marketplace add microsoft/teams-sdk
/plugin install teams-sdk@teams-skillsBenzer 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.
İlgili Yazılar
Bu içerik işinize yaradı mı?
Benzer içerikleri kaçırmamak için beni sosyal medyada takip edin.
4 comments