Udostępnij przez

Dodawanie narzędzi i zarządzanie nimi

Ważne

Aby uzyskać wczesny dostęp do programu Microsoft Agent 365, musisz być częścią programu Frontier w wersji zapoznawczej. Usługa Frontier łączy Cię bezpośrednio z najnowszymi innowacjami firmy Microsoft dotyczącymi sztucznej inteligencji. Wersje zapoznawcze platformy Frontier podlegają istniejącym warunkom obowiązywania wersji zapoznawczej umów klienta. Ponieważ te funkcje są nadal opracowywane, ich dostępność i możliwości mogą ulec zmianie w miarę upływu czasu.

Moduł Tooling umożliwia deweloperom odnajdywanie, konfigurowanie i integrowanie serwerów protokołu MCP (Model Context Protocol) z przepływami pracy agenta sztucznej inteligencji. Serwery MCP uwidaczniają możliwości zewnętrzne jako narzędzia, które mogą wywoływać agenci sztucznej inteligencji. Aby zapoznać się z omówieniem dostępnych serwerów narzędzi, zobacz Agent 365 tooling servers (Serwery narzędzi agenta 365).

Demonstruje przepływ żądania i odpowiedzi

Omówienie

Integracja narzędzi agenta 365 jest zgodna z czteroetapowym przepływem pracy:

  1. Konfigurowanie serwerów MCP — używanie interfejsu wiersza polecenia agenta 365 do odnajdywania i dodawania serwerów MCP
  2. Generowanie manifestu — interfejs wiersza polecenia tworzy ToolingManifest.json z konfiguracjami serwera
  3. Integracja z kodem — ładowanie manifestu i rejestrowanie narzędzi za pomocą orkiestratora
  4. Wywoływanie narzędzi — agent wywołuje narzędzia podczas wykonywania w celu wykonywania operacji

Wymagania wstępne

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

Konfiguracja tożsamości agenta

Jeśli używasz uwierzytelniania agenta, ukończ proces rejestracji agenta, aby utworzyć tożsamość agenta przed skonfigurowaniem serwerów MCP. Spowoduje to utworzenie identyfikatora aplikacji agenta i użytkownika agenta, który umożliwia agentowi uwierzytelnianie i uzyskiwanie dostępu do narzędzi MCP.

Skonfiguruj jednostkę usługi

Uruchom ten skrypt konfiguracji JEDNORAZOWY, aby utworzyć jednostkę usługi dla narzędzi agenta 365 w dzierżawie.

Ważne

Jest to operacja JEDNORAZOWa na dzierżawę, która wymaga uprawnień administratora globalnego.

  1. Pobierz skrypt New-Agent365ToolsServicePrincipalProdPublic.ps1

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

  3. Uruchom skrypt:

    .\New-Agent365ToolsServicePrincipalProdPublic.ps1

  4. Jeśli zostaniesz o to poproszony, zaloguj się za pomocą swoich poświadczeń w .

Po zakończeniu dzierżawa jest gotowa do opracowywania agentów i konfiguracji serwera MCP.

Konfigurowanie serwerów MCP

Użyj interfejsu wiersza polecenia agenta 365, aby odnajdywać i dodawać serwery MCP dla agenta oraz zarządzać nimi. Aby uzyskać pełną listę dostępnych serwerów MCP i ich możliwości, zobacz katalog serwerów MCP.

Odnajdywanie dostępnych serwerów

Wyświetl listę wszystkich serwerów MCP, które można skonfigurować:

a365 develop list-available

Dodawanie serwerów MCP

Dodaj co najmniej jeden serwer MCP do konfiguracji agenta:

a365 develop add-mcp-servers mcp_MailTools

Lista skonfigurowanych serwerów

Wyświetl obecnie skonfigurowane serwery MCP:

a365 develop list-configured

Usuwanie serwerów MCP

Usuń serwer MCP z konfiguracji:

a365 develop remove-mcp-servers mcp_MailTools

Aby uzyskać pełną dokumentację interfejsu wiersza polecenia, zobacz polecenie a365 develop.

Omówienie manifestu narzędzi

Po uruchomieniu a365 develop add-mcp-serversinterfejs wiersza polecenia generuje plik zawierający konfigurację ToolingManifest.json dla wszystkich serwerów MCP. Środowisko uruchomieniowe agenta używa tego manifestu, aby zrozumieć, które serwery są dostępne i jak je uwierzytelniać.

Struktura manifestu

Przykład:

{
  "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:

Parametry Opisy
mcpServerName Nazwa wyświetlana zasobu.
mcpServerUniqueName Unikatowy identyfikator wystąpienia serwera MCP
zakres Zakres protokołu OAuth wymagany do uzyskania dostępu do możliwości serwera MCP (na przykład: McpServers.Mail.All na potrzeby operacji poczty). Ta wartość jest pobierana z katalogu serwerów MCP podczas uruchamiania add-mcp-servers polecenia.
audiencja Identyfikator URI identyfikatora entra firmy Microsoft identyfikujący docelowy zasób interfejsu API. Ta wartość jest również pobierana z katalogu serwerów MCP.

Notatka

Wartości scope i audience są automatycznie wypełniane przez interfejs wiersza polecenia agenta 365 podczas dodawania serwera MCP. Te wartości pochodzą z katalogu serwerów MCP i definiują uprawnienia wymagane do uzyskania dostępu do każdego serwera MCP.

Integrowanie narzędzi z agentem

Po wygenerowaniu manifestu narzędzi zintegruj skonfigurowane serwery MCP z kodem agenta. W tej sekcji opisano opcjonalny krok inspekcji i wymagane kroki integracji.

Wyświetlanie listy serwerów narzędzi (opcjonalnie)

Wskazówka

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

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

  • Wykonywanie zapytań dotyczących wszystkich skonfigurowanych serwerów MCP z poziomu ToolingManifest.json
  • Pobieranie metadanych i możliwości serwera
  • Weryfikowanie dostępności serwera przed rejestracją

Metoda wyświetlania listy serwerów narzędzi jest dostępna w podstawowych pakietach narzędzi:

# 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 Type Podpis Oczekiwana wartość Wymagane/opcjonalnie
agentic_app_id str Unikatowy identyfikator wystąpienia aplikacji agenta Prawidłowy ciąg identyfikatora aplikacji agenta Wymagania
auth_token str Token elementu nośnego do uwierzytelniania za pomocą bramy serwera MCP Prawidłowy token elementu nośnego OAuth Wymagania

Pakiet: microsoft-agents-a365-tooling

Rejestrowanie narzędzi za pomocą orkiestratora

Użyj metody rozszerzenia specyficznej dla platformy, aby zarejestrować wszystkie serwery MCP w ramach struktury aranżacji:

  • .Net
  • add_tool_servers_to_agent (Python)
  • addToolServersToAgent (Node.js)

Te metody:

  • Rejestrowanie wszystkich narzędzi ze skonfigurowanych serwerów MCP za pomocą orkiestratora
  • Automatyczne konfigurowanie szczegółów uwierzytelniania i połączenia
  • Natychmiastowe udostępnianie narzędzi agentowi do wywoływania

Wybieranie rozszerzenia orkiestratora

Moduł Narzędzi agenta 365 udostępnia dedykowane pakiety rozszerzeń dla różnych struktur aranżacji:

  • microsoft-agents-a365-tooling: podstawowe funkcje narzędzi
  • microsoft-agents-a365-tooling-extensions-agentframework: Integracja z platformą Agent Framework
  • microsoft-agents-a365-tooling-extensions-azureaifoundry: integracja usługi Azure AI Foundry
  • microsoft-agents-a365-tooling-extensions-openai: integracja z usługą OpenAI
  • microsoft-agents-a365-tooling-extensions-semantickernel: Integracja jądra semantycznego

Notatka

Uwierzytelnianie jest konfigurowane automatycznie przez interfejs wiersza polecenia agenta 365 podczas uruchamiania polecenia a365 develop add-mcp-servers. Zakresy protokołu OAuth i wartości odbiorców są pobierane z katalogu serwerów MCP i zawarte w pliku ToolingManifest.json. Metody rozszerzenia automatycznie używają tych wartości do skonfigurowania uwierzytelniania — nie jest wymagana żadna konfiguracja ręczna.

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

Przykład wdrożenia

W poniższych przykładach pokazano, jak zintegrować narzędzia agenta 365 z różnymi strukturami aranżacji.

Język Python z funkcją OpenAI

W tym przykładzie pokazano, jak zintegrować narzędzia MCP z usługą OpenAI w aplikacji języka Python.

Dodaj instrukcję 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. Inicjowanie usług narzędzi

Tworzenie wystąpień usług konfiguracji i 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. Rejestrowanie narzędzi MCP za pomocą agenta OpenAI

add_tool_servers_to_agent Użyj metody , aby zarejestrować wszystkie skonfigurowane narzędzia MCP za pomocą agenta OpenAI. Ta metoda obsługuje scenariusze uwierzytelniania agenta i niegenicznego:

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ć.

Parametry Opisy
agent Wystąpienie agenta OpenAI do rejestrowania narzędzi.
agentic_app_id Unikatowy identyfikator agenta (identyfikator aplikacji agenta).
auth Kontekst autoryzacji użytkownika.
context Bieżąca konwersacja zamienia kontekst z zestawu SDK agentów. Zapewnia tożsamość użytkownika, metadane konwersacji i kontekst uwierzytelniania na potrzeby bezpiecznej rejestracji narzędzi.
auth_token (Opcjonalnie) Token elementu nośnego dla scenariuszy uwierzytelniania niegentycznego.

4. Wywołanie podczas inicjowania

Przed uruchomieniem agenta upewnij się, że wywołasz metodę konfiguracji podczas inicjowania:

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

add_tool_servers_to_agent Metoda jest automatycznie:

  • Ładuje wszystkie serwery MCP z ToolingManifest.json
  • Rejestruje swoje narzędzia za pomocą agenta OpenAI
  • Konfiguruje uwierzytelnianie na podstawie konfiguracji manifestu
  • Udostępnia narzędzia do wywoływania agenta

Aby zapoznać się z pełnymi przykładami roboczymi, zobacz repozytorium Przykłady agenta 365.

Testowanie i monitorowanie

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. Postępuj zgodnie z przewodnikiem testowania, aby skonfigurować środowisko, a następnie skoncentruj się przede wszystkim na sekcji Wywołania narzędzi testowych, aby sprawdzić, czy narzędzia MCP działają zgodnie z oczekiwaniami.

Dodawanie możliwości obserwowania

Dodaj do agenta możliwość monitorowania i śledzenia wywołań narzędzia MCP agenta, dodawania możliwości obserwowania w celu śledzenia wydajności, problemów z debugowaniem i zrozumienia wzorców użycia narzędzi. Dowiedz się więcej o implementowaniu śledzenia i monitorowania

  • Last updated on