Aracı şablonunu oluşturma

Aracı şeması, aracının kimliğini, izinlerini ve altyapı gereksinimlerini tanımlar. Bu aracı şemadan her bir aracı örneğini oluşturun.

Not

Kaydetme, Work IQ ve AI ekip arkadaşı işlevlerini etkinleştirmek için bir aracı şeması oluşturulması gerekmektedir. Aracınız için hangi özelliklerin geçerli olduğunu anlamak için Agent 365 geliştirmeye başlayın bölümüne bakın.

Agent 365 Identity hakkında daha fazla bilgi için bkz. Agent 365 Identity.

Ön koşullar

Başlamadan önce, aşağıdaki önkoşulların sağlandığından emin olun:

  1. Agent 365 CLI - Agent 365 CLI yüklemesi bölümüne bakın.

  2. Gerekli izinler:

    • Aşağıdaki rollerden birine sahip geçerli kiracı kullanıcısı:
      • Genel Yönetici
      • Aracı Kimliği Geliştirici
    • Kaynak oluşturma izinlerine sahip bir Azure aboneliğine erişim

    İpucu

    Aracılar (AI takım arkadaşları hariç) bir yapılandırma dosyasına ihtiyaç duymazlar. a365 setup all --agent-name <name> kullanın; CLI, kiracınızı ve istemci uygulamanızı otomatik olarak çözümleyecektir. AI ekip arkadaşı kurulumu, manuel olarak oluşturulmuş bir a365.config.json gerektirir.

Aracı şeması oluştur

Azure kaynakları oluşturmak ve aracı taslağınızı kaydetmek için a365 setup komutunu kullanın. Bu şema, aracı kimliğini, izinlerini ve altyapı gereksinimlerini tanımlar. Bu adım, aracınızı Azure'da dağıtmak ve çalıştırmak için gerekli temeli oluşturur.

Kurulumu çalıştırma

Kurulum komutunu çalıştırın:

a365 setup -h

Bu komutun çeşitli seçenekleri vardır. a365 setup all kullanarak tüm kurulumu tek bir komutla tamamlayabilir veya daha ayrıntılı seçenekleri tercih edebilirsiniz.

Not

a365 setup all, varsayılan olarak aracı moduna geçer. Bunun yerine bir AI destekli aracı kurmak için --aiteammate değerini iletin. M365 aracıları (Teams, Copilot) için mesajlaşma uç noktasını otomatik olarak kaydetmek üzere --m365 öğesini de iletin.

Aracı kurulumu (varsayılan):

# With a config file
a365 setup all

# Config-free — no a365.config.json needed
a365 setup all --agent-name <your-agent-name>

M365 aracı kurulumu (Teams/Copilot):

# Registers the messaging endpoint via MCP Platform
a365 setup all --m365

AI ekip arkadaşı kurulumu:

a365 setup all --aiteammate

Kurulum sürecinin tamamı şu işlemleri gerçekleştirir:

  1. Azure altyapısını oluşturur (zaten mevcut değilse):

    • Kaynak grubu
    • Belirtilen STB'ye sahip App Service planı
    • Yönetilen kimlik özelliği etkinleştirilmiş Azure Web Uygulaması

  2. Aracı taslağını kaydeder:

    • Microsoft Entra kiracınızda aracı şemasını oluşturur
    • Microsoft Entra uygulama kayıtlarını oluşturur
    • Aracı kimliğini gerekli izinlerle yapılandırır
    • Platform yönetilebilirliği için gerekli olan managerApplications öğesini taslağa ayarlar

    Önemli

    Planların platform tarafından kabul edilebilmesi için managerApplications ayarının yapılması gerekir. CLI bunu otomatik olarak ayarlar. Bu gereksinim getirilmeden önce oluşturulmuş mevcut bir taslağınız varsa onu silip a365 setup all öğesini yeniden çalıştırın ya da Graph API aracılığıyla manuel olarak yama uygulayın.

  3. API izinlerini yapılandırır:

    • Microsoft Graph API kapsamlarını ayarlamak
    • Mesajlaşma Botu API izinlerini yapılandırır
    • Aracı örnekleri için devralınmış izinleri uygular

  4. Yapılandırma dosyalarını güncelleştirir:

    • Oluşturulan kimlikleri ve uç noktaları çalışma dizininizde a365.generated.config.json adlı yeni bir dosyaya kaydeder
    • Kayıtlar, kimlik ve kaynak bilgilerini yönetir

Not

Kurulum genellikle 3-5 dakika sürer ve yapılandırmayı otomatik olarak a365.generated.config.json konumuna kaydeder. Genel Yönetici olarak oturum açarsanız, CLI, yönetici onayı için bir tarayıcı penceresi açabilir; devam etmek için onay sürecini tamamlayın. Aracı Kimliği Geliştirici kimliğiyle oturum açarsanız, tarayıcı penceresi açılmaz; CLI, Genel Yönetici'nin daha sonra tamamlaması için onay URL'leri oluşturur.

Aracı Kimliği Geliştirici kullanılarak kurulum

Aracı Kimliği Geliştiricisi (Genel Yönetici değil) olarak çalıştırırsanız a365 setup all çoğu adımı otomatik olarak tamamlar ancak OAuth2 izinlerinin verilmesi için ayrı bir Genel Yönetici adımı gerekir.

Otomatik olarak tamamlanan adımlar:

  • Azure altyapısı (kaynak grubu, App Service planı, Web App)
  • Aracı şema kaydı
  • Aracı örnekleri için devralınabilir izinler

Genel Yönetici gerektiren adımlar:

  • Microsoft Graph, Agent 365 Tools, Messaging Bot API, Observability API ve Power Platform API için OAuth2 aracı izin atamaları (AllPrincipals onayı)

Yönetici olmayan bir hesap kullanarak kurulumu tamamlama:

Aşama Kim Eylem
1 Geliştirici a365 setup all'i çalıştırın. CLI, gerçekleştirebileceği tüm adımları tamamlar ve bir Genel Yönetici'nin açması gereken onay URL'si de dahil olmak üzere sonraki adımları ekrana yazar.
2 Geliştirici CLI çıktısındaki onay URL'sini Genel Yönetici'nizle paylaşın.
3 Global Yönetici Genel Yönetici olarak oturum açmış bir tarayıcıda onay URL'sini açın ve istenen izinleri verin.

Komutları çalıştırma:

# Developer runs:
a365 setup all
# Setup completes all steps it can. The CLI prints the next steps
# for a Global Administrator directly in the output, including a
# direct link or consent URL they can open to complete the grants.

CLI tarafından yazdırılan sonraki adımları Genel Yönetici'nizle paylaşın. OAuth2 yetkilendirme işlemlerini tamamlamak için kendilerine sağlanan bağlantıyı veya onay URL'sini açabilirler.

Kurulumu doğrulama

Kurulum tamamlandığında, tamamlanan tüm adımları gösteren bir özet görüntülenir. Oluşturulan kaynakları doğrulayın:

  1. Oluşturulan yapılandırmayı doğrulayın:

    Çalışma dizininizdeki a365.generated.config.json öğesini açın. Veya PowerShell'i kullanın:

    Get-Content a365.generated.config.json | ConvertFrom-Json

    Beklenen çıktı şu kritik değerleri içerir:

    {
"managedIdentityPrincipalId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"agentBlueprintId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"agentBlueprintObjectId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"agentBlueprintServicePrincipalObjectId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"agentBlueprintClientSecret": "xxx~xxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"agentBlueprintClientSecretProtected": true,
"botId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"botMsaAppId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"messagingEndpoint": "https://your-app.azurewebsites.net/api/messages",
"resourceConsents": [],
"completed": true,
"completedAt": "xxxx-xx-xxTxx:xx:xxZ",
"cliVersion": "x.x.xx"
}

    Doğrulanması gereken anahtar alanlar:

    Alan Amaç Denetlenmesi Gerekenler
    managedIdentityPrincipalId Azure yönetilen kimlik doğrulaması Geçerli bir GUID olmalı
    agentBlueprintId Aracınızın benzersiz tanıtıcısı Geliştirici Portalı ve yönetim merkezinde kullanılır
    agentBlueprintObjectId Taslağın Microsoft Entra ID'si
    messagingEndpoint İleti yönlendirme Teams/Outlook'un iletileri aracınıza gönderdiği yerler
    agentBlueprintClientSecret Kimlik doğrulama gizli dizisi Varlığı gerekir (değer maske altında gizlenmiştir)
    resourceConsents API izinleri Microsoft Graph, Agent 365 Araçları, Messaging Bot API, Observability API gibi kaynakları içermelidir
    completed Kurulum durumu true olmalıdır

    Not

    Kurulumu Agent ID Administrator veya Agent ID Developer olarak çalıştırdıysanız, CLI tarafından yazdırılan sonraki adımları kullanarak bir Global Administrator OAuth2 izin onaylarını tamamlayana kadar resourceConsents boş kalabilir ve completed, false şeklinde görünebilir.

  2. Azure kaynaklarını Azure portal üzerinden doğrulayın:

    Ya da az resource list PowerShell komutunu kullanın.

    # List all resources in your resource group
az resource list --resource-group <your-resource-group> --output table

    Aşağıdaki kaynakların oluşturulduğunu doğrulayın:

    • Kaynak Grubu:

      • Kaynak Grupları> öğesine gidin ve kaynak grubunuzu seçin
      • App Service planınızın ve Web Uygulamanızın listede yer aldığını kontrol etme

    • App Service Planı:

      • Uygulama Hizmetleri>App Service Planları'na gidin
      • Size uygun planı bulma ve fiyatlandırma katmanının yapılandırma SKU'nuzla uyumlu olup olmadığını kontrol etme

    • Web Uygulaması:

      • Uygulama Hizmetleri>Web Uygulamaları'na gidin
      • Web uygulamanızı bulun, ardından Ayarlar>Kimlik>Sistem tarafından atanan kısmına gidin
      • Durumun Açık olduğunu doğrulayın
      • Nesne (asıl) kimliğinin managedIdentityPrincipalId ile eşleştiğine dikkat edin.

  3. Azure portal içinde Microsoft Entra uygulamalarını doğrulayın:

    Azure Active Directory>Uygulama kayıtları>Tüm uygulamalar yoluna gidin:

    • Aracı planınızı agentBlueprintId ile arayın

    • Uygulamayı açın ve API izinleri seçeneğini belirleyin

    • Yeşil onay işaretleriyle verilen izinleri kontrol edin:

      • Microsoft Graph (temsilci izni ve uygulama izinleri)
      • Messaging Bot API izinleri

    • Tüm izinler "[Kiracınız] için verildi" şeklinde görünür

  4. Oluşturulan yapılandırma dosyasının oluşturulduğunu doğrulayın:

    Tüm yapılandırma verilerini içeren a365.generated.config.json adında bir dosyanız olmalıdır.

    Varlığını kontrol etmek için Test-Path PowerShell komutunu kullanın.

    # Check file exists
Test-Path a365.generated.config.json
# Should return: True

    Önemli

    Hem a365.config.json hem de a365.generated.config.json dosyalarını kaydedin. Bu değerlere, dağıtım ve sorun giderme işlemleri için ihtiyacınız olacaktır.

  5. Web uygulamasında yönetilen kimliğin etkinleştirildiğini doğrulayın:

    Yönetilen kimliğin etkinleştirilip etkinleştirilmediğini denetlemek için az webapp identity show komutunu kullanın.

    az webapp identity show --name <your-web-app> --resource-group <your-resource-group>

    Beklenen:

    {
"principalId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"tenantId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"type": "SystemAssigned"
}

  6. Microsoft Entra'da kayıtlı aracı taslağını doğrulayın:

    Microsoft Entra yönetim merkezi içinde agentBlueprintId öğenizi arayın veya ada göre arama yapın.

    Aşağıdakileri doğrulayın:

    ✅ Uygulama Kaydı ve Kurumsal Uygulama görünür
    ✅ Uygulama kaydı taslağında, API izinleri sekmesi tüm izinleri gösterir
    ✅ Durum "[Kiracınız] için verildi" şeklinde görünür

Daha fazla yardım için bkz.:

Aracı izinleri

Uygulamaların ve temsilcilerin Microsoft 365 verilerini (kullanıcılar, posta, dosyalar, Teams, aracılar vb.) okuyabilmesi veya yazabilmesi için, onlara Microsoft Graph izinlerini açıkça vermeniz gerekir. Microsoft Graph izinleri, bir uygulamanın veya hizmetin Microsoft 365 ve Microsoft Entra ID genelinde Microsoft Graph API'leri aracılığıyla hangi verilere ve eylemlere erişebileceğini kontrol eden yetkilendirme modelidir.

Daha fazla bilgi edinin: Microsoft Graph izinlerine genel bakış

Agent 365 aracı örnekleri için Graph izinlerini kullanmak üzere, geliştiricinin bunları aracı şemasında tanımlaması gerekir. Bir yönetici, Microsoft 365 Yönetim Merkezi'nde şablonu etkinleştirdiğinde, portal şablonun Graph izinlerini inceler ve yöneticiye bu izinlere onay vermesini ister.

Graph izinlerinin aracınızın işini nasıl kolaylaştırdığını anlamak ve doğrulamak için şunları yapabilirsiniz:

Şemanıza izinler uygulayın

Microsoft Entra'daki blueprint'inize satır içi özel API izinleri uygulamak için a365 setup permissions custom kullanın.

a365 setup permissions custom `
  --resource-app-id 00000003-0000-0000-c000-000000000000 `
  --scopes Mail.Read,Mail.Send,Chat.Read,Chat.ReadWrite,Chat.Create,User.Read

Özel izinleri yapılandırma ve kaldırma hakkında tüm ayrıntılar için bkz. setup permissions custom.

Sonraki adımlar

Aracı kodunuzu buluta dağıtın:

Azure

Amazon Web Services (AWS)

Google Cloud Platform (GCP)

Aracıyı Microsoft yönetim merkezinde yayımlama

Sorun giderme

Bu bölümde, aracı şemalarını ayarlarken karşılaşılan yaygın sorunlar açıklanmaktadır.

İ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.

Kayıt işlemi sırasında bazen şu sorunlar ortaya çıkabilir:

Yetersiz izin hatası

Belirti:a365 setup komutu yürütülürken yetersiz izin hatası oluştu.

Microsoft Entra kiracınızda aşağıdaki rollerden birine sahip olmanız gerekir:

  • Genel Yönetici
  • Aracı Kimliği Geliştirici

VE Azure aboneliği için katkıda bulunan veya sahip erişim hakkı.

Çözüm: Microsoft Entra'da gerekli izinlere sahip olduğunuzdan emin olun.

Not

Aracı Kimliği Yöneticisi veya Aracı Kimliği Geliştiricisi rolüne (Genel Yönetici değil) sahipseniz a365 setup all yine de başarılı olur ancak OAuth2 izin atamalarını atlar. Kurulum tamamlandıktan sonra, CLI, Genel Yönetici'nin kalan yetki atamalarını tamamlaması için gerekli sonraki adımları görüntüler. Bu iş akışı, aracı geliştiricisi ile Genel Yönetici'nin farklı kişiler olduğu organizasyonlar için öngörülmüştür.

Azure CLI kimlik doğrulaması eksik

Belirti: Kurulum, kimlik doğrulama hataları nedeniyle başarısız oluyor.

Çözüm: Azure'a bağlı olduğunuzdan emin olun ve hesabınızı ile aboneliğinizi doğrulayın.

# Authenticate with Azure
az login

# Verify correct account and subscription
az account show

Kaynak zaten var

Belirti: Kaynak grubu, App Service planı veya Web Uygulaması için kurulum Resource already exists hatasıyla başarısız oluyor.

Çözümler: Aşağıdaki çözümlerden birini seçin.

  • Mevcut kaynakları kullanın

    Eğer kaynaklar var ise ve bunları kullanmak istiyorsanız, bunların yapılandırmanızla uyumlu olduğundan emin olun. az resource list PowerShell komutunu kullanın.

    az resource list --resource-group <your-resource-group>

  • Çakışan kaynakları sil

    Kaynak grubunu silin veya a365.config.json içindeki kaynaklarınızı yeniden adlandırın ve kurulumu yeniden çalıştırın.

    Bir kaynak grubunu silmek için az group delete PowerShell komutunu kullanın.

    # WARNING: This command deletes all resources in it
az group delete --name <your-resource-group>

  • Sıfırdan başlamak için temizleme komutunu kullanın

    Tüm Agent 365 kaynaklarını kaldırmak için cleanup komutunu kullanın, ardından kurulumu yeniden çalıştırmak için a365 setup all komutunu kullanın.

    Uyarı

    a365 cleanup çalıştırılması verileri yok eder.

    a365 cleanup
a365 setup all

Belirti: Kurulum sırasında tarayıcı pencereleri açtınız ancak onay işlemini tamamlamadan kapattınız ya da kurulum tamamlandı ancak OAuth2 izin talepleri hâlâ beklemede.

Çözüm: Rolünüz doğrultusunda seçin:

  • Genel Yönetici: a365 setup all öğesini yeniden çalıştırın. CLI, yönetici onayı istiyor. Görünen tarayıcı penceresinde onay akışını tamamlayın.

  • Aracı Kimliği Yöneticisi veya Geliştiricisi: OAuth2 izin verme işlemlerini doğrudan tamamlayamazsınız. a365 setup all ögesini çalıştırın; kurulum özeti, Genel Yönetici için bir sonraki adımları ve izinleri tamamlamaya yönelik doğrudan bir bağlantı veya onay URL'sini içeren bilgileri yazdırır. Bu ayrıntıları Genel Yöneticinizle paylaşın.

Yapılandırma dosyaları eksik veya geçersiz

Belirti: Kurulum, "Yapılandırma bulunamadı" hatası veya doğrulama hataları nedeniyle başarısız oluyor.

Çözüm:

  1. a365.config.json dosyasının var olduğunu doğrulayın.
  2. Eksik veya geçersizse, el ile oluşturun ya da a365 setup all --agent-name <name> kullanın (yalnızca aracılar).
# Verify a365.config.json exists
Test-Path a365.config.json

Kurulum tamamlanıyor ancak kaynaklar oluşturulmuyor

Belirti: Kurulum komutu başarıyla tamamlandı, ancak Azure kaynakları mevcut değil.

Çözüm:

  1. Çalışma dizininizdeki a365.generated.config.json öğesini açarak oluşturulan kaynakları denetleyin.
  2. az resource list komutunu kullanarak Azure kaynaklarının var olduğunu doğrulayın.
  3. Kaynaklar eksikse kurulum çıktısındaki hataları denetleyin ve a365 setup all komutunu kullanarak kurulumu yeniden çalıştırın.
# Check created resources
Get-Content a365.generated.config.json | ConvertFrom-Json

# Verify Azure resources exist
az resource list --resource-group <your-resource-group> --output table

# If resources missing, check for errors in setup output and re-run
a365 setup all

Aracı taslağı Microsoft Entra'da kayıtlı değil

Belirti: Kurulum tamamlandı ancak Microsoft Entra Yönetim Merkezinde aracı şemasını bulamıyorsunuz.

Çözüm:

  1. Blueprint kimliğini a365.generated.config.json öğesinden alın.

    Get-Content a365.generated.config.json | ConvertFrom-Json | Select-Object agentBlueprintId

  2. Microsoft Entra yönetim merkezinde arama yapın:

    1. Şuraya git: Microsoft Entra yönetim merkezi.
    2. Uygulama kayıtları>Tüm uygulamalar yolunu izleyin.
    3. agentBlueprintId'inizi arayın.

  3. Bulunamazsa a365 setup all komutunu kullanarak kurulumu yeniden çalıştırın.

    a365 setup all

API izinleri verilmedi

Belirti: Kurulum tamamlandı, ancak Microsoft Entra'da izinler "Verilmedi" olarak görünüyor.

Çözüm:

  1. Microsoft Entra yönetim merkezini açın.

  2. Aracınız için şablon uygulaması kaydınızı bulun.

  3. API izinleri'ne gidin.

  4. Yönetici onayı ver:

    1. [Kiracınız] için yönetici onayı verin'i seçin.
    2. Eylemi onaylayın.

  5. Tüm izinlerin yanında yeşil onay işaretleri olduğunu kontrol edin.

Yönetilen kimlik etkinleştirilmedi

Belirti: Web Uygulaması mevcut, ancak yönetilen kimlik etkinleştirilmemiş.

Çözüm:

  1. az webapp identity show komutunu kullanarak yönetilen kimlik durumunu denetleyin.
  2. Etkinleştirilmemişse az webapp identity assign komutunu kullanarak el ile etkinleştirin.
  3. az webapp identity show komutunu kullanarak etkinleştirildiğini doğrulayın.
# Check managed identity status
az webapp identity show --name <your-web-app> --resource-group <your-resource-group>

# If not enabled, enable it manually
az webapp identity assign --name <your-web-app> --resource-group <your-resource-group>

# Verify it's enabled
az webapp identity show --name <your-web-app> --resource-group <your-resource-group>

Kurulum çok uzun sürüyor veya yanıt vermeyi durduruyor

Belirti: Kurulum komutu, tamamlanmadan 10 dakikadan fazla bir süre boyunca çalışıyor.

Çözüm:

  1. Genel yönetici olarak oturum açmışsanız, bir tarayıcı penceresinin yönetici onayı bekleyip beklemediğini kontrol edin. Kurulumun engellemesini kaldırmak için onay akışını tamamlayın.

  2. Kurulum gerçekten yanıt vermeyi durdurursa, iptal edin (Ctrl+C) ve nelerin oluşturulduğunu kontrol edin.

    # Check generated config
Get-Content a365.generated.config.json | ConvertFrom-Json

# Check Azure resources
az resource list --resource-group <your-resource-group>

  3. Temizle ve tekrar deneyin.

    a365 cleanup
a365 setup all

Yapılandırma gerektirmeyen bir aracıyı temizleme

Belirti: Bir aracıya a365 setup all --agent-name <name> ile sağladınız ve şimdi onu kaldırmak istiyorsunuz ama bir a365.config.json dosyanız yok.

Çözüm: Yapılandırma dosyası olmadan aracı kaldırmak için a365 cleanup --agent-name kullanın. CLI, önyükleme kurulumu sırasında yazılan ve genel olarak oluşturulan yapılandırma dosyasından kaynak kimliklerini okur.

a365 cleanup --agent-name <your-agent-name>

İpucu

Komut, kimlik doğrulama aşamasında takılırsa otomatik olarak cihaz kod akışına geçer. Giriş işlemini tamamlamak için terminalde görüntülenen talimatları izleyin.

Genel oluşturulan yapılandırmaya artık sahip değilseniz (örneğin, CLI'yı yeniden yükledikten sonra), manuel olarak oluşturulmuş bir minimal a365.config.json ile a365 cleanup kullanın veya kaynakları doğrudan Azure portal ve Microsoft Entra yönetim merkezi aracılığıyla kaldırın.

Teams'de ilk ileti gönderilemiyor

Belirti: Bir aracı örneğinin hazırlanması sonrasında, bu örnek aracı yöneticisine hoş geldin mesajı olarak bir mesaj gönderemiyor.

Çözüm: Yeni bir sohbet nesnesi oluşturmak için [Chat.Create][perm-chatcreate] izni gereklidir. Halihazırda bir bire bir sohbet varsa bu işlem mevcut sohbeti geri gönderir ve yeni bir sohbet oluşturmaz.

  • Uygulamak için taslağınızın devralınabilir izinleriniChat.Create kapsamını içerecek şekilde yapılandırın.
  • Bir aracı örneği hazır hale getirildiğinde gönderilecek bir Teams sohbet mesajı yapılandırın.
  • Şemadan yeni bir aracı örneği oluşturun ve ilk çalıştırma iletisini test edin.
  • Last updated on