Aracılığıyla paylaş

Araç ekleme ve yönetme

Önemli

Microsoft Agent 365'e erken erişim elde etmek için Frontier önizleme programının bir parçası olmanız gerekir. Frontier sizi Doğrudan Microsoft'un en son yapay zeka yenilikleri ile bağlar. Sınır önizlemeleri, müşteri sözleşmelerinizin mevcut önizleme koşullarına tabidir. Bu özellikler hala geliştirme aşamasında olduğundan, bunların kullanılabilirliği ve özellikleri zaman içinde değişebilir.

Araç modülü, geliştiricilerin Model Bağlam Protokolü (MCP) sunucularını bulmasını, yapılandırmasını ve yapay zeka aracısı iş akışlarıyla tümleştirmesini sağlar. MCP sunucuları, yapay zeka aracılarının çağırabileceği araçlar olarak dış özellikleri kullanıma sunar. Kullanılabilir araç sunucularına genel bakış için bkz . Aracı 365 araç sunucuları.

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

Genel bakış

Agent 365 Tooling tümleştirmesi dört adımlı bir iş akışını izler:

  1. MCP sunucularını yapılandırma - MCP sunucularını bulmak ve eklemek için Agent 365 CLI kullanma
  2. Bildirim oluşturma - CLI sunucu yapılandırmalarıyla oluşturur ToolingManifest.json
  3. Kodla tümleştirme - Bildirim yükleme ve düzenleyicinizle araçları kaydetme
  4. Araçları çağırma - Aracı, işlemleri gerçekleştirmek için yürütme sırasında araçları çağırır

Önkoşullar

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

  • Aracı 365 CLI yüklü ve yapılandırılmış
  • .NET 8.0 SDK veya üzeri - İndirme
  • Microsoft 365 kiracınızdaki Genel Yönetici ayrıcalıkları

Aracı kimliği kurulumu

Aracı kimlik doğrulaması kullanıyorsanız, MCP sunucularını yapılandırmadan önce aracı kimliğinizi oluşturmak için aracı kayıt işlemini tamamlayın. Bu, aracınızın KIMLIĞINI doğrulamasını ve MCP araçlarına erişmesini sağlayan aracılı uygulama kimliğini ve aracı kullanıcısını oluşturur.

Hizmet sorumlusunu ayarlama

Kiracınızda Aracı 365 Araçları için Hizmet Sorumlusu oluşturmak için bu ONE-TIME kurulum betiğini çalıştırın.

Önemli

Bu, Kiracı başına Genel Yönetici ayrıcalıkları gerektiren tek SEFERLIK bir işlemdir.

  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. Komt verilirse kullanıcı bilgilerinizle oturum açın.

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

DHCP sunucusunu yapılandırma

Aracınızın MCP sunucularını bulmak, eklemek ve yönetmek için Agent 365 CLI'yi kullanın. Kullanılabilir MCP sunucularının ve bunların özelliklerinin tam listesi için bkz . MCP sunucu kataloğu.

Kullanılabilir sunucuları bulma

Yapılandırılabilir tüm MCP sunucularını listeleyin:

a365 develop list-available

MCP sunucuları ekleme

Aracı yapılandırmanıza bir veya daha fazla MCP sunucusu ekleyin:

a365 develop add-mcp-servers mcp_MailTools

Yapılandırılmış sunucuları listeleme

Şu anda yapılandırılmış MCP sunucularını görüntüleme:

a365 develop list-configured

MCP sunucularını kaldırma

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

a365 develop remove-mcp-servers mcp_MailTools

Tam CLI başvurusu için bkz . a365 develop komutu.

Araç bildirimini anlama

çalıştırdığınızda a365 develop add-mcp-servers, CLI tüm MCP sunucuları için yapılandırma içeren bir ToolingManifest.json dosya oluşturur. Aracı çalışma zamanı, hangi sunucuların kullanılabilir olduğunu ve bunlarla nasıl kimlik doğrulaması yapılacağını anlamak için bu bildirimi kullanır.

Bildirim 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 girdisi aşağıdakini içerir:

Parametreler Açıklamalar
mcpServerName Varlığın görünen adı.
mcpServerUniqueName MCP sunucu örneğinin benzersiz tanımlayıcısı
kapsam MCP sunucusunun özelliklerine erişmek için gereken OAuth kapsamı (Örneğin: McpServers.Mail.All posta işlemleri için). Bu değer, komutu çalıştırdığınızda MCP sunucu kataloğundan add-mcp-servers alınır.
seyirci Hedef API kaynağını tanımlayan Microsoft Entra Id URI'si. Bu değer MCP sunucu kataloğundan da alınır.

Not

scope Ve audience değerleri, mcp sunucusu eklediğinizde Aracı 365 CLI tarafından otomatik olarak doldurulur. Bu değerler MCP sunucu kataloğundan gelir ve her MCP sunucusuna erişmek için gereken izinleri tanımlar.

Araçları aracınızla tümleştirme

Araç bildirimini oluşturdıktan sonra, yapılandırılmış MCP sunucularını aracı kodunuzla tümleştirin. Bu bölüm isteğe bağlı inceleme adımını ve gerekli tümleştirme adımlarını kapsar.

Liste aracı sunucuları (İsteğe bağlı)

Bahşiş

Bu adım isteğe bağlıdır. Araç bildirimindeki kullanılabilir araç sunucularını düzenleyicinize eklemeden önce incelemek için araç sunucusu yapılandırma hizmetini kullanın.

Aracınızın araç bildiriminden hangi araç sunucularını kullanabileceğini bulmak için araç sunucusu yapılandırma hizmetini kullanın. Bu yöntem şunları yapmanızı sağlar:

  • Tüm yapılandırılmış MCP sunucularını ToolingManifest.json
  • Sunucu meta verilerini ve özelliklerini alma
  • Kayıt öncesinde sunucu kullanılabilirliğini doğrulama

Araç sunucularını listeleme yöntemi, temel araç paketlerinde kullanılabilir:

# 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 Description Beklenen değer Gerekli/isteğe bağlı
agentic_app_id str Aracı uygulama örneğinin benzersiz tanımlayıcısı Geçerli aracı uygulama kimliği dizesi Zorunlu
auth_token str MCP sunucu ağ geçidiyle kimlik doğrulaması için taşıyıcı belirteci Geçerli OAuth taşıyıcı belirteci Zorunlu

Paket: microsoft-agents-a365-tooling

Düzenleyicinize araçları kaydetme

Tüm MCP sunucularını düzenleme çerçevenize kaydetmek için çerçeveye özgü uzantı yöntemini kullanın:

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

Bu yöntemler:

  • Yapılandırılmış MCP sunucularından tüm araçları düzenleyicinize kaydetme
  • Kimlik doğrulama ve bağlantı ayrıntılarını otomatik olarak ayarlama
  • Aracınızın çağırması için araçları hemen kullanılabilir hale getirme

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

Agent 365 Tooling modülü, farklı düzenleme çerçeveleri için ayrılmış uzantı paketleri sağlar:

  • microsoft-agents-a365-tooling: Çekirdek araç işlevselliği
  • microsoft-agents-a365-tooling-extensions-agentframework: Agent Framework tümleştirmesi
  • microsoft-agents-a365-tooling-extensions-azureaifoundry: Azure AI Foundry tümleştirmesi
  • microsoft-agents-a365-tooling-extensions-openai: OpenAI tümleştirmesi
  • microsoft-agents-a365-tooling-extensions-semantickernel: AnlamSal Çekirdek tümleştirmesi

Not

Kimlik doğrulaması, çalıştırdığınızda a365 develop add-mcp-serversAracı 365 CLI tarafından otomatik olarak yapılandırılır. OAuth kapsamları ve hedef kitle değerleri MCP sunucu kataloğundan alınır ve içinde ToolingManifest.jsonbulunur. Uzantı yöntemleri kimlik doğrulamasını ayarlamak için bu değerleri otomatik olarak kullanır; el ile yapılandırma gerekmez.

Ayrıntılı uygulama örnekleri için bkz . Aracı 365 Örnekleri.

Uygulama örneği

Aşağıdaki örneklerde, Aracı 365 Araçları'nı farklı düzenleme çerçeveleriyle tümleştirme gösterilmektedir.

OpenAI ile Python

Bu örnekte, PYTHON uygulamasında MCP araçlarını OpenAI ile tümleştirme gösterilmektedir.

İçeri aktarma deyimi ekleme.

Araç modülüne ve OpenAI uzantılarına erişmek için gerekli içeri aktarmaları ekleyin:

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

2. Araç hizmetlerini başlatma

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. OPENAI aracısıyla MCP araçlarını kaydetme

add_tool_servers_to_agent Yapılandırılmış tüm MCP araçlarını OpenAI aracınıza kaydetmek için yöntemini kullanın. Bu yöntem hem aracılı hem de eflatun olmayan kimlik doğrulama senaryolarını işler:

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}")

Yöntem parametreleri

Aşağıdaki tabloda, dikkate alınması gereken parametreler açıklanmaktadır.

Parametreler Açıklamalar
agent Araçları kaydetmek için OpenAI aracı örneği.
agentic_app_id Aracı için benzersiz tanımlayıcı (aracı uygulama kimliği).
auth Kullanıcının yetkilendirme bağlamı.
context Geçerli konuşma, Aracılar SDK'sından bağlamı çevirir. Güvenli araç kaydı için kullanıcı kimliği, konuşma meta verileri ve kimlik doğrulama bağlamı sağlar.
auth_token (İsteğe bağlı) Eflatun olmayan kimlik doğrulama senaryoları için taşıyıcı belirteci.

4. Başlatma sırasında arama

Aracıyı çalıştırmadan önce başlatma sırası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:

  • ToolingManifest.json tüm MCP sunucularını yükler
  • Araçlarını OpenAI aracısına kaydeder
  • Bildirim yapılandırmasına göre kimlik doğrulamasını ayarlar
  • Aracınızın çağırabilecekleri araçları kullanıma hazır hale getirir

Tam çalışma örnekleri için bkz . Aracı 365 Örnekleri deposu.

Test etme ve izleme

Aracınızı test etme

MCP araçlarını aracınızla tümleştirdikten sonra, doğru çalıştıklarından ve farklı senaryoları işlediklerinden emin olmak için araç çağrılarını test edin. Ortamınızı ayarlamak için test kılavuzunu izleyin, ardından MCP araçlarınızın beklendiği gibi çalıştığını doğrulamak için öncelikle Test aracı çağrıları bölümüne odaklanın.

Gözlemlenebilirlik ekleme

Aracınızın MCP aracı çağrılarını izlemek ve izlemek için aracınıza gözlemlenebilirlik ekleyin, performansı izlemek, sorunları ayıklamak ve araç kullanım desenlerini anlamak için gözlemlenebilirlik özellikleri ekleyin. İzleme ve izleme uygulama hakkında daha fazla bilgi edinin

  • Last updated on