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

Modul Tooling pomáhá vývojářům objevovat, konfigurovat a integrovat servery Model Context Protocol (MCP) do pracovních postupů agentů AI. MCP servery zpřístupňují externí funkce jako nástroje, které mohou agenti AI použít. Pro přehled dostupných nástrojových serverů viz nástrojové servery Agent 365.

Demonstruje tok požadavků a odpovědí

Přehled

Integrace Agent 365 Tooling probíhá podle následujícího postupu:

  1. Konfigurace MCP serverů – Pomocí Agent 365 CLI vyhledejte a přidejte MCP servery
  2. Vygenerujte manifest – CLI vytvoří ToolingManifest.json ve vaší složce projektu s konfiguracemi serverů.
  3. Přidání oprávnění k podrobnému plánu – Globální správce uděluje OAuth2 oprávnění podrobného plánu agenta spuštěním a365 setup all (při prvním nastavení) nebo a365 setup permissions mcp (pokud podrobný plán již existuje). Bez ohledu na postup příkaz načte ToolingManifest.json a vyžaduje souhlas administrátora. Tento krok je vždy oddělený od přidávání serverů do manifestu.
  4. Integrujte do kódu – načtěte manifest a registrujte nástroje pomocí orchestrátoru.
  5. Vyvolává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:

  • Agent 365 CLI nainstalován a nakonfigurován
  • .NET 8.0 SDK nebo vyšší – Stáhnout
  • Oprávnění globálního správce ve vašem klientovi Microsoft 365

Nastavení identity agenta

Pokud používáte agentické ověření, dokončete proces registrace agenta a vytvořte identitu agenta před konfigurací MCP serverů. Tento proces vytvoří ID agenta Entra a uživatele agenta, což umožňuje vašemu agentovi ověření a přístup k MCP nástrojům.

Nastavení ověřování OBO

Pokud používáte autentizaci On-Behalf-Of (OBO) místo agentické autentizace, váš agent může přistupovat k MCP nástrojům pomocí delegovaných uživatelských oprávnění bez identity agenta. V rámci toku OBO agent vyměňuje delegovaný token uživatele, aby mohl provádět akce jménem uživatele.

Další informace o tom, jak funguje tok OBO, najdete v části Toky autentizace. Pro kompletní příklad implementace viz ukázka autorizace OBO v Sadě SDK pro agenty Microsoft 365.

Nastavení instančního objektu

Spusťte tento jednorázový skript pro nastavení, abyste ve svém tenantu vytvořili service principal pro Agent 365 Tools.

Důležité

Tato jednorázová operace prováděná za každý tenant vyžaduje globální administrátorská práva.

  1. Stáhněte skript 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. Jakmile budete vyzváni, přihlaste se pomocí svého Azure účtu.

Po dokončení je váš tenant připraven pro vývoj agentů a konfiguraci MCP serverů.

Konfigurace serverů MCP

Použijte Agent 365 CLI k objevování, přidávání a správě MCP serverů pro vašeho agenta. Pro úplný seznam dostupných MCP serverů a jejich funkcí viz katalog MCP serverů.

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

Vypsat všechny MCP servery, které můžete konfigurovat:

a365 develop list-available

Přidání MCP serverů

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

a365 develop add-mcp-servers mcp_MailTools

Důležité

Tento příkaz pouze aktualizuje ToolingManifest.json ve vaší složce projektu – neuděluje žádná oprávnění podrobnému plánu. Způsob udělení oprávnění závisí na tom, v jaké části procesu nastavení se nacházíte:

  • Před počátečním nastavením: Nejprve spusťte a365 develop add-mcp-servers, poté pokračujte pomocí a365 setup all. Příkaz setup all zahrnuje krok udělení oprávnění MCP jako součást vytváření podrobného plánu.
  • Po vytvoření podrobného plánu: Globální administrátor musí spustit a365 setup permissions mcp zvlášť. Správce musí mít a365.config.json s deploymentProjectPath nastaveným na složku projektu obsahující aktualizované ToolingManifest.json. Dokud tento krok není dokončen, nová oprávnění MCP serveru nejsou v podrobném plánu viditelná.

Seznam nakonfigurovaných serverů

Zobrazit aktuálně nakonfigurované MCP servery:

a365 develop list-configured

Odstranit MCP servery

Odstraňte MCP server ze své konfigurace:

a365 develop remove-mcp-servers mcp_MailTools

Pro kompletní referenci CLI viz příkaz a365 develop.

Použijte server pro simulované nástroje pro testování

Pro účely testování a vývoje používejte server se simulovaným nástrojem Agent 365 CLI namísto připojení ke skutečným serverům MCP. Simulovaný server simuluje interakce MCP serveru, takže můžete svého agenta testovat lokálně bez externích závislostí, jako je autentizace.

Simulovaný server nabízí následující výhody pro lokální vývoj a testování:

  • Offline vývoj: Otestujte svého agenta bez připojení k internetu nebo externích závislostí.
  • Konzistentní testování: Získáte předvídatelné odpovědi při testování hraničních případů.
  • Ladění: Zobrazování všech požadavků a odpovědí v reálném čase
  • Rychlá iterace: nemusíte čekat na volání na externí API ani nastavovat složitá testovací prostředí.

Spusťte simulovaný server nástrojů pomocí příkazu a365 develop start-mock-tooling-server.

Naučte se nastavit a nakonfigurovat simulovaný server nástrojů.

Poznámka

Následující sekce pro konfiguraci manifestů a integraci nástrojů do vašeho agenta fungují stejným způsobem, ať už používáte simulovaný server nástrojů nebo skutečné MCP servery. Nastavte svou proměnnou prostředí MCP_PLATFORM_ENDPOINT tak, aby ukazovala na simulovaný server (například: http://localhost:5309) místo produkčního koncového bodu.

Pochopte manifest nástrojů

Když spustíte a365 develop add-mcp-servers, CLI vygeneruje soubor ToolingManifest.json s konfigurací pro všechny MCP servery. Modul runtime agenta používá tento manifest k určení, které servery jsou dostupné a jak se k nim autentizovat.

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ý záznam MCP serveru obsahuje:

Parametr Popis
mcpServerName Zobrazovaný název serveru MCP.
mcpServerUniqueName Jedinečný identifikátor instance MCP serveru.
scope Rozsah OAuth potřebný pro přístup k schopnostem MCP serveru (například: McpServers.Mail.All pro operace e-mailu). Příkaz add-mcp-servers tuto hodnotu získá z katalogu MCP serveru.
audience Identifikátor URI Microsoft Entra ID, který identifikuje cílový zdroj API. Příkaz add-mcp-servers tuto hodnotu získá z katalogu MCP serveru.

Poznámka

Agent 365 CLI automaticky nastaví hodnoty scope a audience při přidání MCP serveru. Tyto hodnoty pocházejí z katalogu MCP serverů a definují oprávnění potřebná k přístupu ke každému MCP serveru.

Integrujte nástroje do vašeho agenta

Po vygenerování manifestu nástrojů integrujte konfigurované MCP servery do kódu vašeho agenta. Tato část pokrývá volitelný krok inspekce a požadované integrační kroky.

Seznam serverů nástrojů (volitelné)

Zpropitné

Tento krok je nepovinný. Použijte službu konfigurace serveru nástrojů ke kontrole dostupných serverů nástrojů z manifestu nástrojů před jejich přidáním do vašeho orchestrátoru.

Pomocí služby konfigurace serveru nástrojů zjistěte, které servery nástrojů jsou pro váš agent dostupné na základě manifestu nástrojů. Tato metoda vám umožňuje:

  • Získejte seznam všech konfigurovaných MCP serverů ze souboru ToolingManifest.json.
  • Získejte metadata a schopnosti serveru.
  • Před registrací ověřte dostupnost serveru.

Metoda pro výpis serverů nástrojů je dostupná 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ý identifikátor aplikace agenta Požadováno
auth_token str Nosný token pro autentizaci pomocí brány MCP serveru Platný nosný token OAuth Požadováno

Balíček: microsoft_agents_a365.tooling

Registrujte nástroje ve svém orchestrátoru

Použijte frameworkem specifickou rozšiřující metodu pro registraci všech MCP serverů ve vašem orchestračním frameworku:

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

Tyto metody:

  • Zaregistrujte všechny nástroje z konfigurovaných MCP serverů ve svém orchestrátoru
  • Automatické nastavení údajů pro ověřování a připojení
  • Nástroje jsou okamžitě k dispozici, aby je váš agent mohl použít.

Vyberte si rozšíření orchestrátoru

Modul Agent 365 Tooling poskytuje specializované rozšiřující balíčky pro různé orchestrační rámce:

Poznámka

Když spustíte a365 develop add-mcp-servers, CLI automaticky načte OAuth rozsahy a hodnoty audience z katalogu MCP serveru a zapíše je do ToolingManifest.json. Metody rozšíření využívají tyto hodnoty k nastavení autentizace za běhu – ve vašem kódu agenta není vyžadována žádná ruční konfigurace. Globální administrátor však musí stále udělit tato oprávnění agent podrobného plánu, než je váš agent bude moci použít v produkčním prostředí: prostřednictvím a365 setup all (při prvním nastavení) nebo a365 setup permissions mcp (pokud již podrobný plán existuje).

Pro podrobné příklady implementace viz Ukázky Agent 365.

Příklady implementace

Následující příklady ukazují, jak integrovat Agent 365 Tooling s různými orchestračními rámci.

Python s OpenAI

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

1. Přidání příkazů importu

Přidejte potřebné importy pro přístup k modulu Tooling a rozšířením 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 pro konfiguraci a registraci 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 MCP nástrojů u agenta AI OpenAI

Použijte metodu add_tool_servers_to_agent pro registraci všech nakonfigurovaných MCP nástrojů u vašeho OpenAI agenta. Tato metoda zpracovává jak scénáře agentické, tak neagentické autentizace:

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, které je třeba použít s add_tool_servers_to_agent.

Parametr Popis
agent Instance agenta OpenAI určená k registraci nástrojů.
agentic_app_id Jedinečný identifikátor agenta (agentické ID aplikace).
auth Autorizační kontext pro uživatele.
context Aktuální kontext konverzace z Agents SDK. Poskytuje identitu uživatele, metadata konverzace a kontext ověření pro bezpečnou registraci nástroje.
auth_token (Volitelné) Nosný token pro neagentické autentizační scénáře.

4. Volání během inicializace

Ujistěte se, že během inicializace před spuštěním agenta zavolá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 MCP servery ze souboru ToolingManifest.json.
  • Registruje jejich nástroje u agenta OpenAI.
  • Nastavuje autentifikaci na základě konfigurace manifestu.
  • Zpřístupní nástroje vašemu agentovi k použití.

Pro kompletní ukázky viz úložiště ukázek Agent 365.

Další způsoby přístupu k MCP serverům Agent 365

Kromě Agent 365 SDK můžete přistupovat k MCP serverům Agent 365 prostřednictvím dalších vývojových prostředí:

  • Visual Studio Code – Připojte se přímo k MCP serverům pro vlastní vývojové pracovní postupy.
  • Microsoft Copilot Studio – Integrujte MCP servery do konverzačních toků pomocí prostředí s minimálním psaním kódu.
  • Azure AI Foundry – Používejte MCP servery s kompletní podporou SDK a pokročilými orchestračními schopnostmi.

Pro kompletní přehled dostupných MCP serverů a možností integrace napříč těmito platformami si přečtěte Přehled serverů nástrojů Agent 365.

Vlastní MCP server (BYO)

Funkce Bring Your Own (BYO) MCP server vám umožňuje registrovat vaše vlastní externí MCP servery v Microsoft Agent 365, aby mohly být centrálně spravovány, schvalovány a monitorovány v administračním centru Microsoft 365. Servery jsou směrovány přes bránu nástrojů Agent 365, což umožňuje administrátorům kontrolovat schvalování, přístup a politiky, zatímco bezpečnostní týmy mohou sledovat využití prostřednictvím telemetrie. Jako vývojář můžete zaregistrovat svůj MCP server pomocí Agent 365 CLI, poté požádat administrátora o kontrolu a schválení registrace a udělení oprávnění. Schválený server lze následně použít v podporovaných klientských nástrojích, přičemž průběžné monitorování zajišťuje soulad a přehled napříč všemi integracemi.

Pro úplné pokyny viz Vlastní (BYO) MCP server.

Otestujte svého agenta

Po integraci MCP nástrojů do vašeho agenta otestujte jejich invokace, abyste se ujistili, že fungují správně a zvládají různé scénáře. Postupujte podle testovacího průvodce pro nastavení vašeho prostředí. Poté se zaměřte především na sekci Testování volání nástrojů, abyste ověřili, že vaše MCP nástroje fungují podle očekávání. Také se podívejte na mock tooling server pro testování připojení k MCP serveru a volání nástrojů bez nutnosti autentizace.

Přidat pozorovatelnost

Přidejte do svého agenta pozorovatelnosti, abyste mohli monitorovat a sledovat volání MCP nástrojů. Přidáním funkcí pozorovatelnosti můžete sledovat výkon, ladit problémy a rozumět vzorcům používání nástrojů. Zjistěte více o implementaci trasování a monitoringu.

Řešení problému

Tato sekce uvádí běžné problémy při konfiguraci a používání MCP serverů a nástrojů.

Zpropitné

Průvodce odstraňováním problémů Agent 365 obsahuje doporučení k odstraňování problémů na vysoké úrovni, osvědčené postupy a odkazy na obsah o řešení problémů pro každou část životního cyklu vývoje Agent 365.

Problémy s MCP serverem a nástroji

Příznaky:

  • Selhání volání nástrojů.
  • Chyby „MCP server nenalezen“.
  • Chyby „Oprávnění odepřeno“ při volání nástrojů.

Hlavní příčina:

  • MCP server není nakonfigurovaný.
  • Chybí oprávnění.
  • Instanční objekt není nastaven.
  • Nejasnosti mezi simulovanými a produkčními servery.

Řešení: Vyzkoušejte následující postupy k odstranění problému.

  • Ověřte, že jsou MCP servery nakonfigurovány

    Zobrazte seznam nakonfigurovaných serverů a přidejte chybějící.

    # List configured servers
a365 develop list-configured

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

  • Ověřte, že existuje instanční objekt

    Ujistěte se, že je vytvořen požadovaný instanční objekt pro nástroje.

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

  • Pro rané fáze vývoje a testování používejte simulované servery

    Pro rané fáze vývoje a testování použijte simulovaný server nástrojů, pokud chcete otestovat zbytek svého agenta bez produkčních komponent nástrojů.

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

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

    Zjistěte více o simulovaném serveru nástrojů.

  • Ověřte oprávnění v centru pro správu

    Ověřte, že váš agent má potřebná oprávnění MCP.

    • Ověřte, že oprávnění API podrobného plánu vašeho agenta na webu Azure Portal zobrazují veškerá oprávnění MCP serveru.

    Ověření:

    # Test a tool call in Agents Playground
# Should execute without permission errors
  • Last updated on