Dodawanie i zarządzanie narzędziami

Moduł Narzędzi pomaga deweloperom odkrywać, konfigurować i integrować serwery Protokół kontekstu modelu(MCP) z przepływami pracy agentów AI. Serwery MCP udostępniają zewnętrzne możliwości jako narzędzia, które agenci AI mogą wywoływać. Aby zapoznać się z przeglądem dostępnych serwerów narzędzi, zobacz Serwery narzędzi Agent 365.

Demonstracja przepływu żądań i odpowiedzi

Omówienie

Integracja narzędzi Agent 365 przebiega według następującego procesu:

  1. Konfiguracja serwerów MCP – Użyj CLI Agent 365, aby odkryć i dodać serwery MCP
  2. Wygeneruj manifest – CLI tworzy ToolingManifest.json w folderze projektu z konfiguracjami serwerów.
  3. Zastosuj uprawnienia do Blueprintu - Administrator globalny przyznaje uprawnienia OAuth2 Blueprintowi agenta poprzez uruchomienie a365 setup all (przy pierwszej konfiguracji) lub a365 setup permissions mcp (jeśli Blueprint już istnieje). Tak czy inaczej, polecenie odczytuje ToolingManifest.json i wymaga zgody administratora. Ten krok zawsze wykonuje się osobno, niezależnie od dodawania serwerów do manifestu.
  4. Zintegruj z kodem – Załaduj manifest i zarejestruj narzędzia w orchestratorze.
  5. Wywołaj narzędzia - Agent wywołuje narzędzia w trakcie realizacji operacji.

Wymagania wstępne

Przed skonfigurowaniem serwerów MCP upewnij się, że masz:

  • Agent 365 CLI zainstalowany i skonfigurowany
  • .NET 8.0 SDK lub nowszy - Pobierz
  • Uprawnienia administratora globalnego w Twoim dzierżawcy Microsoft 365

Konfigurowanie tożsamości agenta

Jeśli korzystasz z uwierzytelniania agentowego, ukończ proces rejestracji agenta, aby utworzyć tożsamość agenta przed konfiguracją serwerów MCP. Proces ten tworzy identyfikator agenta Entra oraz konto agenta, które umożliwiają agentowi uwierzytelnianie i dostęp do narzędzi MCP.

Ustawienia uwierzytelniania OBO

Jeśli używasz uwierzytelniania On-Behalf-Of (OBO) zamiast uwierzytelniania agentowego, Twój agent może uzyskać dostęp do narzędzi MCP, korzystając z delegowanych uprawnień użytkownika, bez tożsamości użytkownika agenta. W przepływie OBO agent wykorzystuje delegowany token użytkownika, aby wykonać działania w jego imieniu.

Aby dowiedzieć się, jak działa przepływ OBO, zobacz Przepływy uwierzytelniania. Pełny przykład implementacji znajdziesz w przykładzie autoryzacji OBO w Zestaw SDK agentów usługi Microsoft 365.

Skonfiguruj jednostkę usługi

Uruchom ten jednorazowy skrypt konfiguracyjny, aby utworzyć zasadę usługową dla narzędzi Agent 365 w swoim dzierżawcy.

Ważne

Ta jednorazowa operacja w dzierżawie wymaga uprawnień globalnego administratora.

  1. Pobierz skrypt New-Agent365ToolsServicePrincipalProdPublic.ps1.

  2. Otwórz PowerShell jako administrator i przejdź do katalogu skryptów.

  3. Uruchom skrypt.

    .\New-Agent365ToolsServicePrincipalProdPublic.ps1

  4. Zaloguj się, używając poświadczeń platformy Azure, gdy pojawi się monit.

Po zakończeniu, tenant jest gotowy do rozwoju agentów i konfiguracji serwerów MCP.

Skonfiguruj serwery MCP

Użyj Agent 365 CLI, aby wykryć, dodać i zarządzać serwerami MCP dla swojego agenta. Pełną listę dostępnych serwerów MCP i ich możliwości można znaleźć w katalogu serwerów MCP.

Odkryj dostępne serwery

Wyświetl wszystkie serwery MCP, które możesz skonfigurować:

a365 develop list-available

Dodaj serwery MCP

Dodaj jeden lub kilka serwerów MCP do konfiguracji agenta:

a365 develop add-mcp-servers mcp_MailTools

Ważne

To polecenie aktualizuje tylko ToolingManifest.json w folderze projektu — nie przyznaje żadnych uprawnień do blueprinta. Sposób stosowania uprawnień zależy od tego, na jakim etapie procesu konfiguracji jesteś:

  • Przed wstępną konfiguracją: Najpierw uruchom a365 develop add-mcp-servers, następnie kontynuuj z a365 setup all. Polecenie setup all obejmuje etap przyznawania uprawnień MCP jako część tworzenia blueprinta.
  • Po zakończeniu planu: Administrator globalny musi działać a365 setup permissions mcp osobno. Administratorowi muszą a365.config.jsondeploymentProjectPath wskazywać na folder projektu zawierający zaktualizowane ToolingManifest.json. Dopóki ten krok nie zostanie ukończony, nowe uprawnienia serwera MCP nie są widoczne w blueprintie.

Wyświetl skonfigurowane serwery

Wyświetl aktualnie skonfigurowane serwery MCP:

a365 develop list-configured

Usuń serwery MCP

Usuń serwer MCP z konfiguracji:

a365 develop remove-mcp-servers mcp_MailTools

Aby uzyskać pełną dokumentację CLI, zobacz polecenie a365 develop.

Użyj serwera mock tooling do testowania

Do testowania i rozwoju używaj mock tooling servera Agent 365 CLI zamiast łączyć się z rzeczywistymi serwerami MCP. Serwer mock symuluje interakcje z serwerem MCP, umożliwiając lokalne testowanie agenta bez konieczności korzystania z zewnętrznych zależności, takich jak uwierzytelnianie.

Serwer mockowy oferuje następujące korzyści dla lokalnego rozwoju i testowania:

  • Rozwój offline: Przetestuj swojego agenta bez połączenia z internetem i bez zewnętrznych zależności.
  • Spójne testowanie: Otrzymuj przewidywalne odpowiedzi do testowania przypadków brzegowych.
  • Debugowanie: Przeglądaj wszystkie żądania i odpowiedzi w czasie rzeczywistym
  • Szybka iteracja: Brak konieczności oczekiwania na zewnętrzne wywołania API czy tworzenia skomplikowanych środowisk testowych.

Uruchom serwer narzędzi mock, używając polecenia a365 develop start-mock-tooling-server.

Dowiedz się, jak uruchamiać i konfigurować serwer mock tooling.

Notatka

Poniższe sekcje dotyczące konfiguracji manifestów i integracji narzędzi z agentem działają tak samo, niezależnie od tego, czy korzystasz z mock tooling servera, czy faktycznych serwerów MCP. Ustaw zmienną środowiskową MCP_PLATFORM_ENDPOINT tak, aby wskazywała na serwer narzędzi mock (na przykład: http://localhost:5309) zamiast na punkt końcowy produkcyjny.

Manifest narzędziowy – omówienie

Po uruchomieniu a365 develop add-mcp-servers, CLI tworzy plik ToolingManifest.json zawierający konfigurację wszystkich serwerów MCP. Środowisko uruchomieniowe agenta wykorzystuje ten manifest, aby zrozumieć, które serwery są dostępne i jak się z nimi uwierzytelnić.

Struktura manifestu

Przykład ToolingManifest.json:

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

Parametry manifestu

Każdy wpis serwera MCP zawiera:

Parametr Podpis
mcpServerName Nazwa wyświetlana serwera MCP.
mcpServerUniqueName Unikalny identyfikator instancji serwera MCP.
zakres Zakres OAuth wymagany do dostępu do możliwości serwera MCP (na przykład: McpServers.Mail.All do operacji pocztowych). Polecenie add-mcp-servers pobiera tę wartość z katalogu serwerów MCP.
odbiorcy Microsoft Entra ID URI, który identyfikuje docelowy zasób API. Polecenie add-mcp-servers pobiera tę wartość z katalogu serwerów MCP.

Notatka

Agent 365 CLI automatycznie uzupełnia wartości scope i audience podczas dodawania serwera MCP. Te wartości pochodzą z katalogu serwerów MCP i definiują uprawnienia wymagane do dostępu do każdego serwera MCP.

Integruj narzędzia ze swoim agentem

Po wygenerowaniu manifestu narzędzi integruj skonfigurowane serwery MCP z kodem agenta. Ta sekcja obejmuje opcjonalny etap inspekcji oraz wymagane kroki integracji.

Lista serwerów narzędzi (opcjonalnie)

Wskazówka

To krok jest opcjonalny. Użyj usługi konfiguracyjnej serwera narzędzi, aby sprawdzić dostępne serwery narzędzi z manifestu narzędzi przed dodaniem ich do swojego orchestratora.

Użyj usługi konfiguracji serwera narzędzi, aby dowiedzieć się, które serwery narzędzi są dostępne dla Twojego agenta na podstawie manifestu narzędzi. Ta metoda umożliwia:

  • Pobierz listę wszystkich skonfigurowanych serwerów MCP z pliku ToolingManifest.json.
  • Pobierz metadane i możliwości serwera.
  • Sprawdź dostępność serwera przed rejestracją.

Metoda wyświetlania serwerów MCP jest dostępna w podstawowych pakietach narzędziowych:

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

Parametry:

Parametr Typ Podpis Oczckiwana wartość Wymagane/Opcjonalne
agentic_app_id str Unikalny identyfikator instancji aplikacji agenta Prawidłowy identyfikator aplikacji agenta (ciąg znaków) Wymagania
auth_token str Token typu bearer do uwierzytelniania za pomocą bramy serwera MCP Ważny token elementu nośnego OAuth Wymagania

Pakiet: microsoft_agents_a365.tooling

Zarejestruj narzędzia w swoim orkestratorze

Użyj metody rozszerzenia specyficznej dla frameworka, aby zarejestrować wszystkie serwery MCP w swoim frameworku orkiestracji:

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

Te metody:

  • Zarejestruj wszystkie narzędzia z skonfigurowanych serwerów MCP w swoim orkestratorze
  • Automatycznie konfiguruj uwierzytelnianie i szczegóły połączenia
  • Narzędzia są od razu dostępne do wywołania przez agenta

Wybierz rozszerzenie orkiestratora

Moduł narzędzi Agent 365 oferuje dedykowane pakiety rozszerzeń dla różnych frameworków orkiestracji:

Notatka

Gdy uruchomisz a365 develop add-mcp-servers, CLI automatycznie pobierze zakresy OAuth i identyfikatory odbiorców z katalogu serwera MCP i zapisze je do ToolingManifest.json. Metody rozszerzenia wykorzystują te wartości do konfiguracji uwierzytelniania w czasie działania — nie jest wymagana ręczna konfiguracja w kodzie agenta. Jednak Global Administrator musi nadal przyznać te uprawnienia blueprintowi agenta, zanim Twój agent będzie mógł użyć ich w produkcji: poprzez a365 setup all (przy pierwszej konfiguracji) lub a365 setup permissions mcp (jeśli blueprint już istnieje).

Aby uzyskać szczegółowe przykłady implementacji, zobacz Przykłady Agent 365.

Przykłady implementacji

Poniższe przykłady pokazują, jak zintegrować Agent 365 Tooling z różnymi frameworkami orkiestracji.

Python z OpenAI

Ten przykład pokazuje, jak zintegrować narzędzia MCP z OpenAI w aplikacji napisanej w Pythonie.

1. Dodaj instrukcję akcji importu

Dodaj wymagane importy, aby uzyskać dostęp do modułu Tooling i rozszerzeń OpenAI:

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

2. Inicjalizacja usług narzędziowych

Utwórz instancje usług do konfiguracji oraz rejestracji narzędzi:

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

3. Zarejestruj narzędzia MCP dla agenta AI OpenAI

Skorzystaj z metody add_tool_servers_to_agent, aby zarejestrować wszystkie skonfigurowane narzędzia MCP dla swojego agenta AI OpenAI. Ta metoda obsługuje zarówno scenariusze uwierzytelniania agentycznego, jak i nieagentycznego:

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

Parametry metody

W poniższej tabeli opisano parametry, które należy uwzględnić z add_tool_servers_to_agent.

Parametr Podpis
agent Instancja agenta AI OpenAI, z którą rejestruje się narzędzia.
agentic_app_id Unikalny identyfikator agenta (agentic app ID).
auth Kontekst autoryzacji użytkownika.
context Kontekst bieżącej tury rozmowy z Agents SDK. Udostępnia tożsamość użytkownika, metadane rozmowy oraz kontekst uwierzytelniania dla bezpiecznej rejestracji narzędzi.
auth_token (Opcjonalnie) token typu bearer dla scenariuszy uwierzytelniania nieagentowego.

4. Połączenie podczas inicjalizacji

Upewnij się, że podczas inicjalizacji wywołujesz metodę konfiguracji przed uruchomieniem agenta:

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

Metoda add_tool_servers_to_agent automatycznie:

  • Ładuje wszystkie serwery MCP z pliku ToolingManifest.json.
  • Rejestruje ich narzędzia w agencie OpenAI.
  • Konfiguruje uwierzytelnianie na podstawie konfiguracji pliku manifestu.
  • Udostępnia narzędzia agentowi do użycia.

Aby zobaczyć pełne działające przykłady, odwiedź repozytorium Agent 365 Samples.

Inne sposoby dostępu do serwerów MCP Agent 365

Oprócz Agent 365 SDK, możesz uzyskać dostęp do serwerów Agent 365 MCP poprzez inne środowiska deweloperskie:

  • Visual Studio Code – Bezpośrednie połączenie z serwerami MCP dla niestandardowych przepływów pracy programistycznej.
  • Microsoft Copilot Studio – Integracja serwerów MCP z przepływami konwersacyjnymi przy użyciu środowiska niskokodowego.
  • Azure AI Foundry – Korzystaj z serwerów MCP z pełnym wsparciem SDK i zaawansowanymi możliwościami orkiestracji.

Aby uzyskać pełny przegląd dostępnych serwerów MCP oraz opcji integracji na tych platformach, zobacz przegląd serwerów narzędzi Agent 365.

Weź własny (BYO) serwer MCP

Funkcja Bring Your Own (BYO) MCP server umożliwia rejestrację własnych zewnętrznych serwerów MCP w Microsoft Agent 365, umożliwiając ich scentralizowane zarządzanie, zatwierdzanie i monitorowanie w centrum administracyjnym Microsoft 365. Serwery te są routowane przez bramę narzędziową Agent 365, co daje administratorom kontrolę nad zatwierdzaniem, dostępem i politykami, a zespołom ds. bezpieczeństwa umożliwia monitorowanie wykorzystania poprzez telemetrię. Jako deweloper możesz zarejestrować swój serwer MCP za pomocą Agent 365 CLI, a następnie administrator dokonuje weryfikacji i zatwierdzenia rejestracji oraz przyznaje uprawnienia. Zatwierdzony serwer może być następnie używany w obsługiwanych aplikacjach klienckich, a ciągły monitoring zapewnia zgodność i widoczność we wszystkich integracjach.

Aby uzyskać pełne instrukcje, zobacz Bring Your Own (BYO) MCP server.

Testowanie własnego agenta

Po zintegrowaniu narzędzi MCP z agentem, przetestuj wywołania narzędzi, aby upewnić się, że działają prawidłowo i obsługują różne scenariusze. Skorzystaj z przewodnika testowego, aby skonfigurować środowisko. Następnie skoncentruj się przede wszystkim na sekcji Test tool invocations, aby zweryfikować, czy narzędzia MCP działają zgodnie z oczekiwaniami. Sprawdź także serwer narzędzi mock, aby przetestować połączenie z serwerem MCP i wywołania narzędzi bez obsługi uwierzytelniania.

Dodaj obserwowalność

Dodaj obserwowalność do swojego agenta, aby monitorować i śledzić wywołania narzędzi MCP przez agenta. Dodając obserwowalność, możesz śledzić wydajność, debugować problemy i rozumieć wzorce wykorzystania narzędzi. Dowiedz się więcej o wdrażaniu śledzenia i monitoringu.

Rozwiązywanie problemów

Ta sekcja wymienia typowe problemy podczas konfiguracji i korzystania z serwerów oraz narzędzi MCP.

Wskazówka

Przewodnik po rozwiązywaniu problemów Agent 365 zawiera wysokopoziomowe zalecenia dotyczące rozwiązywania problemów, najlepsze praktyki oraz odnośniki do treści dotyczących rozwiązywania problemów dla każdego etapu cyklu rozwoju Agent 365.

Problemy z serwerem MCP i narzędziami

Objawy:

  • Niepowodzenia w wywoływaniu narzędzi.
  • Błędy „Nie znaleziono serwera MCP”.
  • Błędy odmowy dostępu podczas wywoływania narzędzi.

Główna przyczyna:

  • Serwer MCP nie jest skonfigurowany.
  • Brak uprawnień.
  • Jednostka usługi nie jest ustawiona.
  • Zamieszanie między serwerami mock a produkcyjnymi.

Rozwiązania: Spróbuj poniższych rozwiązań, aby usunąć problem.

  • Zweryfikuj, czy serwery MCP są skonfigurowane

    Wypisz skonfigurowane serwery i dodaj brakujące.

    # List configured servers
a365 develop list-configured

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

  • Sprawdź, czy istnieje obiekt usługi (service principal)

    Upewnij się, że wymagany obiekt usługi (service principal) został utworzony na potrzeby narzędzi.

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

  • Do wczesnego rozwoju i testów używaj serwerów typu mock

    Użyj serwera narzędzi testowych (mock tooling server) do wczesnego lokalnego tworzenia i testowania, jeśli chcesz przetestować resztę swojego agenta bez produkcyjnych narzędzi.

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

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

    Dowiedz się więcej o serwerze narzędzi testowych (mock tooling server).

  • Weryfikacja uprawnień w centrum administracyjnym

    Upewnij się, że Twój agent ma niezbędne uprawnienia MCP.

    • Zweryfikuj, czy uprawnienia API Blueprint agenta w Azure Portal obejmują wszystkie uprawnienia serwera MCP.

    Weryfikacja:

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