Del via

Tilføje og administrere værktøjer

Vigtigt

Du skal være en del af Frontier-forhåndsversionsprogrammet for at få tidlig adgang til Microsoft Agent 365. Frontier forbinder dig direkte med Microsofts seneste AI-innovationer. Frontier-forhåndsversioner er underlagt de eksisterende forhåndsversionsbetingelser i dine kundeaftaler. Da disse funktioner stadig er under udvikling, kan deres tilgængelighed og egenskaber ændre sig over tid.

Værktøjsmodulet gør det muligt for udviklere 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 en arbejdsproces i fire trin:

  1. Konfigurer MCP-servere – Brug Agent 365 CLI til at finde og tilføje MCP-servere
  2. Generér manifest – CLI opretter ToolingManifest.json med serverkonfigurationer
  3. Integrer i kode – Indlæs manifest- og registreringsværktøjer med din organisator
  4. 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. Dette opretter det agentbaserede app-id og den agentbaserede bruger, hvilket gør det muligt for din agent at godkende og få adgang til MCP-værktøjer.

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 naviger til scriptmappen

  3. Kør 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, der kan konfigureres:

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

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 få en komplet CLI-reference i udviklerkommandoen a365.

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:

Parametre Beskrivelser
mcpServerName Det viste navn på MCP-serveren
mcpServerUniqueName Det entydige id for MCP-serverforekomsten
omfang Det OAuth-område, der kræves for at få adgang til MCP-serverens funktioner (f.eks. McpServers.Mail.All til mailhandlinger). Denne værdi hentes fra MCP-serverkataloget, når du kører kommandoen add-mcp-servers.
målgruppe URI'en for Microsoft Entra ID, der identificerer destinations-API-ressourcen. Denne værdi hentes også fra MCP-serverkataloget.

Bemærk

Værdierne scope og audience udfyldes automatisk af Agent 365 CLI, 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
  • Hente servermetadata og -egenskaber
  • Kontrollere servertilgængelighed før registrering

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 Krævet/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:

  • microsoft-agents-a365-tooling: Kerneværktøjsfunktionalitet
  • microsoft-agents-a365-tooling-extensions-agentframework: Agent Framework-integration
  • microsoft-agents-a365-tooling-extensions-azureaifoundry: Azure AI Foundry-integration
  • microsoft-agents-a365-tooling-extensions-openai: OpenAI-integration
  • microsoft-agents-a365-tooling-extensions-semantickernel: Semantic Kernel-integration

Bemærk

Godkendelse konfigureres automatisk af Agent 365 CLI, når du kører a365 develop add-mcp-servers. OAuth-områder og -målgruppeværdier hentes fra MCP-serverkataloget og medtages i ToolingManifest.json. Udvidelsesmetoderne bruger automatisk disse værdier til at konfigurere godkendelse – der kræves ingen manuel konfiguration.

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.

Parametre Beskrivelser
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
  • 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.

Test og overvåg

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 testvejledningen for at konfigurere dit miljø, og fokuser derefter primært på afsnittet Aktivering af testværktøjer for at validere, at dine MCP-værktøjer fungerer som forventet.

Tilføj observerbarhed

Føj observerbarhed til din agent for at overvåge og spore din agents aktivering af MCP-værktøjer, tilføje observerbarhedsfunktioner til sporing af ydeevne, foretage fejlfinding af problemer og forstå mønstre for værktøjsanvendelse. Få mere at vide om implementering af sporing og overvågning

  • Last updated on