Legg til og administrer verktøy

Verktøymodulen hjelper utviklere med å oppdage, konfigurere og integrere Model Context Protocol (MCP)-servere i KI-agentens arbeidsflyter. MCP-servere eksponerer eksterne muligheter som verktøy som KI-agenter kan kalle opp. For en oversikt over tilgjengelige verktøyservere se Agent 365-verktøyservere.

Demonstrerer forespørsels- og svarflyten

Oversikt

Agent 365-verktøyintegrasjonen følger denne arbeidsflyten:

  1. Konfigurer MCP-servere – Bruk Agent 365 CLI for å oppdage og legge til MCP-servere
  2. Generer manifest – CLI opprettes ToolingManifest.json i prosjektmappen din med serverkonfigurasjoner.
  3. Gi tillatelser til blåkopi – En global administrator tildeler OAuth2-tillatelser til agentblåkopien ved å kjøre a365 setup all (førstegangsoppsett) eller a365 setup permissions mcp (hvis blåkopien allerede er opprettet). I begge tilfeller leser kommandoen ToolingManifest.json og krever administratorsamtykke. Dette trinnet er alltid adskilt fra å legge til servere i manifestet.
  4. Integrering i kode – last inn manifestet og registrer verktøyene med din iverksetter.
  5. Kjør verktøy – Agenten bruker verktøy under utførelse for å utføre operasjoner.

Forutsetning

Før du konfigurerer MCP-servere, sørg for at du har:

  • Agent 365 CLI installert og konfigurert
  • .NET 8.0 SDK eller nyere – Last ned
  • Globale administratorrettigheter i din Microsoft 365-leietaker

Agentidentitetsoppsett

Hvis du bruker agentisk autentisering, fullfør agentregistreringsprosessen for å opprette agentidentiteten før du konfigurerer MCP-servere. Denne prosessen oppretter Entra-agent-ID-en og agentbrukeren som gjør det mulig for agenten din å autentisere og få tilgang til MCP-verktøyene.

Oppsett av på-vegne-av-godkjenning

Hvis du bruker på-vegne-av-autentisering (OBO) i stedet for agentisk autentisering, kan agenten din få tilgang til MCP-verktøy ved å bruke tillatelser for delegert bruker uten en agentbrukeridentitet. I OBO-flyten utveksler agenten en brukers delegerte token for å utføre handlinger på brukerens vegne.

For mer informasjon om hvordan OBO-flyten fungerer se Autentiseringsflyter. For et fullstendig eksempel på implementering se OBO-autorisasjonseksempelet i SDK for Microsoft 365-agenter.

Konfigurer tjenestekontohaver

Kjør dette engangsoppsettsskriptet for å opprette tjenesteprinsippet for Agent 365 Tools i din leietaker.

Viktig!

Denne engangsoperasjonen per leietaker krever Global administrator-rettigheter.

  1. Last ned skriptet New-Agent365ToolsServicePrincipalProdPublic.ps1.

  2. Åpne PowerShell som administrator og gå til skriptkatalogen.

  3. Kjør skriptet.

    .\New-Agent365ToolsServicePrincipalProdPublic.ps1

  4. Logg på med legitimasjonen for Azure når du blir bedt om det.

Etter ferdigstillelse er leietakeren din klar for agentutvikling og MCP-serverkonfigurasjon.

Konfigurer MCP-servere

Bruk Agent 365 CLI for å oppdage, legge til og administrere MCP-servere for agenten din. For en komplett liste over tilgjengelige MCP-servere og deres egenskaper se MCP-serverkatalogen.

Oppdag tilgjengelige servere

Vis alle MCP-servere du kan konfigurere:

a365 develop list-available

Legg til MCP-servere

Legg til en eller flere MCP-servere i agentkonfigurasjonen din:

a365 develop add-mcp-servers mcp_MailTools

Viktig!

Denne kommandoen oppdateres ToolingManifest.json bare i prosjektmappen din – den gir ingen tillatelser til blåkopien. Hvordan tillatelser tildeles avhenger av hvor du er i oppsettsprosessen:

  • Før første oppsett: Kjør a365 develop add-mcp-servers først, og fortsett deretter med a365 setup all. Kommandoen setup all inkluderer MCP-tillatelsestrinnet som en del av blåkopiopprettelsen.
  • Når blåkopien allerede eksisterer: En global administrator må kjøre a365 setup permissions mcp separat. Administratorens a365.config.json må ha deploymentProjectPath som peker på prosjektmappen som inneholder den oppdaterte ToolingManifest.json. Inntil dette trinnet er fullført, er de nye MCP-servertillatelsene ikke synlige i blåkopien.

Vis konfigurerte servere

Vis konfigurerte MCP-servere:

a365 develop list-configured

Fjern MCP-servere

Fjern en MCP-server fra konfigurasjonen:

a365 develop remove-mcp-servers mcp_MailTools

For fullstendig CLI-referanse se a365 develop-kommandoen.

Bruk falsk verktøyserver for testing

For testing og utvikling bruk falsk Agent 365 CLI-verktøyserver i stedet for å koble til faktiske MCP-servere. Falsk server simulerer MCP-serversamhandlinger, slik at du kan teste agenten din lokalt uten eksterne avhengigheter som autentisering.

Den simulerte serveren byr på følgende fordeler for lokal utvikling og testing:

  • Frakoblet utvikling: Test agenten uten Internett-tilkobling eller eksterne avhengigheter.
  • Konsekvent testing: Motta forutsigbare svar for testing av kanttilfeller.
  • Feilsøking: Vis alle forespørsler og svar i sanntid
  • Rask gjentakelse: Du trenger ikke å vente på eksterne API-oppkall eller konfigurere kompliserte testmiljøer.

Start falsk verktøyserver med kommandoen a365 develop start-mock-tooling-server.

Lær hvordan du setter opp og konfigurerer falsk verktøyserver.

Notat

De følgende delene for å konfigurere manifester og integrere verktøy i agenten din fungerer på samme måte enten du bruker falsk verktøyserver eller faktiske MCP-servere. Konfigurer miljøvariabelen MCP_PLATFORM_ENDPOINT slik at den peker på falsk verktøyserver (f.eks.: http://localhost:5309) i stedet for produksjonsendepunktet.

Forstå verktøymanifestet

Når du kjører a365 develop add-mcp-servers, genererer CLI-en en ToolingManifest.json-fil som inneholder konfigurasjon for alle MCP-servere. Agentens kjøretid bruker dette manifestet for å forstå hvilke servere som er tilgjengelige og hvordan de skal autentiseres.

Manifestets struktur

Eksempel ToolingManifest.json:

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

Manifestparametere

Hver MCP-serveroppføring inneholder:

Parameter Description
mcpServerName Visningsnavnet for MCP-serveren.
mcpServerUniqueName Unik identifikator for MCP-serverforekomst.
omfang OAuth-omfanget som kreves for å få tilgang til MCP-serverens funksjoner (eksempel: McpServers.Mail.All for e-postoperasjoner). Kommandoen add-mcp-servers henter denne verdien fra MCP-serverkatalogen.
målgruppe Microsoft Entra ID-URI-en som identifiserer den aktuelle API-ressursen. Kommandoen add-mcp-servers henter denne verdien fra MCP-serverkatalogen.

Notat

Agent 365 CLI fyller automatisk inn scope- og audience-verdiene når du legger til en MCP-server. Disse verdiene hentes fra MCP-serverkatalogen og bestemmer hvilke tillatelser som kreves for å få tilgang til hver MCP-server.

Integrer verktøy i agenten din

Etter å ha generert verktøymanifestet, integrer de konfigurerte MCP-serverne i agentkoden din. Denne delen dekker det valgfrie inspeksjonstrinnet og de nødvendige integrasjonstrinnene.

List opp verktøyservere (valgfritt)

Tips

Dette trinnet er valgfritt. Bruk verktøyserverkonfigurasjonstjenesten til å inspisere tilgjengelige verktøyservere fra verktøymanifestet før du legger dem til i iverksetteren din.

Bruk verktøyserverkonfigurasjonstjenesten for å finne ut hvilke verktøyservere som er tilgjengelige for agenten din fra verktøymanifestet. Du kan gjøre følgende med denne metoden:

  • Hent alle konfigurerte MCP-servere fra ToolingManifest.json-filen.
  • Hent servermetadata og egenskaper.
  • Sjekk servertilgjengeligheten før registrering.

Metoden for å liste verktøyservere er tilgjengelig i kjerneverktøypakkene:

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

Parametere:

Parameter Type Description Forventet verdi Obligatorisk/valgfri
agentic_app_id str Den unike identifikatoren for agentappforekomsten Gyldig agentapp-ID-streng Kreves
auth_token str Bærertoken for autentisering gjennom MCP-servergatewayen Gyldig OAuth-bærertoken Kreves

Pakke: Microsoft_agents_a365.tooling

Registrer verktøy hos iverksetteren

Bruk rammeverkets utvidelsesmetode til å registrere alle MCP-servere med iverksettingsrammeverket.

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

Disse metodene:

  • Registrer alle verktøy fra konfigurerte MCP-servere i iverksetter
  • Sett opp autentisering og tilkoblingsdetaljer automatisk
  • Gjør verktøy umiddelbart tilgjengelige slik at agenten din kan bruke dem

Velg iverksetterutvidelse

Agent 365-verktøymodulen tilbyr dedikerte utvidelsespakker for ulike iverksettingsrammeverk:

Notat

Når du kjører a365 develop add-mcp-servers, henter CLI-en automatisk OAuth-omfang og målgruppeverdier fra MCP-serverkatalogen og skriver dem til ToolingManifest.json. Utvidelsesmetodene bruker disse verdiene for å sette opp autentisering under kjøring – ingen manuell konfigurasjon kreves i agentkoden din. En global administrator må imidlertid fortsatt tildele disse tillatelsene til agentblåkopien før agenten din kan bruke dem i produksjon – via a365 setup all (førstegangsoppsett) eller a365 setup permissions mcp (hvis blåkopien allerede eksisterer).

For detaljerte implementeringseksempler se Agent 365-eksempler.

Implementeringseksempler

Følgende eksempler viser hvordan man kan integrere Agent 365-verktøy med ulike iverksettingsrammeverk.

Python med OpenAI

Dette eksempelet viser hvordan man kan integrere MCP-verktøy med OpenAI i en Python-app.

1. Legg importerklæringer

Legg til nødvendige importer for å få tilgang til Tooling-modulen og OpenAI-utvidelsene:

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

2. Initialiser verktøytjenester

Opprett forekomster av konfigurasjons- og verktøyregistreringstjenester:

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

3. Registrer MCP-verktøy med OpenAI-agenten

Bruk add_tool_servers_to_agent-metoden for å registrere alle konfigurerte MCP-verktøy i OpenAI-agenten din. Denne metoden håndterer både agentbaserte og ikke-agentbaserte autentiseringsscenarioer:

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

Metodeparametere

Tabellen nedenfor beskriver parameterne som skal brukes med add_tool_servers_to_agent.

Parameter Description
agent OpenAI-agentforekomsten som verktøy skal registreres hos.
agentic_app_id Den unike identifikatoren for agenten (agentisk app-ID).
auth Brukerens autorisasjonskontekst
context Konteksten for den aktuelle samtaletur fra Agents SDK. Gir brukeridentitet, samtalemetadata og autentiseringskontekst for sikker verktøyregistrering.
auth_token (Valgfritt) Bærertoken for scenarier med ikke-agentisk autentisering.

4. Kall ved initialisering

Sørg for at du kaller oppsettsmetoden under initialiseringen før du kjører agenten:

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

Metoden add_tool_servers_to_agent gjør automatisk følgende:

  • Laster alle MCP-servere fra ToolingManifest.json-filen.
  • Registrerer verktøyene sine hos OpenAI-agenten.
  • Setter opp autentisering basert på manifestkonfigurasjonen.
  • Gjør verktøyene tilgjengelige for bruk av agenten din.

For fullstendige fungerende eksempler se Repositorium for Agent 365-eksempler.

Andre måter å få tilgang til Agent 365 MCP-servere på

I tillegg til Agent 365 SDK kan du få tilgang til Agent 365 MCP-servere gjennom andre utviklingsmiljøer:

  • Visual Studio Code – Koble direkte til MCP-servere for tilpassede utviklingsarbeidsflyter.
  • Microsoft Copilot Studio – Integrer MCP-servere i samtaleflyter ved hjelp av en lavkodebasert opplevelse.
  • Azure AI Foundry – Bruk MCP-servere med full SDK-støtte og avanserte iverksettingsmuligheter.

For en fullstendig oversikt over tilgjengelige MCP-servere og integrasjonsmuligheter på tvers av disse plattformene se Oversikt over Agent 365-verktøyservere.

Bring Your Own (BYO) MCP-server

Med Bring Your Own (BYO) MCP-server-funksjonen kan du registrere dine egne eksterne MCP-servere med Microsoft Agent 365, slik at de kan administreres, godkjennes og overvåkes sentralt i administrasjonssenteret for Microsoft 365. Den ruter disse serverne gjennom Agent 365-verktøygatewayen, som gir administratorer kontroll over godkjenning, tilgang og policyer, samtidig som sikkerhetsteamene kan spore bruken via telemetri. Som utvikler kan du registrere MCP-serveren din ved hjelp av Agent 365 CLI, og deretter kan administratoren din gjennomgå og godkjenne registreringen samt tildele nødvendige tillatelser. Den godkjente serveren kan deretter brukes i støttede klientverktøy, med kontinuerlig overvåking som sikrer etterlevelse og synlighet på tvers av alle integrasjoner.

For utfyllende instruksjoner se Bring your own (BYO) MCP-server.

Test agenten

Etter at du har integrert MCP-verktøy i agenten din, test verktøykallene for å forsikre deg om at de fungerer som de skal og håndterer ulike scenarioer. Følg testguiden for å sette opp miljøet ditt. Fokuser deretter hovedsakelig på delen Testverktøyaktiveringer for å validere at MCP-verktøyene dine fungerer som forventet. Ta en titt på falsk verktøyserver for å teste MCP-servertilkobling og verktøykall uten krav om autentisering.

Legg til observerbarhet

Legg til observerbarhet til agenten din for å overvåke og spore agentens MCP-verktøykall. Ved å legge til observerbarhetsegenskaper kan du spore ytelse, feilsøke problemer og forstå verktøybruksmønstre. Les mer om implementering av sporing og overvåking.

Feilsøking

Denne delen lister opp vanlige problemer når du konfigurerer og bruker MCP-servere og -verktøy.

Tips

Feilsøkingsveiledning for Agent 365 inneholder anbefalinger på høyt nivå for feilsøking, anbefalte fremgangsmåter og koblinger til feilsøkingsinnhold for hver fase i utviklingssyklusen i Agent 365.

MCP-server- og verktøyproblemer

Symptomer:

  • Feil i verktøyanrop.
  • MCP-server ikke funnet-feil.
  • Tillatelse nektet feil når jeg kaller verktøy.

Rotårsak:

  • MCP-serveren er ikke konfigurert.
  • Mangler tillatelser.
  • Tjenestekontohaver er ikke konfigurert.
  • Forvirring mellom falske servere og produksjonsservere.

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

  • Verifiser at MCP-serverne er konfigurert

    Vis konfigurerte servere og legg til eventuelle som mangler.

    # List configured servers
a365 develop list-configured

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

  • Sjekk om tjenestekontohaver eksisterer

    Sørg for at den nødvendige tjenestekontohaveren er opprettet for verktøyene.

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

  • For tidlig utvikling og testing bruk falske servere

    Bruk falsk verktøyserver for tidlig lokal utvikling og testing hvis du vil teste resten av agenten uten produksjonsverktøykomponenter.

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

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

    Lær om falsk verktøyserver.

  • Kontroller tillatelser i administrasjonssenteret

    Verifiser at agenten din har nødvendige MCP-tillatelser.

    • Verifiser at agentens blåkopi-API-tillatelser i Azure Portal viser alle MCP-servertillatelser.

    Verifikasjon:

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