Tilføje og administrere værktøjer

Værktøjsmodulet hjælper udviklere med at finde, konfigurere og integrere MCP-servere (Model Context Protocol) i arbejdsprocesser for AI-agenter. MCP-servere viser eksterne funktioner som værktøjer, AI-agenter kan aktivere. Du kan få en oversigt over tilgængelige værktøjsservere under Agent 365-værktøjsservere.

Viser anmodnings- og svarflowet

Oversigt

Integration af Agent 365 Tooling følger denne arbejdsproces:

  1. Konfigurer MCP-servere – Brug Agent 365 CLI til at finde og tilføje MCP-servere
  2. Generér manifest – CLI opretter ToolingManifest.json i din projektmappe med serverkonfigurationer.
  3. Anvend tilladelser til blueprint – en global administrator giver OAuth2-tilladelser til agent-blueprintet ved at køre a365 setup all (første opsætning) eller a365 setup permissions mcp (hvis blueprintet allerede eksisterer). Under alle omstændigheder læser kommandoen ToolingManifest.json og kræver administratorens samtykke. Dette trin er altid anderledes end tilføjelsen af servere i manifestet.
  4. Integrer i kode – Indlæs manifest- og registreringsværktøjer med din organisator.
  5. Aktivér værktøjer – Agent kalder værktøjer under kørsel for at udføre handlinger.

Forudsætninger

Før du konfigurerer MCP-servere, skal du sikre dig, at du har:

  • Agent 365 CLI installeret og konfigureret
  • .NET 8.0 SDK eller nyere – Download
  • Globale administratorrettigheder i din Microsoft 365-lejer

Konfiguration af agentidentitet

Hvis du bruger agentbaseret godkendelse, skal du fuldføre agentregistreringsprocessen for at oprette din agentidentitet, før du konfigurerer MCP-servere. Denne proces opretter Entra-agent-id’et og agentbrugeren, som gør det muligt for din agent at logge ind og få adgang til MCP-værktøjerne.

OBO-godkendelseskonfiguration

Hvis du bruger On-Behalf-Of-godkendelse (OBO) i stedet for agentbaseret godkendelse, kan din agent få adgang til MCP-værktøjer ved at bruge delegerede brugerrettigheder uden agentbrugeridentitet. I OBO-flowet udveksler agenten en brugers delegerede token for at udføre handlinger på brugerens vegne.

Få flere oplysninger om, hvordan OBO-flowet fungerer, i Godkendelsesflow. Du kan se et komplet implementeringseksempel i OBO-godkendelseseksempel i SDK til Microsoft 365-agenter.

Konfigurer tjenesteprincipal

Kør dette engangsinstallationsscript for at oprette tjenesteprincipalen for Agent 365-værktøjer i din lejer.

Vigtigt!

Dette er en engangshandling pr. lejer, der kræver globale administratorrettigheder.

  1. Download scriptet New-Agent365ToolsServicePrincipalProdPublic.ps1.

  2. Åbn PowerShell som administrator, og gå til scriptmappen.

  3. Køre scriptet.

    .\New-Agent365ToolsServicePrincipalProdPublic.ps1

  4. Log på med dine Azure-legitimationsoplysninger, når du bliver bedt om det.

Når du er færdig, er din lejer klar til agentudvikling og konfiguration af MCP-serveren.

Konfigurere MCP-servere

Brug Agent 365 CLI til at finde, tilføje og administrere MCP-servere for din agent. Du kan se en komplet liste over tilgængelige MCP-servere og deres funktioner i MCP-serverkataloget.

Find tilgængelige servere

Vis alle MCP-servere, som du kan konfigurere:

a365 develop list-available

Tilføj MCP-servere

Føj en eller flere MCP-servere til din agentkonfiguration:

a365 develop add-mcp-servers mcp_MailTools

Vigtigt!

Denne kommando opdaterer kun ToolingManifest.json i din projektmappe – den giver ikke nogen tilladelser til blueprintet. Den måde, tilladelser bliver anvendt på, afhænger af, hvor du er i opsætningsprocessen:

  • Gør følgende, inden opsætningen påbegyndes: Kør a365 develop add-mcp-servers først, og fortsæt med a365 setup all. Kommandoen setup all inkluderer MCP-tilladelsestrinnet som en del af blueprint-oprettelsen.
  • Gør følgende, når Blueprint allerede eksisterer: En Global Administrator skal køre a365 setup permissions mcp separat. Administratorens a365.config.json skal have deploymentProjectPath rettet mod projektmappen, der indeholder den opdaterede ToolingManifest.json. Indtil dette trin er færdigt, er de nye MCP-servertilladelser ikke synlige i blueprintet.

Vis konfigurerede servere

Vis aktuelt konfigurerede MCP-servere:

a365 develop list-configured

Fjern MCP-servere

Fjern en MCP-server fra konfigurationen:

a365 develop remove-mcp-servers mcp_MailTools

Du kan se hele CLI-referencen i udviklerkommandoen a365.

Brug modelværktøjsserveren til at teste

Du kan bruge Agent 365 CLI-modelserveren til test og udvikling i stedet for at oprette forbindelse til rigtige MCP-servere. Modelserveren simulerer MCP-serverinteraktioner, så du kan teste din agent lokalt uden eksterne afhængigheder som f.eks. godkendelse.

Simuleringsserveren giver følgende fordele for lokal udvikling og test:

  • Offline udvikling: Test din agent uden internetforbindelse eller eksterne afhængigheder.
  • Konsistent test: Modtag forudsigelige svar til test af grænsetilfælde.
  • Fejlfinding: Se alle forespørgsler og svar i realtid
  • Hurtig gentagelse: Der er ikke behov for at vente på eksterne API-kald eller indstille komplekse testmiljøer.

Start modelværktøjsserveren ved hjælp af kommandoen a365 develop start-mock-tooling-server.

Lær at opsætte og konfigurere modelværktøjsserveren.

Bemærk!

De følgende afsnit om konfiguration af manifester og integration af værktøjer i din agent fungerer på samme måde, uanset om du bruger modelværktøjsserveren eller MCP-servere. Indstil din MCP_PLATFORM_ENDPOINT-miljøvariabel til at pege på modelværktøjsserveren (for eksempel: http://localhost:5309) i stedet for produktionsslutpunktet.

Forstå værktøjsmanifestet

Når du kører a365 develop add-mcp-servers, genererer CLI en ToolingManifest.json-fil, der indeholder konfigurationen for alle MCP-servere. Agentens kørsel bruger dette manifest til at forstå, hvilke servere der er tilgængelige, og hvordan de skal godkende med dem.

Manifeststruktur

Eksempel ToolingManifest.json:

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

Manifestparametre

Hver MCP-serverpost indeholder:

Parameter Beskrivelse
mcpServerName MCP-serverens viste navn.
mcpServerUniqueName MCP-serverforekomstens entydige id.
omfang Det OAuth-område, der kræves for at få adgang til MCP-serverens funktioner (f.eks. McpServers.Mail.All til mailhandlinger). Kommandoen add-mcp-servers henter denne værdi fra MCP-serverkataloget.
målgruppe URI'en for Microsoft Entra ID, der identificerer destinations-API-ressourcen. Kommandoen add-mcp-servers henter denne værdi fra MCP-serverkataloget.

Bemærk!

Agent 365 CLI udfylder automatisk værdierne scope og audience, når du tilføjer en MCP-server. Disse værdier kommer fra MCP-serverkataloget og definerer de tilladelser, der kræves for at få adgang til de enkelte MCP-servere.

Integrer værktøjer i din agent

Når du har genereret værktøjsmanifestet, skal du integrere de konfigurerede MCP-servere i din agentkode. I dette afsnit beskrives det valgfrie inspektionstrin og de påkrævede integrationstrin.

Vis værktøjsservere (valgfrit)

Tip

Dette trin er valgfrit. Brug konfigurationstjenesten til værktøjsserveren til at undersøge tilgængelige værktøjsservere fra værktøjsmanifestet, før du føjer dem til din organisator.

Brug konfigurationstjenesten til værktøjsserveren til at finde ud af, hvilke værktøjsservere der er tilgængelige for din agent fra værktøjsmanifestet. Med denne metode kan du:

  • Forespørge alle konfigurerede MCP-servere fra ToolingManifest.json-filen.
  • Hent servermetadata og -egenskaber.
  • Kontroller servertilgængelighed før registreringen.

Metoden til visning af værktøjsservere er tilgængelig i pakkerne med kerneværktøj:

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

Parametre:

Parameter Type Beskrivelse Forventet værdi Obligatorisk/valgfri
agentic_app_id str Det entydige id for forekomsten af agentprogrammet Gyldig id-streng til agentprogram Obligatorisk
auth_token str Ihændehavertoken til godkendelse med MCP-servergatewayen Gyldigt OAuth-ihændehavertoken Obligatorisk

Pakke: microsoft_agents_a365.tooling

Registrer værktøjer med din organisator

Brug den strukturspecifikke udvidelsesmetode til at registrere alle MCP-servere med orkestreringsstrukturen:

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

Disse metoder:

  • Registrer alle værktøjer fra konfigurerede MCP-servere med din organisator
  • Konfigurer automatisk godkendelses- og forbindelsesoplysninger
  • Gør værktøjer tilgængelige med det samme, så din agent kan aktivere dem

Vælg din organisatorudvidelse

Agent 365 Tooling-modulet indeholder dedikerede udvidelsespakker til forskellige orkestreringsstrukturer:

Bemærk!

Når du kører a365 develop add-mcp-servers, henter CLI'en automatisk OAuth-omfang og målgruppeværdier fra MCP-serverkataloget og skriver dem til ToolingManifest.json. Udvidelsesmetoderne bruger disse værdier til at konfigurere godkendelsen under kørsel – du skal ikke konfigurere din agentkode manuelt. En Global Administrator skal dog stadig give disse tilladelser til agentens blueprint, før din agent kan bruge dem i produktion. Dette gøres via a365 setup all (første opsætning) eller a365 setup permissions mcp (hvis blueprintet allerede findes).

Du kan finde detaljerede implementeringseksempler i Agent 365-eksempler.

Implementeringseksempler

Følgende eksempler viser, hvordan du integrerer Agent 365 Tooling med forskellige orkestreringsstrukturer.

Python med OpenAI

I dette eksempel kan du se, hvordan du integrerer MCP-værktøjer med OpenAI i et Python-program.

1. Tilføj importsætninger

Tilføj de nødvendige importer for at få adgang til Tooling-modulet og OpenAI-udvidelserne:

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

2. Initialiser værktøjstjenester

Opret forekomster af tjenesterne til registrering af konfiguration og værktøjer:

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

3. Registrer MCP-værktøjer med OpenAI-agent

Brug metoden add_tool_servers_to_agent til at registrere alle konfigurerede MCP-værktøjer med din OpenAI-agent. Denne metode håndterer både agentbaserede og ikke-agentbaserede godkendelsesscenarier:

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

Metodeparametre

I følgende tabel beskrives de parametre, der skal bruges med add_tool_servers_to_agent.

Parameter Beskrivelse
agent OpenAI-agentforekomsten, der skal registreres værktøjer med.
agentic_app_id Det entydige id for agenten (agentbaseret app-id).
auth Godkendelseskonteksten for brugeren.
context Kontekst for det aktuelle samtaleskift fra SDK til agenter. Leverer brugeridentitet, samtalemetadata og godkendelseskontekst til sikker registrering af værktøjer.
auth_token (Valgfrit) Ihændehavertoken til ikke-agentbaserede godkendelsesscenarier.

4. Ring op under initialisering

Kontrollér, at du kalder installationsmetoden under initialisering, før du kører agenten:

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

Metoden add_tool_servers_to_agent gør automatisk følgende:

  • Indlæser alle MCP-servere fra ToolingManifest.json-filen.
  • Registrerer deres værktøjer med OpenAI-agenten.
  • Konfigurerer godkendelse baseret på manifestkonfigurationen.
  • Gør værktøjerne tilgængelige for din agent, så de kan aktiveres.

Du kan se komplette arbejdseksempler i lageret med Agent 365-eksempler.

Andre metoder til at få adgang til Agent 365 MCP-servere

Ud over Agent 365 SDK'en kan du tilgå Agent 365 MCP-servere gennem andre udviklingsmiljøer:

  • Visual Studio Code – opret direkte forbindelse til MCP-servere for at lave tilpassede udviklingsforløb.
  • Microsoft Copilot Studio – integrer MCP-servere i samtaleflow ved hjælp af en low-code løsning.
  • Azure AI Foundry – brug MCP-servere med fuld SDK-understøttelse og avancerede orkestreringsmuligheder.

Få et komplet overblik over tilgængelige MCP-servere og integrationsmuligheder til disse platforme i Agent 365 tooling server-oversigt.

Medbring din egen MCP-server (BYO)

Funktionen Medbring din egen MCP-server (BYO) giver dig mulighed for at registrere dine egne eksterne MCP-servere med Microsoft Agent 365, så de kan styres centralt, godkendes og overvåges i Microsoft 365 Administration. Den dirigerer disse servere gennem Agent 365 tooling-gateway, hvilket giver administratorer kontrol over godkendelse, adgang og politikker, samtidig med at sikkerhedsteams kan spore brugen via telemetri. Som udvikler kan du registrere din MCP-server med Agent 365 CLI, hvorefter din administrator skal gennemgå og godkende registreringen samt tildele tilladelser. Den godkendte server kan derefter bruges i understøttede klienter, mens løbende overvågning sikrer overholdelse og synlighed i alle integrationer.

Se hele vejledningen i Medbring din egen MCP-server (BYO).

Test din agent

Når du har integreret MCP-værktøjer i din agent, skal du teste aktiveringerne af værktøjerne for at sikre, at de fungerer korrekt og kan håndtere forskellige scenarier. Følg testguiden for at indstille dit miljø. Fokuser derefter primært på afsnittet Test værktøjsaktiveringer for at validere, at dine MCP-værktøjer fungerer som forventet. Tjek også modelværktøjsserveren for at teste MCP-serverforbindelsen og værktøjskald uden at håndtere godkendelse.

Tilføj observerbarhed

Tilføj observationsmulighed i din agent for at overvåge og spore din agents MCP-værktøjskald. Ved at tilføje overvågningsfunktioner kan du holde øje med ydeevnen, rette fejl og forstå, hvordan værktøjerne bruges. Få mere at vide om implementering af sporing og overvågning.

Fejlfinding

Denne sektion beskriver de typiske problemer, du kan opleve, når du konfigurerer og bruger MCP-servere og værktøjer.

Tip

Agent 365 Fejlfindingsguide indeholder overordnede anbefalinger til fejlfinding, bedste praksis og links til fejlfindingsindhold for hver fase af udviklingslivscyklussen for Agent 365.

MCP-server- og værktøjsproblemer

Symptomer:

  • Fejl i værktøjskald.
  • "MCP-server ikke fundet"-fejl.
  • Fejl: Adgang nægtet, når værktøjer kaldes.

Rodårsag:

  • MCP-serveren er ikke konfigureret.
  • Manglende tilladelser.
  • Tjenesteprincipal er ikke konfigureret.
  • Model- og produktionsservere forveksles ved en fejl.

Løsninger: Prøv følgende løsninger for at løse problemet.

  • Kontroller, at MCP-serverne er konfigureret

    Vis en liste med konfigurerede servere, og tilføj eventuelle manglende servere.

    # List configured servers
a365 develop list-configured

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

  • Kontroller, at tjenesteprincipal eksisterer

    Sørg for, at den nødvendige tjenesteprincipal er oprettet til brug for værktøjerne.

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

  • Brug modelservere til tidlig udvikling og test

    Brug modelværktøjsserveren til tidlig lokal udvikling og test, hvis du vil teste resten af din agent uden komponenter fra produktionsværktøjer.

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

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

    Få mere at vide om modelværktøjsserveren.

  • Bekræft tilladelser i Administration

    Bekræft, at din agent har de nødvendige MCP-tilladelser.

    • Valider, at dine API-tilladelser til agent-blueprint i Azure Portal viser alle MCP-servertilladelser.

    Bekræftelse:

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