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.

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.

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

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.

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ää:

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)

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)

// Use McpToolServerConfigurationService.listToolServers
const { McpToolServerConfigurationService } = require('@microsoft/agents-a365-tooling');

const configService = new McpToolServerConfigurationService();
const toolServers = await configService.listToolServers(agentUserId, authToken);

// Use IMcpToolServerConfigurationService.ListToolServersAsync
using Microsoft.Agents.A365.Tooling.Services;

var configService = serviceProvider.GetRequiredService<IMcpToolServerConfigurationService>();
var toolServers = await configService.ListToolServersAsync(agentInstanceId, authToken);

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:

Katso yksityiskohtaiset toteutusesimerkit Agent 365 -esimerkeistä.

Toteutusesimerkit

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

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

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

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

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

import { McpToolServerConfigurationService } from '@microsoft/agents-a365-tooling';
import { McpToolRegistrationService } from '@microsoft/agents-a365-tooling-extensions-langchain';

const toolService = new McpToolRegistrationService();

// Get MCP Tools
try {
  const agent = await toolService.addToolServersToAgent(
    agent,
    process.env.AGENTIC_USER_ID || '',
    authorization,
    turnContext,
    process.env.MCP_AUTH_TOKEN || "",
  );
} catch (error) {
  console.error('Error adding MCP tool servers:', error);
}

using Microsoft.Agents.A365.Tooling;
using Microsoft.Agents.A365.Tooling.Extensions.SemanticKernel;

builder.Services.AddSingleton<IMcpToolRegistrationService, McpToolRegistrationService>();
builder.Services.AddSingleton<IMcpToolServerConfigurationService, McpToolServerConfigurationService>();

private readonly IMcpToolRegistrationService _toolsService;

// Simplified call (authentication configured automatically)
await toolService.AddToolServersToAgentAsync(kernel, userAuthorization, turnContext);

// Or with explicit authentication parameters:
if (useAgenticAuth)
{
    await toolService.AddToolServersToAgentAsync(kernel, userAuthorization, authHandlerName, turnContext);
}
else
{
    await toolService.AddToolServersToAgentAsync(kernel, userAuthorization, authHandlerName, turnContext, authToken);
}

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.

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