Sdílet prostřednictvím

Přidání a správa nástrojů

Důležité

Abyste získali přednostní přístup k Microsoft Agentu 365, musíte být součástí programu Frontier Preview. Hranice vás spojuje přímo s nejnovějšími inovacemi umělé inteligence Microsoftu. Verze Preview hranice podléhají stávajícím podmínkám verze Preview vašich smluv se zákazníkem. Vzhledem k tomu, že tyto funkce jsou stále ve vývoji, jejich dostupnost a možnosti se můžou v průběhu času měnit.

Modul Nástrojů umožňuje vývojářům zjišťovat, konfigurovat a integrovat servery MCP (Model Context Protocol) do pracovních postupů agenta AI. Servery MCP zpřístupňují externí funkce jako nástroje, které můžou vyvolat agenti AI. Přehled dostupných serverů nástrojů najdete v tématu Servery nástrojů agenta 365.

Demonstruje tok požadavku a odpovědi.

Přehled

Integrace nástrojů agenta 365 se řídí čtyřstupňovým pracovním postupem:

  1. Konfigurace serverů MCP – Zjišťování a přidání serverů MCP pomocí rozhraní příkazového řádku agenta 365
  2. Generování manifestu – rozhraní příkazového řádku se vytvoří ToolingManifest.json s konfiguracemi serveru
  3. Integrace do kódu – Načtení manifestu a registrace nástrojů v orchestrátoru
  4. Vyvolání nástrojů – Agent volá nástroje během provádění operací

Předpoklady

Před konfigurací serverů MCP se ujistěte, že máte:

Nastavení identity agenta

Pokud používáte ověřování agentů, před konfigurací serverů MCP dokončete proces registrace agenta a vytvořte identitu agenta. Tím se vytvoří ID aplikace agenta a uživatel agenta, který umožňuje vašemu agentu ověřovat a přistupovat k nástrojům MCP.

Nastavení instančního objektu

Spuštěním tohoto jednorázového instalačního skriptu vytvořte instanční objekt pro nástroje agenta 365 ve vašem tenantovi.

Důležité

Jedná se o jednorázovou operaci na tenanta, která vyžaduje oprávnění globálního správce.

  1. Stažení skriptu New-Agent365ToolsServicePrincipalProdPublic.ps1

  2. Otevřete PowerShell jako správce a přejděte do adresáře skriptu.

  3. Spusťte skript:

    .\New-Agent365ToolsServicePrincipalProdPublic.ps1

  4. Pokud se zobrazí výzva, přihlaste se pomocí svých přihlašovacích údajů pro .

Po dokončení je váš tenant připravený na vývoj agenta a konfiguraci serveru MCP.

Konfigurace serveru DHCP

Pomocí rozhraní příkazového řádku agenta 365 můžete zjistit, přidat a spravovat servery MCP pro vašeho agenta. Úplný seznam dostupných serverů MCP a jejich možností najdete v katalogu serverů MCP.

Zjišťování dostupných serverů

Zobrazte seznam všech serverů MCP, které je možné konfigurovat:

a365 develop list-available

Přidání serverů MCP

Přidejte jeden nebo více serverů MCP do konfigurace agenta:

a365 develop add-mcp-servers mcp_MailTools

Seznam nakonfigurovaných serverů

Zobrazení aktuálně nakonfigurovaných serverů MCP:

a365 develop list-configured

Odebrání serverů MCP

Odeberte server MCP z konfigurace:

a365 develop remove-mcp-servers mcp_MailTools

Kompletní referenční informace k rozhraní příkazového řádku najdete v příkazu a365 develop.

Vysvětlení manifestu nástrojů

Při spuštění a365 develop add-mcp-serversrozhraní příkazového řádku vygeneruje ToolingManifest.json soubor obsahující konfiguraci pro všechny servery MCP. Modul runtime agenta používá tento manifest k pochopení, které servery jsou k dispozici a jak se s nimi ověřují.

Struktura manifestu

Příklad: ToolingManifest.json

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

Parametry manifestu

Každá položka serveru MCP obsahuje:

Parametry Popisy
mcpServerName Zobrazovaný název materiálu.
mcpServerUniqueName Jedinečný identifikátor instance serveru MCP
rozsah Obor OAuth vyžadovaný pro přístup k možnostem serveru MCP (například pro McpServers.Mail.All poštovní operace). Tato hodnota se načte z katalogu serverů MCP při spuštění add-mcp-servers příkazu.
obecenstvo Identifikátor URI ID Microsoft Entra, který identifikuje cílový prostředek rozhraní API. Tato hodnota se také načte z katalogu serverů MCP.

Poznámka:

Hodnoty scope a audience hodnoty se automaticky vyplní rozhraním příkazového řádku agenta 365, když přidáte server MCP. Tyto hodnoty pocházejí z katalogu serverů MCP a definují oprávnění potřebná pro přístup k jednotlivým serverům MCP.

Integrace nástrojů do agenta

Po vygenerování manifestu nástrojů integrujte nakonfigurované servery MCP do kódu agenta. Tato část popisuje volitelný krok kontroly a požadované kroky integrace.

Seznam serverů nástrojů (volitelné)

Zpropitné

Tento krok je nepovinný. Před přidáním do orchestrátoru pomocí konfigurační služby serveru nástrojů zkontrolujte dostupné servery nástrojů z manifestu nástrojů.

Pomocí konfigurační služby serveru nástrojů zjistěte, které servery nástrojů jsou k dispozici vašemu agentu z manifestu nástrojů. Tato metoda umožňuje:

  • Dotazování na všechny nakonfigurované servery MCP z webu ToolingManifest.json
  • Načtení metadat a možností serveru
  • Ověření dostupnosti serveru před registrací

Metoda výpisu serverů nástrojů je k dispozici v základních balíčcích nástrojů:

# 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)

**Parametry:

Parametr Typ Popis Očekávaná hodnota Povinné/volitelné
agentic_app_id str Jedinečný identifikátor instance aplikace agenta Platný řetězec ID aplikace agenta Požadováno
auth_token str Nosný token pro ověřování pomocí brány serveru MCP Platný nosný token OAuth Požadováno

Balíček: microsoft-agents-a365-tooling

Registrace nástrojů v orchestrátoru

Metodu rozšíření specifickou pro architekturu použijte k registraci všech serverů MCP v rámci vaší architektury orchestrace:

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

Tyto metody:

  • Registrace všech nástrojů z nakonfigurovaných serverů MCP v orchestrátoru
  • Automatické nastavení podrobností o ověřování a připojení
  • Okamžité zpřístupnění nástrojů pro vyvolání agenta

Volba rozšíření orchestrátoru

Modul nástrojů Agent 365 poskytuje vyhrazené balíčky rozšíření pro různé architektury orchestrace:

  • microsoft-agents-a365-tooling: Základní funkce nástrojů
  • microsoft-agents-a365-tooling-extensions-agentframework: Integrace rozhraní Agent Framework
  • microsoft-agents-a365-tooling-extensions-azureaifoundry: Integrace Azure AI Foundry
  • microsoft-agents-a365-tooling-extensions-openai: Integrace OpenAI
  • microsoft-agents-a365-tooling-extensions-semantickernel: Integrace semantického jádra

Poznámka:

Při spuštění a365 develop add-mcp-serversse ověřování automaticky konfiguruje pomocí rozhraní příkazového řádku agenta 365 . Obory OAuth a hodnoty cílové skupiny se načítají z katalogu serverů MCP a jsou zahrnuty v souboru ToolingManifest.json. Metody rozšíření tyto hodnoty automaticky používají k nastavení ověřování – nevyžaduje se žádná ruční konfigurace.

Podrobné příklady implementace najdete v ukázkách agenta 365.

Příklad implementace

Následující příklady ukazují, jak integrovat nástroje Agent 365 s různými architekturami orchestrace.

Python s OpenAI

Tento příklad ukazuje, jak integrovat nástroje MCP s OpenAI v aplikaci v Pythonu.

Přidejte prohlášení o importu.

Přidejte požadované importy pro přístup k modulu Nástrojů a rozšíření OpenAI:

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

2. Inicializace služeb nástrojů

Vytvořte instance služeb konfigurace a registrace nástrojů:

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

3. Registrace nástrojů MCP v agentovi OpenAI

add_tool_servers_to_agent Pomocí této metody zaregistrujte všechny nakonfigurované nástroje MCP u agenta OpenAI. Tato metoda zpracovává scénáře agentického i neagentického ověřování:

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

Parametry metody

Následující tabulka popisuje parametry.

Parametry Popisy
agent Instance agenta OpenAI pro registraci nástrojů.
agentic_app_id Jedinečný identifikátor agenta (ID aplikace agenta).
auth Kontext autorizace pro uživatele.
context Aktuální konverzace otočí kontext ze sady Sdk agentů. Poskytuje identitu uživatele, metadata konverzací a kontext ověřování pro zabezpečenou registraci nástrojů.
auth_token (Volitelné) Nosný token pro scénáře neagentického ověřování.

4. Volání během inicializace

Před spuštěním agenta se ujistěte, že během inicializace voláte metodu nastavení:

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

Metoda add_tool_servers_to_agent automaticky:

  • Načte všechny servery MCP z ToolingManifest.json
  • Zaregistruje své nástroje v agentovi OpenAI.
  • Nastaví ověřování na základě konfigurace manifestu.
  • Zpřístupňuje nástroje pro vyvolání agenta.

Kompletní pracovní příklady najdete v úložišti Ukázek agenta 365.

Testování a monitorování

Otestujte svého agenta

Po integraci nástrojů MCP do agenta otestujte vyvolání nástroje, abyste měli jistotu, že fungují správně a zpracovávají různé scénáře. Podle průvodce testováním nastavte prostředí a pak se zaměřte především na část Vyvolání testovacích nástrojů a ověřte, že vaše nástroje MCP fungují podle očekávání.

Přidání pozorovatelnosti

Přidáním pozorovatelnosti do agenta můžete monitorovat a sledovat vyvolání nástrojů MCP vašeho agenta, přidávat možnosti pozorovatelnosti ke sledování výkonu, ladění problémů a pochopení vzorů využití nástrojů. Další informace o implementaci trasování a monitorování

  • Last updated on