Araçları ekleyin ve yönetin

Tooling modülü, geliştiricilerin Model Bağlam Protokolü (MCP) sunucularını keşfetmelerine, yapılandırmalarına ve bunları AI destekli aracı iş akışlarına entegre etmelerine yardımcı olur. MCP sunucuları, AI destekli aracıların çağrılabileceği araçlar olarak dış yetenekleri ortaya çıkarır. Mevcut tooling sunucularının genel bir görünümü için Agent 365 tooling sunucularına başvurabilirsiniz.

İstek ve yanıt akışını gösterir

Genel bakış

Agent 365 Tooling entegrasyonu aşağıdaki iş akışını izler:

  1. MCP sunucularını yapılandırın - Agent 365 CLI'yi kullanarak MCP sunucularını keşfedin ve ekleyin
  2. Manifest dosyasını oluşturun: - CLI, sunucu yapılandırmalarını içeren ToolingManifest.json manifest dosyasını proje klasörünüzde oluşturur.
  3. Blueprint'e izinleri uygulayın - Bir Global Administrator, ilk kurulumda a365 setup all veya blueprint zaten mevcutsa a365 setup permissions mcp komutunu çalıştırarak aracı blueprint'ine OAuth2 izinlerini tanımlar. Her durumda, komut ToolingManifest.json okur ve yönetici onayı gerektirir. Bu adım, sunucuları manifest'e eklemekten her zaman bağımsızdır.
  4. Koda entegre edin - Manifesti yükleyin ve araçları orkestratörünüzde kaydedin.
  5. Araçları çağır - Aracı yürütme sırasında işlemleri gerçekleştirmek için araçları çağırır.

Ön koşullar

MCP sunucularını yapılandırmadan önce şunlara sahip olduğunuzdan emin olun:

  • Agent 365 CLI kurulu ve yapılandırılmış olmalı
  • .NET 8.0 SDK veya daha yeni - İndir
  • Microsoft 365 kiracınızda Küresel Yönetici ayrıcalıkları

Aracı kimliği kurulumu

Eğer aracı tabanlı kimlik doğrulama kullanıyorsanız, MCP sunucularını yapılandırmadan önce aracı kimliğinizi oluşturmak için aracı kayıt sürecini tamamlamalısınız. Bu süreç, aracınızın kimlik doğrulaması yapmasını ve MCP araçlarına erişmesini sağlayan Entra aracı ID'si ve aracı kullanıcısını oluşturur.

OBO kimlik doğrulama kurulumu

Eğer aracısal kimlik doğrulaması yerine On-Behalf-Of (OBO) kimlik doğrulamasını kullanırsanız, aracınız bir aracı kullanıcı kimliği olmadan delege edilmiş kullanıcı izinleriyle MCP araçlarına erişebilir. OBO akışında, aracı kullanıcı adına işlemler yapmak üzere kullanıcının delege edilmiş belirtecini takas eder.

OBO akışının nasıl çalıştığı hakkında daha fazla bilgi için Kimlik doğrulama akışları bölümüne bakınız. Tam bir uygulama örneği için, OBO yetkilendirme örneğini Microsoft 365 Aracıları SDK'sı'nda inceleyiniz.

Hizmet sorumlusunu ayarlama

Kiracınızda Agent 365 Tools için hizmet yetkilisini oluşturmak üzere bu tek seferlik kurulum betiğini çalıştırın.

Önemli

Bu tek seferlik işlem, kiracı başına Genel Yönetici yetkileri gereklidir.

  1. New-Agent365ToolsServicePrincipalProdPublic.ps1 betiğini indirin.

  2. PowerShell'i yönetici olarak açın ve betik dizinine gidin.

  3. Betiği çalıştırın.

    .\New-Agent365ToolsServicePrincipalProdPublic.ps1

  4. İstendiğinde Azure kimlik bilgilerinizi kullanarak oturum açın.

Tamamlandıktan sonra, kiracınız aracı geliştirme ve MCP sunucu yapılandırmasına hazırdır.

MCP Sunucularını Yapılandırma

Agent 365 CLI'yi kullanarak aracınız için MCP sunucularını keşfedin, ekleyin ve yönetin. Mevcut MCP sunucularının ve yeteneklerinin tam listesi için MCP Sunucu Kataloğu'nu inceleyiniz.

Mevcut Sunucuların Keşfi

Yapılandırabileceğiniz tüm MCP sunucularını listeleyin:

a365 develop list-available

MCP sunucuları ekleyin

Aracınızın yapılandırmasına bir veya daha fazla MCP sunucusu ekleyin:

a365 develop add-mcp-servers mcp_MailTools

Önemli

Bu komut yalnızca proje klasörünüzdeki ToolingManifest.json'i günceller — blueprint'e herhangi bir izin vermez. İzinlerin nasıl uygulandığı, kurulum sürecinin hangi aşamasında olduğunuza bağlıdır:

  • İlk kurulumdan önce: Önce a365 develop add-mcp-servers komutunu çalıştırın, ardından a365 setup all ile devam edin. setup all komutu, blueprint oluşturma işleminin bir parçası olarak MCP izinleri adımını içerir.
  • Plan zaten varken: Küresel Yönetici a365 setup permissions mcp'ü ayrı olarak çalıştırmalıdır. Yöneticinin a365.config.json'i, güncellenmiş ToolingManifest.json dosyasını içeren proje klasörüne işaret eden bir deploymentProjectPath'ye sahip olmalıdır. Bu adım tamamlanana kadar, yeni MCP sunucu izinleri blueprint'te görünmez.

Yapılandırılmış sunucuları listele

Mevcut yapılandırılmış MCP sunucularını görüntüleyin:

a365 develop list-configured

MCP sunucularını kaldır

Yapılandırmanızdan bir MCP sunucusunu kaldırın:

a365 develop remove-mcp-servers mcp_MailTools

Tam CLI referansı için bkz. a365 develop command.

Test için mock tooling sunucusu kullanın

Geliştirme ve test için, gerçek MCP sunucularına bağlanmak yerine Agent 365 CLI mock tooling sunucusunu kullanın. Mock tooling sunucusu, MCP sunucu etkileşimlerini simüle eder; bu sayede aracınızı kimlik doğrulama gibi harici bağımlılıklar olmadan yerel olarak test edebilirsiniz.

Mock sunucu, yerel geliştirme ve test için aşağıdaki avantajları sunar:

  • Çevrimdışı geliştirme: Aracınızı internet bağlantısı veya harici bağımlılıklar olmadan test edin.
  • Tutarlı testler: Uç durumları test ederken öngörülebilir yanıtlar alın.
  • Hata ayıklama: Tüm istek ve yanıtları gerçek zamanlı görüntüleyin
  • Hızlı yineleme: Harici API çağrılarını beklemenize veya karmaşık test ortamları oluşturmanıza gerek yok.

Mock tooling sunucusunu başlatmak için a365 develop start-mock-tooling-server komutunu kullanın.

Mock tooling sunucusunu kurmayı ve yapılandırmayı öğrenin.

Not

Manifest dosyalarını yapılandırmak ve araçları aracınıza entegre etmek için aşağıdaki bölümler, ister mock tooling sunucusunu ister gerçek MCP sunucularını kullansanız, aynı şekilde çalışır. MCP_PLATFORM_ENDPOINT ortam değişkeninizi mock sunucuya (örneğin: http://localhost:5309) yönlendirecek şekilde ayarlayın, üretim uç noktası yerine.

Araç manifestini anlamak

a365 develop add-mcp-servers komutunu çalıştırdığınızda, CLI tüm MCP sunucularının yapılandırma bilgilerini içeren bir ToolingManifest.json dosyasını oluşturur. Aracı çalışma zamanı, hangi sunucuların mevcut olduğunu ve onlarla nasıl kimlik doğrulamanın gerçekleştirileceğini anlamak için bu manifestoyu kullanır.

Manifest yapısı

Örnek ToolingManifest.json:

{
  "mcpServers": [
    {
      "mcpServerName": "mcp_MailTools",
      "mcpServerUniqueName": "mcp_MailTools",
      "scope": "McpServers.Mail.All",
      "audience": "api://05879165-0320-489e-b644-f72b33f3edf0"
    }
  ]
}

Bildirim parametreleri

Her MCP sunucu kaydı aşağıdaki öğeleri içerir:

Parametre Açıklama
mcpServerName MCP sunucusunun görünen adı.
mcpServerUniqueName MCP sunucu örneğinin benzersiz tanımlayıcısı.
scope MCP sunucusunun yeteneklerine erişmek için gerekli OAuth kapsamı (örneğin: McpServers.Mail.All posta işlemleri için). add-mcp-servers komutu bu değeri MCP sunucu kataloğundan alır.
audience Hedef API kaynağını tanımlayan Microsoft Entra ID URI'si. add-mcp-servers komutu bu değeri MCP sunucu kataloğundan alır.

Not

Agent 365 CLI, bir MCP sunucusu eklediğinizde scope ve audience değerlerini otomatik olarak doldurur. Bu değerler MCP sunucu kataloğundan gelir ve her MCP sunucusuna erişim için gerekli izinleri tanımlar.

Araçları aracınıza entegre edin

Araç manifestosu oluşturulduktan sonra, yapılandırılmış MCP sunucularını aracı kodunuza entegre edin. Bu bölüm, isteğe bağlı inceleme adımını ve gerekli entegrasyon adımlarını kapsamaktadır.

List araç sunucuları (isteğe bağlı)

İpucu

Bu adım isteğe bağlıdır. Araç sunucusu yapılandırma hizmetini kullanarak, araç manifestosundan mevcut araç sunucularını inceleyip bunları orkestratörünüze eklemeden önce gözden geçirin.

Araç sunucusu yapılandırma hizmetini kullanarak aracı manifestosundan aracınızın hangi araç sunucularının mevcut olduğunu keşfedin. Bu yöntemle şunları gerçekleştirebilirsiniz:

  • ToolingManifest.json dosyasındaki tüm yapılandırılmış MCP sunucularını sorgulayın.
  • Sunucu meta verilerini ve yeteneklerini alın.
  • Kayıttan önce sunucu kullanılabilirliğini doğrulayın.

Araç sunucularını listeleme yöntemi temel araç paketlerinde yer almaktadır:

# Use McpToolServerConfigurationService.list_tool_servers
from microsoft.agents.a365.tooling import McpToolServerConfigurationService

config_service = McpToolServerConfigurationService()
tool_servers = await config_service.list_tool_servers(agentic_app_id, auth_token)

Parametreler:

Parametre Tür Açıklama Beklenen Değer Gerekli/İsteğe bağlı
agentic_app_id str Aracı uygulama örneğinin benzersiz tanımlayıcısı Geçerli aracı uygulama kimlik dizesi Zorunlu
auth_token str MCP sunucu geçidi üzerinden kimlik doğrulama için taşıyıcı belirteç Geçerli OAuth taşıyıcı belirteç Zorunlu

Paket: microsoft_agents_a365.tooling

Araçları orkestratöre kaydedin

Tüm MCP sunucularını orkestrasyon çerçevenizle kaydetmek için framework'e özel uzantı metodunu kullanın:

  • AddToolServersToAgentAsync (.NET)
  • add_tool_servers_to_agent (Python)
  • addToolServersToAgent (Node.js)

Bu yöntemler:

  • Yapılandırılmış MCP sunucularındaki tüm araçları orkestratörünüze kaydeder
  • Kimlik doğrulama ve bağlantı detaylarını otomatik olarak ayarlar
  • Araçları, aracınızın hemen çağırabileceği şekilde erişilebilir hale getirir

Düzenleyici uzantısını seçin

Agent 365 Tooling modülü, farklı orkestrasyon framework'leri için özel uzantı paketleri sağlar.

Not

a365 develop add-mcp-servers komutunu çalıştırdığınızda, CLI otomatik olarak OAuth kapsamlarını ve audience değerlerini MCP sunucu kataloğundan alır ve bunları ToolingManifest.json'ye yazar. Uzantı yöntemleri, kimlik doğrulamasını çalışma zamanında sağlamak için bu değerleri kullanır — aracı kodunuzda manuel yapılandırma gerekmez. Ancak, Genel Yönetici'nin bu izinleri, aracınızın üretimde kullanabilmesi için aracı blueprint'ine vermesi gerekmektedir: ilk kurulumda a365 setup all veya blueprint zaten mevcutsa a365 setup permissions mcp üzerinden.

Detaylı uygulama örnekleri için Agent 365 Örnekleri'ne bakınız.

Uygulama örnekleri

Aşağıdaki örnekler, Agent 365 Araçları'nın farklı orkestrasyon çerçeveleriyle nasıl entegre edileceğini göstermektedir.

OpenAI ile Python

Bu örnek, MCP araçlarının OpenAI ile bir Python uygulamasında nasıl entegre edileceğini gösterir.

1. İçe aktarma ifadeleri ekleyin

Tooling modülüne ve OpenAI uzantılarına erişmek için gerekli import ifadelerini ekleyin:

from microsoft.agents.a365.tooling import McpToolServerConfigurationService
from microsoft.agents.a365.tooling.extensions.openai import mcp_tool_registration_service

2. Araç servislerini başlatın

Yapılandırma ve araç kayıt hizmetlerinin örneklerini oluşturun:

# Create configuration service and tool service with dependency injection
self.config_service = McpToolServerConfigurationService()
self.tool_service = mcp_tool_registration_service.McpToolRegistrationService()

3. MCP araçlarını OpenAI aracıyı ile kaydedin

Tüm yapılandırılmış MCP araçlarını OpenAI aracınıza kaydetmek için bu add_tool_servers_to_agent yöntemini kullanın. Bu yöntem hem aracıik hem de aracıik olmayan kimlik doğrulama senaryolarını destekler:

async def setup_mcp_servers(self, auth: Authorization, context: TurnContext):
    """Set up MCP server connections"""
    try:
        use_agentic_auth = os.getenv("USE_AGENTIC_AUTH", "false").lower() == "true"
        if use_agentic_auth:
            self.agent = await self.tool_service.add_tool_servers_to_agent(
                agent=self.agent,
                agentic_app_id=agentic_app_id,
                auth=auth,
                context=context,
            )
        else:
            self.agent = await self.tool_service.add_tool_servers_to_agent(
                agent=self.agent,
                agentic_app_id=agentic_app_id,
                auth=auth,
                context=context,
                auth_token=self.auth_options.bearer_token,
            )

    except Exception as e:
        logger.error(f"Error setting up MCP servers: {e}")

Metot parametreleri

Aşağıdaki tabloda add_tool_servers_to_agent ile kullanılacak parametreler açıklanmaktadır.

Parametre Açıklama
agent Araçları kaydetmek için OpenAI aracı örneği.
agentic_app_id Aracının benzersiz tanımlayıcısı (aracı uygulama kimliği).
auth Kullanıcı için yetkilendirme bağlamı.
context Aracılar SDK'sından güncel konuşma turu bağlamı. Güvenli araç kaydı için kullanıcı kimliği, konuşma meta verileri ve kimlik doğrulama bağlamı sağlar.
auth_token (Opsiyonel) Aracısal olmayan kimlik doğrulama senaryoları için taşıyıcı belirteç.

4. Başlatma sırasında çağırın

Aracıyı çalıştırmadan önce, başlatma aşamasında kurulum yöntemini çağırdığınızdan emin olun:

# Setup MCP servers during initialization
await self.setup_mcp_servers(auth, context)

add_tool_servers_to_agent yöntemi otomatik olarak şunları gerçekleştirir:

  • ToolingManifest.json dosyasındaki tüm MCP sunucularını yükler.
  • Araçlarını OpenAI aracınına kaydeder.
  • Manifest yapılandırmasına göre kimlik doğrulamayı kurar.
  • Araçları, aracınızın çağırabilmesi için kullanılabilir hale getirir.

Tam çalışma örnekleri için Agent 365 Örnekleri deposunu inceleyin.

Agent 365 MCP sunucularına erişim için diğer yollar

Agent 365 SDK'nın yanı sıra, Agent 365 MCP sunucularına çeşitli geliştirme ortamları üzerinden de erişebilirsiniz:

  • Visual Studio Code - Özel geliştirme iş akışları için doğrudan MCP sunucularına bağlanın.
  • Microsoft Copilot Studio - MCP sunucularını az kodlu bir deneyimle konuşma akışlarına entegre edin.
  • Azure Yapay Zeka Atölyesi - Tam SDK desteği ve gelişmiş orkestrasyon yetenekleriyle MCP sunucularını kullanın.

Bu platformlar genelinde mevcut MCP sunucularının ve entegrasyon seçeneklerinin tam bir özeti için Agent 365 araç sunucuları genel görünümü sayfasına bakınız.

Kendi MCP sunucunuzu getirin (BYO)

Bring Your Own (BYO) MCP sunucusu özelliği, kendi harici MCP sunucularınızı Microsoft Agent 365'e kaydetmenize olanak tanır; böylece bu sunucular Microsoft 365 yönetim merkezi üzerinden merkezi olarak yönetilebilir, onaylanabilir ve izlenebilir. Bu sunucuları Agent 365 araç geçidi üzerinden yönlendirir; yöneticilere onay, erişim ve politikaların yönetimi üzerinde kontrol sağlarken, güvenlik ekiplerinin telemetri yoluyla kullanımı takip etmesine olanak tanır. Bir geliştirici olarak, MCP sunucunuzu Agent 365 CLI ile kaydedebilir, ardından yöneticinizin kaydı gözden geçirip onaylamasını ve izinleri vermesini bekleyebilirsiniz. Onaylanan sunucu, desteklenen istemci araçlarında kullanılabilir; sürekli izleme, tüm entegrasyonlarda uyumluluk ve izlenebilirlik sağlar.

Detaylı talimatlar için bkz. Kendi (BYO) MCP sunucunuzu getirme.

Aracınızı test etme

MCP araçlarını aracınıza entegre ettikten sonra, araç çağrılarını farklı senaryolarda doğru çalışıp çalışmadıklarını kontrol etmek için test edin. Ortamınızı kurmak için test rehberini takip edin. Ardından, MCP araçlarınızın beklendiği gibi çalıştığını doğrulamak için esas olarak Test araç çağrıları bölümüne odaklanın. Ayrıca, kimlik doğrulama işlemleriyle uğraşmadan MCP sunucu bağlantısını ve araç çağrılarını test etmek için mock tooling sunucusunu inceleyebilirsiniz.

Gözlemlenebilirlik sağlayın

Aracınızın MCP araç çağrılarını izleyip takip edebilmek için gözlemlenebilirlik ekleyin. Gözlemlenebilirlik özellikleri ekleyerek performansı izleyebilir, sorunları giderebilir ve araç kullanım desenlerini anlayabilirsiniz. Takip ve izlemenin nasıl uygulanacağı hakkında daha fazla bilgi edinin.

Sorun giderme

Bu bölüm, MCP sunucularını ve araçlarını yapılandırırken ve kullanırken karşılaşılan yaygın sorunları listeler.

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

MCP sunucu ve araçlar sorunları

Belirtiler:

  • Araç çağrısı hataları.
  • "MCP sunucusu bulunamadı" hataları.
  • Araç çağrısı sırasında izin reddi hataları.

Temel Neden:

  • MCP sunucusu yapılandırılmamış.
  • Eksik izinler.
  • Hizmet sorumlusu ayarlanmamış.
  • Mock ve prodüksiyon sunucuları arasında karışıklık.

Çözümler: Sorunu çözmek için aşağıdaki çözümleri deneyin.

  • MCP sunucularının yapılandırıldığını doğrulayın

    Yapılandırılmış sunucuları listeleyin ve eksik olanları ekleyin.

    # List configured servers
a365 develop list-configured

# If empty, add required servers (example: Mail MCP server)
a365 develop add-mcp-servers mcp_MailTools

  • Hizmet sorumlusunun mevcut olup olmadığını kontrol edin

    Araçlar için gerekli hizmet prensibinin oluşturulduğundan emin olun.

    # Run the one-time setup script
# https://github.com/microsoft/Agent365-devTools/blob/main/scripts/cli/Auth/New-Agent365ToolsServicePrincipalProdPublic.ps1

  • Erken geliştirme ve test için mock sunucular kullanın

    Aracınızın geri kalanını üretim araç bileşenleri olmadan test etmek istiyorsanız, erken yerel geliştirme ve test için mock tooling sunucusunu kullanın.

    # Start mock tooling server
a365 develop start-mock-tooling-server

# Update your .env
MCP_PLATFORM_ENDPOINT=http://localhost:5309

    Mock tooling sunucusu hakkında bilgi edinin.

  • Yönetim merkezindeki izinleri doğrulayın

    Aracınızın gerekli MCP izinlerine sahip olduğunu doğrulayın.

    • Azure portalında aracı blueprint API izinlerinizin tüm MCP sunucu izinlerini gösterdiğini doğrulayın.

    Doğrulama:

    # Test a tool call in Agents Playground
# Should execute without permission errors
  • Son güncelleştirme: