Dela via

Lägga till och hantera verktyg

Viktigt

Du måste vara en del av förhandsversionen av Frontier för att få tidig åtkomst till Microsoft Agent 365. Frontier ansluter dig direkt till Microsofts senaste AI-innovationer. Förhandsversioner av Gräns omfattas av de befintliga förhandsversionsvillkoren för dina kundavtal. Eftersom dessa funktioner fortfarande är under utveckling kan deras tillgänglighet och funktioner ändras över tid.

Med verktygsmodulen kan utvecklare identifiera, konfigurera och integrera MCP-servrar (Model Context Protocol) i AI-agentarbetsflöden. MCP-servrar exponerar externa funktioner som verktyg som AI-agenter kan anropa. En översikt över tillgängliga verktygsservrar finns i Agent 365-verktygsservrar.

Visar flödet för begäran och svar

Översikt

Integreringen av agent 365-verktyg följer ett fyrastegsarbetsflöde:

  1. Konfigurera MCP-servrar – Använd Agent 365 CLI för att identifiera och lägga till MCP-servrar
  2. Generera manifest – CLI skapar ToolingManifest.json med serverkonfigurationer
  3. Integrera i kod – Läsa in manifest- och registerverktyg med din orkestrerare
  4. Anropa verktyg – Agent anropar verktyg under körning för att utföra åtgärder

Förutsättningar

Kontrollera att du har följande innan du konfigurerar MCP-servrar:

  • Agent 365 CLI installerat och konfigurerat
  • .NET 8.0 SDK eller senare – Ladda ned
  • Globala administratörsbehörigheter i din Microsoft 365-klientorganisation

Konfiguration av agentidentitet

Om du använder agentbaserad autentisering slutför du agentregistreringsprocessen för att skapa din agentidentitet innan du konfigurerar MCP-servrar. Detta skapar det agentiska app-ID och den agentiska användare som gör det möjligt för din agent att autentisera och komma åt MCP-verktyg.

Konfigurera huvudkonto för tjänsten

Kör det här engångskonfigurationsskriptet för att skapa tjänstens huvudnamn för Agent 365-verktyg i klientorganisationen.

Viktigt

Det här är en ENGÅNGSåtgärd per klientorganisation som kräver global administratörsbehörighet.

  1. Ladda ned skriptet New-Agent365ToolsServicePrincipalProdPublic.ps1

  2. Öppna PowerShell som administratör och gå till skriptkatalogen

  3. Kör skriptet:

    .\New-Agent365ToolsServicePrincipalProdPublic.ps1

  4. Om du uppmanas, logga in med dina autentiseringsuppgifterna för .

När du är klar är din klientorganisation redo för agentutveckling och MCP-serverkonfiguration.

Konfigurera DHCP-server

Använd Agent 365 CLI för att identifiera, lägga till och hantera MCP-servrar för din agent. En fullständig lista över tillgängliga MCP-servrar och deras funktioner finns i MCP-serverkatalogen.

Identifiera tillgängliga servrar

Visa en lista över alla MCP-servrar som kan konfigureras:

a365 develop list-available

Lägga till MCP-servrar

Lägg till en eller flera MCP-servrar i agentkonfigurationen:

a365 develop add-mcp-servers mcp_MailTools

Lista konfigurerade servrar

Visa för närvarande konfigurerade MCP-servrar:

a365 develop list-configured

Ta bort MCP-servrar

Ta bort en MCP-server från konfigurationen:

a365 develop remove-mcp-servers mcp_MailTools

Fullständig CLI-referens finns i kommandot a365 develop.

Förstå verktygsmanifestet

När du kör a365 develop add-mcp-serversgenererar CLI en ToolingManifest.json fil som innehåller konfiguration för alla MCP-servrar. Agentkörningen använder det här manifestet för att förstå vilka servrar som är tillgängliga och hur de ska autentiseras med dem.

Manifeststruktur

Exempel:

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

Manifestparametrar

Varje MCP-serverpost innehåller:

Parametrar Beskrivningar
mcpServerName Tillgångens visningsnamn.
mcpServerUniqueName Den unika identifieraren för MCP-serverinstansen
omfattning OAuth-omfånget som krävs för åtkomst till MCP-serverns funktioner (till exempel för McpServers.Mail.All e-poståtgärder). Det här värdet hämtas från MCP-serverkatalogen add-mcp-servers när du kör kommandot.
publik Den Microsoft Entra-ID-URI som identifierar mål-API-resursen. Det här värdet hämtas också från MCP-serverkatalogen.

Obs

Värdena scope och audience fylls automatiskt i av Agent 365 CLI när du lägger till en MCP-server. Dessa värden kommer från MCP-serverkatalogen och definierar de behörigheter som krävs för att få åtkomst till varje MCP-server.

Integrera verktyg i din agent

När du har genererat verktygsmanifestet integrerar du de konfigurerade MCP-servrarna i din agentkod. Det här avsnittet beskriver det valfria inspektionssteget och de nödvändiga integreringsstegen.

Listverktygsservrar (valfritt)

Tips

Steget är valfritt. Använd konfigurationstjänsten för verktygsservern för att inspektera tillgängliga verktygsservrar från verktygsmanifestet innan du lägger till dem i orkestratorn.

Använd konfigurationstjänsten för verktygsservern för att identifiera vilka verktygsservrar som är tillgängliga för din agent från verktygsmanifestet. Med den här metoden kan du:

  • Fråga alla konfigurerade MCP-servrar från ToolingManifest.json
  • Hämta servermetadata och funktioner
  • Kontrollera serverns tillgänglighet före registreringen

Metoden för att lista verktygsservrar är tillgänglig i de viktigaste verktygspaketen:

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

**Parametrar:

Parameter Typ Description Förväntat värde Krävs/valfritt
agentic_app_id str Den unika identifieraren för agentprograminstansen Giltig agentprogram-ID-sträng Obligatoriskt
auth_token str Ägartoken för autentisering med MCP-servergatewayen Giltig OAuth-ägartoken Obligatoriskt

Paket: microsoft-agents-a365-tooling

Registrera verktyg med din orkestrerare

Använd den ramverksspecifika tilläggsmetoden för att registrera alla MCP-servrar med ditt orkestreringsramverk:

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

Följande metoder:

  • Registrera alla verktyg från konfigurerade MCP-servrar med din orchestrator
  • Konfigurera autentiserings- och anslutningsinformation automatiskt
  • Gör verktyg omedelbart tillgängliga för agenten att anropa

Välj ditt orchestrator-tillägg

Agent 365 Tooling-modulen tillhandahåller dedikerade tilläggspaket för olika orkestreringsramverk:

  • microsoft-agents-a365-tooling: Funktioner för kärnverktyg
  • microsoft-agents-a365-tooling-extensions-agentframework: Agent Framework-integrering
  • microsoft-agents-a365-tooling-extensions-azureaifoundry: Azure AI Foundry-integrering
  • microsoft-agents-a365-tooling-extensions-openai: OpenAI-integrering
  • microsoft-agents-a365-tooling-extensions-semantickernel: Semantic Kernel-integrering

Obs

Autentisering konfigureras automatiskt av Agent 365 CLI när du kör a365 develop add-mcp-servers. OAuth-omfången och målgruppsvärdena hämtas från MCP-serverkatalogen ToolingManifest.jsonoch ingår i . Tilläggsmetoderna använder automatiskt dessa värden för att konfigurera autentisering – ingen manuell konfiguration krävs.

Detaljerade implementeringsexempel finns i Agent 365-exempel.

Implementeringsexempel

Följande exempel visar hur du integrerar Agent 365-verktyg med olika orkestreringsramverk.

Python med OpenAI

Det här exemplet visar hur du integrerar MCP-verktyg med OpenAI i ett Python-program.

Lägg till importutdrag.

Lägg till nödvändiga importer för att få åtkomst till verktygsmodulen och OpenAI-tilläggen:

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

2. Initiera verktygstjänster

Skapa instanser av konfigurations- och verktygsregistreringstjänsterna:

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

3. Registrera MCP-verktyg med OpenAI-agenten

Använd metoden add_tool_servers_to_agent för att registrera alla konfigurerade MCP-verktyg med din OpenAI-agent. Den här metoden hanterar både scenarier för agentisk och icke-agentisk autentisering:

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

Metodparametrar

Följande tabell beskriver parametrarna.

Parametrar Beskrivningar
agent OpenAI-agentinstansen att registrera verktyg med.
agentic_app_id Den unika identifieraren för agenten (agentiskt app-ID).
auth Auktoriseringskontexten för användaren.
context Den aktuella konversationen omvandlar kontexten från Agents SDK. Tillhandahåller användaridentitet, konversationsmetadata och autentiseringskontext för säker verktygsregistrering.
auth_token (Valfritt) Ägartoken för scenarier med icke-agentisk autentisering.

4. Ring under initieringen

Kontrollera att du anropar konfigurationsmetoden under initieringen innan du kör agenten:

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

Metoden add_tool_servers_to_agent :

  • Läser in alla MCP-servrar från ToolingManifest.json
  • Registrerar sina verktyg med OpenAI-agenten
  • Konfigurerar autentisering baserat på manifestkonfigurationen
  • Gör verktygen tillgängliga för agenten att anropa

Fullständiga arbetsexempel finns i lagringsplatsen Agent 365-exempel.

Testa och övervaka

Testa din agent

När du har integrerat MCP-verktyg i din agent testar du verktygsanropen för att säkerställa att de fungerar korrekt och hanterar olika scenarier. Följ testguidenför att konfigurera din miljö och fokusera sedan främst på avsnittet Testverktygsanrop för att verifiera att mcp-verktygen fungerar som förväntat.

Lägg till observerbarhet

Lägg till observerbarhet för din agent för att övervaka och spåra agentens MCP-verktygsanrop, lägga till observerbarhetsfunktioner för att spåra prestanda, felsöka problem och förstå användningsmönster för verktyg. Läs mer om att implementera spårning och övervakning

  • Last updated on