Aracı örnekleri oluştur

Aracınızı yayınlayıp Microsoft yönetim merkezinde erişilebilir hale getirdikten sonra, aracı örnekleri ve aracı kullanıcıları oluşturabilirsiniz. Bu örnekler ve kullanıcılar, oluşturduğunuz aracı blueprint ve aracı kodunu kullanır.

Bu makalede süreç üç ana adımda açıklanmıştır.

  1. Teams Geliştirici Portalı'nda aracıyı yapılandır
  2. Aracı örneği oluştur
  3. Dağıtılan aracınızı test edin

Zorluklarla karşılaşırsanız, Sorun Giderme bölümüne bakınız.

Ön koşullar

1. Teams geliştirici portalında aracıyı yapılandırın

Yayınladıktan sonra, aracınızı Microsoft 365 mesajlaşma altyapısına bağlamak için Teams Developer Portal'da aracı planını yapılandırın. Bu yapılandırma olmadan, aracınız Teams, e-posta veya diğer Microsoft 365 hizmetlerinden mesaj almaz.

  1. Blueprint kimliğinizi alın

    Çalışma dizininizde a365.generated.config.json dosyasını açın ve agentBlueprintId değerini kopyalayın.

  2. Geliştirici Portalı'na gidin

    Tarayıcınızı açın ve yapılandırma sayfasına gidin:

    https://dev.teams.microsoft.com/tools/agent-blueprint/<your-blueprint-id>/configuration

    <your-blueprint-id> öğesini, kopyaladığınız agentBlueprintId değeriyle değiştirin.

    Not

    Geliştirici Portalı'na erişiminiz yoksa, kiracı yöneticinizle iletişime geçerek size erişim vermesini veya bu yapılandırmayı sizin adınıza tamamlamasını isteyin.

  3. Aracıyı yapılandırın

    Geliştirici Portalı'nda:

    1. Aracı Tipi değerini API Tabanlı olarak ayarlayın

    2. Bildirim URL'sini aracınızın mesajlaşma uç noktasına ayarlayın. a365.generated.config.json içinde messagingEndpoint değerini bulun.

    3. Kaydet'i seçin.

    Geliştirici Portalı yapılandırma sayfasının ekran görüntüsü; Aracı Tipi olarak API Tabanlı seçilmiş ve Bildirim URL alanı mevcut.

Teams'te aracı örnekleri oluşturabilmek için bu yapılandırmaya ihtiyacınız var.

Aracı kimlik şablonları ve Geliştirici Portalı yapılandırması hakkında daha fazla bilgi edinin.

2. Aracı örneği oluştur

Şimdi Teams'ten aracı şablonunuzun bir örneğini talep edebilirsiniz. Aracıyı nasıl keşfedeceğiniz, oluşturacağınız ve devreye alacağınız hakkında daha fazla bilgi edinin.

Aracı örneği talep ettiğinizde, Teams isteği onaylanmak üzere kiracı yöneticinize gönderir. Yöneticiler, Microsoft yönetim merkezi - Talep Edilen Aracılar sayfasında talepleri inceleyip onaylayabilir.

Yönetici isteğinizi onayladıktan sonra, aracı örneğiniz Teams tarafından oluşturulur ve Teams'te kullanılabilir hale getirilir.

3. Dağıtılan aracınızı test edin

Bir aracı örneği oluşturduktan sonra, üretim ortamında düzgün çalıştığını doğrulamak için Microsoft 365’te test edin.

Dağıtım tamamlandıktan ve Agent 365 SDK'da aracı bildirimleri etkinleştirildikten sonra, aracınız Microsoft 365 hizmetleriyle entegre olur. Sohbetler, kanallar ve toplantılar için Teams ile entegre çalışır; gönderme, alma ve zamanlama işlemleri için e-posta ve takvim ile entegre çalışır; belge erişimi ve dosya paylaşımı için ise SharePoint ve OneDrive ile entegre çalışır. Ayrıca organizasyon varlığı, Planner görevleri ve belge yorumları gibi iş birliği özelliklerini de destekler.

Önemli

Tıpkı normal kullanıcılar gibi, aracı kullanıcıları da hizmetlere erişmek için uygun Microsoft 365 lisanslarına ihtiyaç duyar. Yaygın lisanslar arasında Microsoft 365 E5, Teams Enterprise ve Microsoft 365 Copilot bulunmaktadır.

Yayınlanan aracıyı yönetim merkezinde görüntüleyin

Aracınızı yayınladıktan sonra, Microsoft yönetim merkezinde işe alım için görünür. Görünür hale gelmesi biraz zaman alabilir.

Microsoft 365 yönetici merkezi - Aracılar'a gidin:

  • Yayınlanan aracınızı görüntüleyin
  • Aracı ayarlarını yönet
  • Aracı kullanımını izleme
  • İzinleri yapılandırma

Teams'te test aracısı

Aracı taslağınızı dağıtıp, yayımlayıp ve yapılandırdıktan ve bir aracı kullanıcısı oluşturduktan sonra, aracı kullanıcısını doğrudan Microsoft Teams'te test edin:

Testi başlat

  1. Yeni aracı kullanıcınızı Teams'te arayın.

    Not

    Aracı kullanıcı oluşturma süreci asenkrondur. Aracı kullanıcısını oluşturduktan sonra, aranabilir hale gelmesi birkaç dakika ila birkaç saat sürebilir.

  2. Yeni oluşturduğunuz aracı örneğiyle yeni bir sohbet başlatın.

  3. Aracı işlevselliğini doğrulamak için test mesajları gönderin.

Örnek Test Mesajı

Aracıyı E-posta ile yapılandırdıysanız, e-posta işlevselliğini test etmek için bu mesajı gönderin. Alıcı recipient@contoso.com e-posta değerini güncelleyin.

Send an email to <recipient@contoso.com> with subject "Hello from Teams" and message "This is a test message from my agent!"

Aracı talebi işliyor ve e-postayı daha fazla onay gerektirmeden gönderiyor.

Doğrulama denetim listesi

Aracı örneğinizi oluşturduktan sonra, Teams'te doğru şekilde çalıştığını doğrulayın.

✅ Geliştirici portalı yapılandırması kaydedildi
✅ Aracı, Teams uygulamalarında aramada görünür
✅ Teams'de aracı örneği oluşturabilirsiniz
✅ Aracı örneği oluşturuldu
✅ Aracı kullanıcısı organizasyonda görünür
✅ Aracı mesajlara yanıt veriyor
✅ Aracı işlemler gerçekleştirebilir
✅ Uygulama kayıtlarında hata yok
✅ Yönetim merkezinde gözlemlenebilirlik çalışıyor

Aracınız beklendiği gibi çalışmıyorsa, yaygın sorunlara dair ayrıntılı çözümler için Sorun Giderme bölümüne bakınız.

Geliştirici portalı yapılandırmasının kaydedildiğini doğrulayın

Şu adrese gidin: https://dev.teams.microsoft.com/tools/agent-blueprint/<your-blueprint-id>/configuration

✅ Aracı Tipi gösteriyor: API Tabanlı✅Bildirim URL'si aracınızın mesajlaşma uç noktasıyla eşleşiyor ✅ gösteriyor 'Başarıyla kaydedildi' mesajı

Aracının Teams'te göründüğünü doğrulayın

  1. Teams >Uygulamalar'ı açın

  2. Aracınızın adını arayın

    ✅ Aracı arama sonuçlarında görünüyor: ✅ Aracı simgesi ve açıklaması gösteriliyor

Teams'de aracı örneği oluşturabildiğinizi doğrulayın

Teams Uygulamalarında aracınızı seçin

✅ Aracı Örneği İste/Oluştur butonu etkin ✅ Hata olmadan aracı örneği isteyebilirsiniz

Aracı örneğinin oluşturulduğunu doğrulayın

Örneği iste seçildikten sonra:

✅ İstek yöneticiye başarıyla gönderilir

Aracı kullanıcısının organizasyonda göründüğünü doğrulayın

Microsoft 365 yönetim merkezi'nde:

  1. Şuraya gidin: https://admin.cloud.microsoft/#/agents/all
  2. Tüm Aracılar İstekleri sekmesine gidin

✅Aracı örneği talebiniz inceleme bekleyen durumda listelenmiştir.✅Yönetici, aracı örneğini onaylayarak kullanılmasını sağlayabilir.✅Kullanıcı, Teams üzerinden bir örnek oluşturup ona bir ad verebilir.

Aracının mesajlara yanıt verdiğini doğrulayın

Teams'te aracınızla sohbet penceresinde - Test mesajı gönderin: Hello!

✅ Aracı yazıyor göstergesini gösteriyor. ✅ Aracı birkaç saniye içinde yanıt veriyor. ✅ Yanıt tutarlı ve ilgili

Aracının işlem yapabildiğini doğrulayın

Eğer araçları yapılandırdıysanız, araç işlevselliğini test edin. Örneğin, Mail MCP sunucusunu eklerseniz, kendinize bir test e-postası gönderin.

Aracı şunları gerçekleştirmelidir:

✅ Talebi karşıladığını bildir ✅ Araç çağrısını gerçekleştir ✅ Başarılı tamamlandığını doğrula

E-postanın gelen kutunuza ulaştığını doğrulamanız gerekir.

İşlevselliği doğrulayın

Aşağıdaki kontrol listesi, aracınız için sistematik bir test yöntemi sunar:

Temel işlev:

✅ Aracı basit selamlara yanıt verir. ✅ Aracı çok adımlı konuşmaları işleyebilir. ✅ Aracı uygun yanıtlar verir.

Araç işlevselliği:

MCP sunucusunun yapılandırmasına bağlıdır

✅ E-posta gönderebilir. ✅ Takvime erişebilir. ✅ Belgeleri arayabilir. ✅ Yapılandırılmış eylemleri yerine getirebilir.

Hata işleme:

✅ Geçersiz talepleri uygun şekilde ele alabilir. ✅ Açıklayıcı hata mesajları sunar. ✅ Beklenmedik girişte çökmez.

Performans:

✅ Birkaç saniye içinde yanıt veriyor. ✅ Zaman aşımı hatası yok. ✅ Tutarlı yanıt süreleri.

Uygulama günlüklerini doğrulayın

Aracınızın ne yaptığını görmek için uygulama günlüklerini az webapp log tail komutunu kullanarak kontrol edin.

# Real-time logs from Azure
az webapp log tail --name <your-web-app> --resource-group <your-resource-group>

Günlüklerde dikkat edilecekler:

✅ Teams'den gelen istekler ✅ Başarılı kimlik doğrulama ✅ Yürütülen araç çağrıları ✅ Gönderilen yanıtlar ❌ Hata mesajları veya istisnalar

Yönetim merkezinde izlenebilirliği doğrulayın

Aracınız çalışmaya başladıktan sonra:

  1. Şuraya gidin: https://admin.cloud.microsoft/#/agents/all.

  2. Aracınızı seçin ve Activity sekmesini açın.

    Aşağıdakileri görmelisiniz:

    ✅ Oturumlar görünüyor. ✅ Her oturumda tetikleyiciler ve eylemler gösterilir. ✅ Araç çağrıları zaman damgası ile kaydedilir.

Sonraki adımlar

Aracınız artık bulutta yayında ve Microsoft 365'te ekibinizle birlikte çalışmaya hazır. Başlangıçta yerel kod olarak başlatılan aracı, artık kayıtlı ve kurumsal kullanıma hazır bir asistana dönüştü; kullanıcılar, organizasyonunuz genelinde aracı örnekleri oluşturabiliyor.

Aracınızın geliştirme yaşam döngüsü tamamlandı, ancak etkisi yeni başlıyor. Agent 365 geliştirici yaşam döngüsünde oluşturduklarınızın çoğu açık kaynaklıdır ve topluluk katkılarına açıktır. Hata bildirin, özellik talep edin ve pull request gönderin:

  • Agent 365 Samples: İlginç ve eğlenceli örnek aracılarınız var mı? Aracı kodunuzu açık kaynak topluluğuyla buradan paylaşın!
  • Node.js SDK: Node.js'daki Agent 365 SDK.
  • Python SDK: Python'daki Agent 365 SDK.
  • .NET SDK: C# (.NET) dilinde Agent 365 SDK.
  • Agent 365 DevTools CLI: Agent 365 geliştirme yaşam döngüsünün her aşamasında destek sağlayan bir CLI.

Sorun giderme

Bu bölüm, aracı örnekleri oluşturma ve test etme sırasında karşılaşılan yaygın sorunları içerir.

İpucu

Agent 365 Sorun Giderme Kılavuzu yüksek seviyeli sorun giderme önerileri, en iyi uygulamalar ve Agent 365 geliştirme yaşam döngüsünün her aşamasına yönelik sorun giderme içeriğine bağlantılar sunar.

Aracı Teams'de görünmüyor

Belirti: Aracı yönetim merkezinde görünüyor, ancak Teams Uygulamaları'nda bulunamıyor.

Temel neden: Geliştirici Portalı yapılandırması eksik.

Çözüm:

  1. Blueprint ID'nizi a365.generated.config.json adresinden alın — agentBlueprintId bölümünü bulun.

  2. Geliştirici Portalında yapılandırın:

    1. Şuraya gidin: https://dev.teams.microsoft.com/tools/agent-blueprint/<your-blueprint-id>/configuration

    2. Aracı Tipi değerini API Tabanlı olarak ayarlayın

    3. Bildirim URL'sini aracınızın mesajlaşma uç noktasına ayarlayın. a365.generated.config.json içinde messagingEndpoint değerini bulun.

    4. Kaydet'i seçin.

  3. Yayılması için 5-10 dakika bekleyin.

Doğrulama:

  • Teams'i açın > Uygulamalar > Aracınızı arayın.
  • Aracı görünüyor ve eklemek için hazır.

Teams'de aracı örneği oluşturulamıyor

Belirti: Aracı Teams'te görünür ancak ekleyemez veya bir örnek oluşturamazsınız; Örnek İste düğmesi çalışmıyor.

Temel sebep: Microsoft Agent 365 Frontier kiracı için etkinleştirilmemiştir.

Çözüm: Microsoft Agent 365 Frontier'ın kiracıda etkinleştirildiğini doğrulamak için kiracı yöneticinizle iletişime geçin.

Frontier hakkında daha fazla bilgi edinin.

Doğrulama:

Lisansınız ve yönetici ayarlarınız izin verdiğinde, Frontier özellikleri Microsoft 365 Copilot ve Microsoft 365 Uygulamaları içinde kullanılabilir olur.

Aracı mesajlara yanıt vermiyor

Belirti: Bir aracı örneği oluşturuyorsunuz ancak mesajlara yanıt vermiyor. Uygulamada log kaydı görmüyorsunuz.

Ana neden: Birden fazla olası neden olabilir - mesajlaşma uç noktası sorunları, kimlik doğrulama sorunları veya yapılandırma hataları.

Temel sorun giderme

  1. Web uygulamasının çalıştığını doğrulayın:

    az webapp show --name <your-app-name> --resource-group <your-resource-group> --query state
# Should be: "Running"

  2. Mesajlaşma uç noktasını kontrol edin:

    • Şöyle olmalı: https://<your-app-root-url>/api/messages
    • Bunu a365.config.json ve a365.generated.config.json içinde doğrulayın

  3. Uç noktayı doğrudan test edin:

    curl https://<your-app-root-url>/api/messages
# Should not return 404

  4. Uygulama günlüklerini kontrol edin:

    az webapp log tail --name <your-app-name> --resource-group <your-resource-group>
# Look for incoming requests and errors

Gelişmiş tanılama

  1. Kimlik doğrulaması doğrulama:

    • Belirteçlerin süresinin dolup dolmadığını kontrol edin. Gerekirse yenileyin.
    • Web Uygulaması yapılandırmasında kimlik bilgilerini doğrulayın.

  2. Araç/MCP yapılandırmasını kontrol edin:

    • MCP sunucularının yapılandırıldığını doğrulayın.
    • İzinlerin verildiğinden emin olun.

  3. Yerel olarak test edin:

    • Aynı yapılandırmayla aracıyı yerel olarak çalıştır.
    • Agents Playground ile test yapın.
    • Eğer yerel ortamda çalışıyor ancak bulutta çalışmıyorsa, > dağıtım sorunu vardır

Yaygın çözümler

  • Mesajlaşma uç noktası hatalı: Azure portalında ve Geliştirici Portalı'nda güncelleyin.
  • Web uygulaması durduruldu: Azure portal veya CLI ile başlatın.
  • Token süresi doldu: Web App ortam değişkenlerinde tokenları güncelleyin.
  • Ortam değişkenleri eksik: Uygulama Ayarları'nı Azure portal'da kontrol edin.
  • MCP sunucu sorunları: Service principal ve izinleri doğrulayın.
  • Kod hataları: Uygulama günlüklerinde istisnalara bakın.

Doğrulama

Teams'te aracınıza bir mesaj gönderin ve uygulama günlüklerinde gelen istekleri kontrol edin.

Ayrıca şunları da denemek isteyebilirsiniz:

Araç çağrıları başarısız

Belirti: Aracı mesajlara yanıt veriyor, ancak araç çağrıları başarısız. İzin reddedildi veya zaman aşımı hatası görüyorsunuz.

Temel neden: MCP sunucu izinleri eksik, service principal yapılandırılmamış, ağ bağlantısı problemleri veya yanlış araç yapılandırması.

Çözümler

Araç çağrıları başarısızsa aşağıdaki çözümleri deneyin:

  • Yönetim merkezindeki izinleri doğrulayın

    Gerekli MCP sunucu izinlerini gözden geçirin ve onaylayın:

    • Şuraya gidin: https://admin.cloud.microsoft/#/agents/all
    • Aracınızı seçin > İzinler
    • Listenin gerekli MCP sunucularını içerdiğinden ve onayladığından emin olun

  • Servis yetkilisini kontrol edin

    Daha önce çalıştırmadıysanız, bir defalık kurulum betiğini çalıştırın:

    # Download and run:
# https://github.com/microsoft/Agent365-devTools/blob/main/scripts/cli/Auth/New-Agent365ToolsServicePrincipalProdPublic.ps1

  • MCP uç nokta yapılandırmasını doğrulayın

    Üretim MCP uç noktasını kullandığınızdan emin olun:

    # Should be production endpoint, not mock
MCP_PLATFORM_ENDPOINT=https://agent365.svc.cloud.microsoft

  • Yönetilen kimliği kontrol etme

    Web Uygulamanızda yönetilen kimliğin etkin olduğunu doğrulayın:

    # Verify managed identity is enabled
az webapp identity show --name <your-app-name> --resource-group <your-resource-group>

Doğrulama

Teams üzerinden araç çağrılarını test edin ve başarılı çalıştırıldığını doğrulamak için logları kontrol edin.

Ayrıca şu adımları denemek isteyebilirsiniz:

Lisans ataması başarısız olur

Belirti: Bir aracı kullanıcısına lisans atamazsınız. Yönetim merkezinde lisans hataları görüyorsunuz.

Temel neden: Kullanılabilir lisansların yetersizliği, yanlış lisans türü veya izin sorunu.

Çözümler

Lisans atama işlemi başarısız olduğunda aşağıdaki çözümleri deneyin:

  1. Lisansların mevcut olduğunu doğrulayın:

    • Microsoft 365 yönetim merkezi >Faturalama>Lisanslar sekmesini kontrol edin.
    • Kiracı için Microsoft Agent 365 Frontier'ın etkin olduğundan emin olun.

  2. Lisansı manuel olarak atayın:

    • Microsoft 365 yönetim merkezine gidin >Kullanıcılar.
    • Aracı kullanıcıyı bulun.
    • Uygun lisansı atayın.

  3. Tam işlevsellik için gerekli lisanslar:

    • Microsoft 365 E5 (veya eşdeğeri).
    • Teams Enterprise.
    • Microsoft 365 Copilot (Copilot özellikleri için).

Doğrulama

Yönetim merkezindeki kullanıcı profilinde atanan lisansları kontrol edin.

  • Last updated on