Työkalujen lisääminen ja hallinta

Työkalumoduuli auttaa kehittäjiä löytämään, konfiguroimaan ja integroimaan Mallin kontekstin protokolla (MCP) -palvelimia osaksi tekoälyagenttien työnkulkuja. MCP-palvelimet tarjoavat ulkoisia ominaisuuksia työkaluina, joita tekoälyagentit voivat käyttää. Katso saatavilla olevien työkalupalvelimien yleiskatsaus kohdasta Agent 365 -työkalupalvelimet.

Havainnollistaa pyyntöjen ja vastausten työnkulun

Yleiskatsaus

Agent 365 Tooling -integraatio noudattaa tätä työnkulkua:

  1. Konfiguroi MCP-palvelimet – Käytä Agent 365 CLI:tä etsiäksesi ja lisätäksesi MCP-palvelimia
  2. Luo kokoonpanotiedot – CLI luo ToolingManifest.json projektikansioosi palvelinmäärityksillä.
  3. Myönnä käyttöoikeudet Blueprintille – Globaali ylläpitäjä myöntää OAuth2-oikeudet agentti Blueprintille ajamalla a365 setup all (ensimmäinen asennus) tai a365 setup permissions mcp (jos Blueprint on jo olemassa). Joka tapauksessa komento lukee ToolingManifest.json ja vaatii ylläpitäjän hyväksynnän. Tämä vaihe on aina erillään palvelimien lisäämisestä manifestiin.
  4. Integroi koodiin – lataa manifesti ja rekisteröi työkalut orkestroijalle.
  5. Kutsu työkalut – Agentti kutsuu työkaluja suorituksen aikana suorittaakseen operaatioita.

Edellytykset

Ennen MCP-palvelimien konfigurointia varmista, että sinulla on:

  • Agent 365 CLI asennettu ja konfiguroitu
  • .NET 8.0 SDK tai uudempi – Lataa
  • Yleisen järjestelmänvalvojan oikeudet Microsoft 365 -ympäristössä

Agentin identiteetin määrittely

Jos käytät agenttitunnistautumista, suorita agentin rekisteröintiprosessi luodaksesi agentti-identiteettisi ennen MCP-palvelimien määrittämistä. Tämä prosessi luo Entra-agentin tunnisteen ja agentin käyttäjätilin, jotka mahdollistavat agentin todennuksen ja MCP-työkalujen käytön.

Määritä todentautuminen jonkun nimissä

Jos käytät On-Behalf-Of (OBO) -tunnistautumista agenttitunnistautumisen sijaan, agenttisi voi käyttää MCP-työkaluja delegoiduilla käyttäjäoikeuksilla ilman agentin käyttäjäidentiteettiä. OBO-virtauksessa agentti vaihtaa käyttäjän delegoidun tunnisteen suorittaakseen toimintoja käyttäjän puolesta.

Lisätietoja OBO-työnkulun toiminnasta löytyy kohdasta Todentamistyönkulut. Täydellisen toteutusesimerkin löydät Microsoft 365 -agenttien SDK:n OBO-valtuutusesimerkistä.

Palveluobjektin määritys

Suorita tämä kertaluonteinen asennusskripti luodaksesi palveluobjektin Agent 365 Toolsille vuokralaisessasi.

Tärkeää

Tämä kertaluonteinen vuokraajakohtainen toimenpide vaatii yleisen järjestelmänvalvojan oikeudet.

  1. Lataa New-Agent365ToolsServicePrincipalProdPublic.ps1 -skripti.

  2. Avaa PowerShell järjestelmänvalvojana ja siirry skriptihakemistoon.

  3. Suorita komentosarja.

    .\New-Agent365ToolsServicePrincipalProdPublic.ps1

  4. Kirjaudu sisään Azure-tunnistetietojen avulla pyydettäessä.

Kun toimenpide on suoritettu, vuokraaja on valmis agenttien kehitykseen ja MCP-palvelimien konfigurointiin.

Määritä MCP-palvelimet

Käytä Agent 365 CLI:tä MCP-palvelimien löytämiseen, lisäämiseen ja hallintaan agentin käyttöön. Saat täydellisen listan saatavilla olevista MCP-palvelimista ja niiden ominaisuuksista MCP-palvelinluettelosta.

Löydä saatavilla olevat palvelimet

Listaa kaikki MCP-palvelimet, jotka voit konfiguroida:

a365 develop list-available

Lisää MCP-palvelimia

Lisää yksi tai useampi MCP-palvelin agentin asetuksiin:

a365 develop add-mcp-servers mcp_MailTools

Tärkeää

Tämä komento päivittää ToolingManifest.json vain projektikansiosi — se ei myönnä mitään oikeuksia blueprintille. Käyttöoikeuksien soveltaminen riippuu siitä, missä vaiheessa asennusprosessia olet:

  • Ennen alkuasennusta: Suorita a365 develop add-mcp-servers ensin, jatka sitten a365 setup all. setup all-komento sisältää MCP-käyttöoikeusvaiheen osana blueprintin luomista.
  • Kun Blueprint on jo olemassa: Globaalin ylläpitäjän täytyy suorittaa a365 setup permissions mcp erikseen. Ylläpitäjän a365.config.json tulee olla määritetty siten, että deploymentProjectPath osoittaa projektikansioon, joka sisältää päivitetyn ToolingManifest.json. Ennen kuin tämä vaihe on suoritettu, uudet MCP-palvelimen oikeudet eivät näy blueprintissä.

Listaa konfiguroidut palvelimet

Näytä tällä hetkellä konfiguroidut MCP-palvelimet:

a365 develop list-configured

Poista MCP-palvelimet

Poista MCP-palvelin konfiguraatiostasi:

a365 develop remove-mcp-servers mcp_MailTools

Täydellisen CLI-viitteen löydät osoitteesta a365-kehityskomento.

Käytä mock tooling -palvelinta testausta varten

Testauksen ja kehityksen aikana käytä Agent 365 CLI:n mock tooling -palvelinta sen sijaan, että yhdistäisit oikeisiin MCP-palvelimiin. Mock-palvelin simuloi MCP-palvelimen vuorovaikutuksia, joten voit testata agenttiasi paikallisesti ilman ulkoisia riippuvuuksia, kuten todennusta.

Valepalvelin tarjoaa seuraavat edut paikalliseen kehitykseen ja testaukseen:

  • Offline-kehitys: agentin testaaminen onnistuu ilman internet-yhteyttä tai ulkoisia riippuvuuksia.
  • Johdonmukainen testaus: Saat ennustettavia vastauksia reunatapausten testaamiseen.
  • Virheenkorjaus: Tarkastele kaikkia pyyntöjä ja vastauksia reaaliajassa
  • Nopea iterointi: Ei tarvitse odottaa ulkoisia API-kutsuja tai luoda monimutkaisia testiympäristöjä.

Käynnistä mock tooling -palvelin käyttämällä a365 develop start-mock-tooling-server -komentoa.

Opi asentamaan ja konfiguroimaan mock tooling -palvelin.

Muistiinpano

Seuraavat osiot manifestien konfigurointiin ja työkalujen integrointiin agenttiin toimivat samalla tavalla, käytätpä sitten mock-työkalujen palvelinta tai oikeita MCP-palvelimia. Aseta MCP_PLATFORM_ENDPOINT-ympäristömuuttuja osoittamaan mock tooling -palvelimelle (esimerkiksi: http://localhost:5309) tuotantopäätepisteen sijaan.

Työkalumanifestin ymmärtäminen

Kun suoritat a365 develop add-mcp-servers-koodin, CLI luo ToolingManifest.json-tiedoston, joka sisältää kaikkien MCP-palvelimien konfiguraation. Agentin suorituksenaikainen ympäristö käyttää tätä manifestia selvittääkseen, mitkä palvelimet ovat käytettävissä ja miten niihin kirjaudutaan.

Manifestin rakenne

Esimerkki ToolingManifest.json:

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

Manifestin parametrit

Jokainen MCP-palvelimen merkintä sisältää:

Parametri Description
mcpServerName MCP-palvelimen näyttönimi.
mcpServerUniqueName MCP-palvelininstanssin yksilöllinen tunniste.
vaikutusalue OAuth-vaikutusalue, joka vaaditaan MCP-palvelimen toimintojen käyttöön (esimerkiksi: McpServers.Mail.All-sähköpostitoimintoihin). Komento add-mcp-servers hakee tämän arvon MCP-palvelinluettelosta.
käyttäjäryhmä Microsoft Entra ID:n URI, joka tunnistaa kohde-API-resurssin. Komento add-mcp-servers hakee tämän arvon MCP-palvelinluettelosta.

Muistiinpano

Agent 365 CLI täyttää automaattisesti scope- ja audience-arvot, kun lisäät MCP-palvelimen. Nämä arvot ovat peräisin MCP-palvelinkatalogista ja määrittävät oikeudet, jotka vaaditaan kunkin MCP-palvelimen käyttöön.

Integroi työkalut agenttiisi

Työkalumanifestin luomisen jälkeen integroi konfiguroidut MCP-palvelimet agenttisi koodiin. Tämä osio kattaa valinnaisen tarkastusvaiheen ja vaaditut integraatiovaiheet.

Työkalupalvelimien listaaminen (valinnainen)

Vinkki

Tämä vaihe on valinnainen. Käytä työkalupalvelimen konfigurointipalvelua tarkastaaksesi saatavilla olevat työkalupalvelimet työkalumanifestista ennen niiden lisäämistä orkestroijaasi.

Hyödynnä työkalupalvelimen konfigurointipalvelua selvittääksesi, mitkä työkalupalvelimet ovat agentillesi käytettävissä työkalumanifestista. Tämän menetelmän avulla voidaan:

  • Hae kaikki konfiguroidut MCP-palvelimet ToolingManifest.json-tiedostosta.
  • Hae palvelimen metatiedot ja ominaisuudet.
  • Varmista palvelimen saatavuus ennen rekisteröintiä.

Työkalupalvelimien listaamiseen tarkoitettu menetelmä löytyy ydintyökalupaketeista:

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

Parametrit:

Parametri Tyyppi Description Odotettu arvo Pakollinen/valinnainen
agentic_app_id str Agenttisovelluksen instanssin yksilöllinen tunniste Kelvollinen agenttisovelluksen ID-merkkijono Pakollinen
auth_token str Haltijatunnus todennukseen MCP-palvelinyhdyskäytävän avulla Voimassa oleva OAuth-haltijatunnus Pakollinen

Paketti: microsoft_agents_a365.tooling

Rekisteröi työkalut orkestroijaan

Käytä kehyskohtaista laajennusmenetelmää rekisteröidäksesi kaikki MCP-palvelimet orkestrointikehykseesi:

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

Nämä menetelmät:

  • Rekisteröi kaikki työkalut konfiguroiduista MCP-palvelimista orkestroijaasi
  • Tunnistautuminen ja yhteysasetukset määritetään automaattisesti
  • Työkalut ovat heti agenttisi käytettävissä

Valitse orkestroijan laajennus

Agent 365 Tooling -moduuli tarjoaa tarkoitukseen suunnitellut laajennuspaketit eri orkestrointikehyksille:

Muistiinpano

Kun suoritat a365 develop add-mcp-servers, CLI hakee automaattisesti OAuth-alueet ja audience-tunnisteet MCP-palvelinkatalogista ja kirjoittaa ne kohteeseen ToolingManifest.json. Laajennusmetodit käyttävät näitä arvoja autentikoinnin määrittämiseen suorituksenaikaisesti — agenttikoodiin ei tarvitse tehdä manuaalista konfigurointia. Globaalin ylläpitäjän täytyy silti myöntää nämä oikeudet agentin blueprintille ennen kuin agenttisi voi käyttää niitä tuotannossa: käyttämällä a365 setup all (ensiasennus) tai a365 setup permissions mcp (jos blueprint on jo olemassa).

Katso yksityiskohtaiset toteutusesimerkit Agent 365 -esimerkeistä.

Toteutusesimerkit

Seuraavat esimerkit osoittavat, miten Agent 365 -työkalut integroidaan eri orkestrointikehyksiin.

Python ja OpenAI

Tässä esimerkissä havainnollistetaan, miten MCP-työkalut integroidaan OpenAI:n kanssa Python-sovelluksessa.

1. Tuontilausekkeiden lisääminen

Lisää tarvittavat tuonnit työkalumoduulin ja OpenAI-laajennusten käyttöä varten:

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

2. Alusta työkalupalvelut

Luo konfiguraatio- ja työkalurekisteröintipalveluiden instanssit:

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

3. Rekisteröi MCP-työkalut OpenAI-agenttiin

Käytä menetelmää add_tool_servers_to_agent rekisteröidäksesi kaikki konfiguroidut MCP-työkalut OpenAI-agenttiin. Tämä menetelmä käsittelee sekä agenttisia että ei-agenttisia autentikointiskenaarioita:

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

Menetelmäparametrit

Seuraava taulukko kuvaa parametrit, joita käytetään kohteen add_tool_servers_to_agent kanssa.

Parametri Description
agent OpenAI-agentti-instanssi, johon työkalut rekisteröidään.
agentic_app_id Agentin yksilöllinen tunniste (agenttisovelluksen tunnus).
auth Käyttäjän valtuutuskonteksti.
context Nykyisen keskusteluvuoron konteksti Agents SDK:sta. Tarjoaa käyttäjän identiteetin, keskustelun metatiedot ja todennuskontekstin työkalujen turvallista rekisteröintiä varten.
auth_token (Valinnainen) haltijatunnus ei-agenttisiin autentikointitilanteisiin.

4. Kutsu valmistelun yhteydessä

Varmista, että kutsut asetusmetodia alustuksen yhteydessä ennen agentin käynnistämistä:

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

Metodi add_tool_servers_to_agent suorittaa seuraavat toiminnot automaattisesti:

  • Lataa kaikki MCP-palvelimet ToolingManifest.json-tiedostosta.
  • Rekisteröi työkalunsa OpenAI-agentin käyttöön.
  • Konfiguroi autentikoinnin manifestin asetusten mukaan.
  • Se antaa agentillesi käytettävissä olevat työkalut, joita agentti voi käyttää.

Katso täydellisiä käyttöesimerkkejä Agent 365 Samples -tietovarastosta.

Muita tapoja päästä käsiksi Agent 365 MCP -palvelimiin

Agent 365 SDK:n lisäksi voit saada yhteyden Agent 365 MCP -palvelimiin eri kehitysympäristöissä:

  • Visual Studio Code - Yhdistä suoraan MCP-palvelimiin räätälöityihin kehitystyönkulkuihin.
  • Microsoft Copilot Studio – Integroi MCP-palvelimet keskusteluvirtoihin low-code-ympäristössä.
  • Azure AI Foundry – Käytä MCP-palvelimia, joissa on täysi SDK-tuki ja kehittyneet orkestrointiominaisuudet.

Täydellisen yleiskatsauksen saatavilla olevista MCP-palvelimista ja integraatiovaihtoehdoista näillä alustoilla löytyy Agent 365 tooling servers -yleiskatsauksesta.

Bring your own (BYO) MCP-palvelin

Bring Your Own (BYO) MCP-palvelinominaisuus mahdollistaa omien ulkoisten MCP-palvelimien rekisteröinnin Microsoft Agent 365:n avulla, jolloin niitä voidaan hallita, hyväksyä ja valvoa keskitetysti Microsoft 365 -hallintakeskuksessa. Se ohjaa nämä palvelimet Agent 365 -työkaluyhdyskäytävän kautta, jolloin ylläpitäjät saavat hallinnan hyväksyntään, käyttöoikeuksiin ja käytäntöihin, ja tietoturvatiimit voivat seurata käyttöä telemetrian avulla. Kehittäjänä voit rekisteröidä MCP-palvelimesi Agent 365 CLI:n avulla, minkä jälkeen ylläpitäjäsi tarkistaa ja hyväksyy rekisteröinnin sekä myöntää käyttöoikeudet. Hyväksyttyä palvelinta voidaan käyttää tuetuissa asiakastyökaluissa, ja jatkuva seuranta varmistaa vaatimustenmukaisuuden ja näkyvyyden kaikissa integraatioissa.

Täydelliset ohjeet löydät kohdasta Bring your own (BYO) MCP-palvelin.

Agentin testaaminen

Kun olet integroinut MCP-työkalut agenttiisi, testaa työkalukutsut varmistaaksesi, että ne toimivat oikein ja eri skenaarioissa. Määritä ympäristö testausoppaan tietojen avulla. Keskity ensisijaisesti Työkalukutsujen testaaminen -osioon varmistaaksesi, että MCP-työkalusi toimivat odotetusti. Tutustu myös mock tooling server -palvelimeen, jonka avulla voit testata MCP-palvelimen yhteyttä ja työkalukutsuja ilman tunnistautumista.

Lisää näkyvyys

Lisää agentillesi monitorointi- ja jäljitettävyysominaisuudet, jotta voit seurata ja jäljittää agenttisi MCP-työkalukutsuja. Lisäämällä monitorointi- ja jäljitettävyysominaisuuksia voit seurata suorituskykyä, ratkaista ongelmia ja analysoida työkalujen käyttöä. Lue lisää jäljityksen ja seurannan toteuttamisesta.

Vianmääritys

Tässä osiossa luetellaan yleisiä ongelmia, kun konfiguroidaan ja käytetään MCP-palvelimia ja työkaluja.

Vinkki

Agent 365:n vianmääritysopas sisältää yleisluontoisia vianmääritykseen liittyviä suosituksia, parhaita käytäntöjä sekä linkkejä vianmääritykseen liittyvään sisältöön Agent 365:n kehityksen elinkaaren kaikissa vaiheissa.

MCP-palvelin- ja työkaluongelmat

Oireet:

  • Työkalukutsujen epäonnistumiset.
  • "MCP Serveriä ei löytynyt" -virheet.
  • Käyttöoikeusvirheitä työkaluja kutsuttaessa.

Juurisyy:

  • MCP-palvelin ei ole konfiguroitu.
  • Käyttöoikeuksia puuttuu.
  • Palvelun päänimeä ei ole määritetty.
  • Sekaannusta mock- ja tuotantopalvelimien välillä.

Ratkaisut: Kokeile seuraavia ratkaisuja ongelman ratkaisemiseksi.

  • Varmista, että MCP-palvelimet on määritetty

    Luettele määritetyt palvelimet ja lisää puuttuvat.

    # List configured servers
a365 develop list-configured

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

  • Tarkista, että Palvelun päänimi on olemassa

    Varmista, että vaadittu Palvelun päänimi on luotu työkalujen käyttöä varten.

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

  • Varhaisessa kehityksessä ja testauksessa käytä mock-palvelimia

    Käytä mallityökalupalvelinta varhaiseen paikalliseen kehitykseen ja testaukseen, jos haluat testata agenttisi muita osia ilman tuotantotyökalukomponentteja.

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

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

    Lue lisää mallityökalupalvelimesta

  • Tarkista hallintakeskuksen käyttöoikeudet

    Varmista, että agentillasi on tarvittavat MCP-oikeudet.

    • Varmista, että agenttisi blueprint API -oikeudet Azure-portaalissa kattavat kaikki MCP-palvelimen käyttöoikeudet.

    Vahvistus:

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