다음을 통해 공유

도구 추가 및 관리

중요

Microsoft 에이전트 365에 대한 초기 액세스를 얻으려면 프론티어 미리 보기 프로그램의 일부여야 합니다. 프론티어는 Microsoft의 최신 AI 혁신과 직접 연결합니다. 프론티어 미리 보기에는 고객 계약의 기존 미리 보기 조건이 적용됩니다. 이러한 기능은 아직 개발 중이므로 가용성 및 기능은 시간이 지남에 따라 변경 될 수 있습니다.

도구 모듈을 사용하면 개발자가 MCP(모델 컨텍스트 프로토콜) 서버를 검색, 구성 및 AI 에이전트 워크플로에 통합할 수 있습니다. MCP 서버는 외부 기능을 AI 에이전트가 호출할 수 있는 도구로 노출합니다. 사용 가능한 도구 서버에 대한 개요는 에이전트 365 도구 서버를 참조 하세요.

요청 및 응답 흐름을 보여 줍니다.

개요

에이전트 365 도구 통합은 4단계 워크플로를 따릅니다.

  1. MCP 서버 구성 - 에이전트 365 CLI를 사용하여 MCP 서버 검색 및 추가
  2. 매니페스트 생성 - CLI는 서버 구성을 사용하여 만듭니다 ToolingManifest.json .
  3. 코드 에 통합 - 매니페스트 로드 및 오케스트레이터에 도구 등록
  4. 도구 호출 - 에이전트는 실행 중에 도구를 호출하여 작업을 수행합니다.

필수 구성 요소

백업 서비스를 구성하기 전에, 다음 사항을 확인해야 합니다.

에이전트 ID 설정

에이전트 인증을 사용하는 경우 MCP 서버를 구성하기 전에 에이전트 등록 프로세스를 완료하여 에이전트 ID를 만듭니다. 그러면 에이전트가 MCP 도구를 인증하고 액세스할 수 있는 에이전트 앱 ID 및 에이전트 사용자가 만들어집니다.

서비스 주체 설정

이 일회성 설치 스크립트를 실행하여 테넌트에서 에이전트 365 도구에 대한 서비스 주체를 만듭니다.

중요

전역 관리자 권한이 필요한 테넌트당 일회성 작업입니다.

  1. New-Agent365ToolsServicePrincipalProdPublic.ps1 스크립트 다운로드

  2. 관리자 권한으로 PowerShell을 열고 PowerShell 스크립트를 저장한 디렉터리로 이동합니다.

  3. 스크립트를 실행합니다.

    .\New-Agent365ToolsServicePrincipalProdPublic.ps1

  4. 메시지가 표시되면 Azure 자격 증명을 사용하여 로그인합니다.

완료 후 테넌트는 에이전트 개발 및 MCP 서버 구성을 수행할 준비가 됩니다.

MCP 서버 구성

에이전트 365 CLI를 사용하여 에이전트에 대한 MCP 서버를 검색, 추가 및 관리합니다. 사용 가능한 MCP 서버 및 해당 기능의 전체 목록은 MCP 서버 카탈로그를 참조하세요.

사용 가능한 카운터 검색

구성할 수 있는 모든 MCP 서버를 나열합니다.

a365 develop list-available

MCP 서버 추가

에이전트 구성에 하나 이상의 MCP 서버를 추가합니다.

a365 develop add-mcp-servers mcp_MailTools

구성된 서버 나열

현재 구성된 MCP 서버 보기:

a365 develop list-configured

MCP 서버 제거

구성에서 MCP 서버를 제거합니다.

a365 develop remove-mcp-servers mcp_MailTools

전체 CLI 참조는 a365 개발 명령을 참조 하세요.

도구 매니페스트 이해

실행 a365 develop add-mcp-servers하면 CLI는 모든 MCP 서버에 대한 구성이 포함된 파일을 생성합니다 ToolingManifest.json . 에이전트 런타임은 이 매니페스트를 사용하여 사용할 수 있는 서버와 이를 사용하여 인증하는 방법을 이해합니다.

매니페스트 구조

예: ToolingManifest.json

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

매니페스트 매개 변수

각 MCP 서버 항목에는 다음이 포함됩니다.

매개 변수 설명
mcpServerName 사용자의 표시 이름
mcpServerUniqueName MCP 서버 인스턴스의 고유 식별자
범위 MCP 서버의 기능에 액세스하는 데 필요한 OAuth 범위입니다(예: McpServers.Mail.All 메일 작업의 경우). 이 값은 명령을 실행할 때 MCP 서버 카탈로그에서 검색됩니다 add-mcp-servers .
대상 대상 API 리소스를 식별하는 Microsoft Entra ID URI입니다. 이 값은 MCP 서버 카탈로그에서도 검색됩니다.

참고

scope MCP 서버를 추가할 때 에이전트 365 CLI에서 값과 audience 값이 자동으로 채워집니다. 이러한 값은 MCP 서버 카탈로그 에서 제공되며 각 MCP 서버에 액세스하는 데 필요한 권한을 정의합니다.

에이전트에 사용자 지정 도구 통합

도구 매니페스트를 생성한 후 구성된 MCP 서버를 에이전트 코드에 통합합니다. 이 섹션에서는 선택적 검사 단계 및 필요한 통합 단계를 설명합니다.

목록 도구 서버(선택 사항)

팁

이 단계는 선택 사항입니다. 도구 서버 구성 서비스를 사용하여 도구 매니페스트에서 사용 가능한 도구 서버를 검사한 후 오케스트레이터에 추가합니다.

도구 서버 구성 서비스를 사용하여 도구 매니페스트에서 에이전트가 사용할 수 있는 도구 서버를 검색합니다. 이 메서드를 사용하면 다음을 수행할 수 있습니다.

  • 에서 구성된 모든 MCP 서버를 쿼리합니다. ToolingManifest.json
  • 서버 메타데이터 및 기능 검색
  • 등록하기 전에 서버 가용성 확인

도구 서버를 나열하는 방법은 핵심 도구 패키지에서 사용할 수 있습니다.

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

매개 변수:

매개 변수 Type Description 예상 값 필수/선택 사항
agentic_app_id str 설치된 Win32 애플리케이션의 고유 식별자입니다. 유효한 에이전트 애플리케이션 ID 문자열 필수
auth_token str MCP 서버 게이트웨이를 사용하여 인증하기 위한 전달자 토큰 유효한 OAuth 전달자 토큰 필수

패키지: microsoft-agents-a365-tooling

오케스트레이터에 도구 등록

프레임워크별 확장 메서드를 사용하여 오케스트레이션 프레임워크에 모든 MCP 서버를 등록합니다.

  • .NET
  • Python
  • Node.js:

이러한 메서드는 다음과 같습니다.

  • 구성된 MCP 서버의 모든 도구를 오케스트레이터에 등록
  • 인증 및 연결 세부 정보 자동 설정
  • 에이전트에서 즉시 도구를 호출할 수 있도록 설정

오케스트레이터 확장 선택

에이전트 365 도구 모듈은 다양한 오케스트레이션 프레임워크에 대한 전용 확장 패키지를 제공합니다.

  • microsoft-agents-a365-tooling: 핵심 도구 기능
  • microsoft-agents-a365-tooling-extensions-agentframework: Agent Framework 통합
  • microsoft-agents-a365-tooling-extensions-azureaifoundry: Azure AI Foundry 통합
  • microsoft-agents-a365-tooling-extensions-openai: OpenAI 통합
  • microsoft-agents-a365-tooling-extensions-semantickernel: 의미 체계 커널 통합

참고

인증은 실행할 a365 develop add-mcp-servers때 에이전트 365 CLI에 의해 자동으로 구성됩니다. OAuth 범위 및 대상 그룹 값은 MCP 서버 카탈로그에서 검색되고 에 포함 ToolingManifest.json됩니다. 확장 메서드는 이러한 값을 자동으로 사용하여 인증을 설정합니다. 수동 구성은 필요하지 않습니다.

자세한 구현 예제는 에이전트 365 샘플을 참조 하세요.

구현 예제

다음 예제에서는 에이전트 365 도구를 다른 오케스트레이션 프레임워크와 통합하는 방법을 보여 줍니다.

OpenAI를 사용하여 Python

이 예제에서는 Python 애플리케이션에서 OPENAI와 MCP 도구를 통합하는 방법을 보여줍니다.

import 문을 추가합니다.

도구 모듈 및 OpenAI 확장에 액세스하는 데 필요한 가져오기를 추가합니다.

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

2. 도구 서비스 초기화

구성 및 도구 등록 서비스의 인스턴스를 만듭니다.

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

3. OpenAI 에이전트에 MCP 도구 등록

이 메서드를 add_tool_servers_to_agent 사용하여 구성된 모든 MCP 도구를 OpenAI 에이전트에 등록합니다. 이 메서드는 에이전트 인증 및 비제전 인증 시나리오를 모두 처리합니다.

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

메서드 매개 변수

아래의 표는 add_tool_servers_to_agent에서 사용되는 매개 변수에 대해 설명합니다.

매개 변수 설명
agent 도구를 등록할 OpenAI 에이전트 인스턴스입니다.
agentic_app_id 에이전트의 고유 식별자(에이전트 앱 ID)입니다.
auth 사용자의 권한 부여 컨텍스트입니다.
context 현재 대화는 에이전트 SDK에서 컨텍스트를 켭니다. 보안 도구 등록을 위한 사용자 ID, 대화 메타데이터 및 인증 컨텍스트를 제공합니다.
auth_token (선택 사항) 비연속 인증 시나리오에 대한 전달자 토큰입니다.

4. 초기화 중 호출

에이전트를 실행하기 전에 초기화 중에 설치 메서드를 호출해야 합니다.

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

메서드는 add_tool_servers_to_agent 자동으로 다음을 수행합니다.

  • ToolingManifest.json 모든 MCP 서버를 로드합니다.
  • OpenAI 에이전트에 도구를 등록합니다.
  • 매니페스트 구성에 따라 인증 설정
  • 에이전트가 호출할 수 있는 도구를 만듭니다.

전체 작업 예제는 에이전트 365 샘플 리포지토리를 참조 하세요.

테스트 및 모니터

에이전트 테스트

MCP 도구를 에이전트에 통합한 후 도구 호출을 테스트하여 올바르게 작동하는지 확인하고 다양한 시나리오를 처리합니다. 테스트 가이드에 따라 환경을 설정한 다음, 주로 테스트 도구 호출 섹션에 집중하여 MCP 도구가 예상대로 작동하는지 확인합니다.

SDK 가시성

에이전트에 관찰 기능을 추가하여 에이전트의 MCP 도구 호출을 모니터링하고 추적하고, 성능 추적, 문제 디버그 및 도구 사용 패턴을 이해하는 관찰 기능을 추가합니다. 추적 및 모니터링 구현에 대해 자세히 알아보기

  • Last updated on