다음을 통해 공유

Microsoft 에이전트 365 SDK를 사용하여 에이전트 테스트

중요

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

배포하기 전에 에이전트 플레이그라운드를 사용하여 에이전트를 로컬로 테스트합니다. 이 가이드에서는 에이전트 플레이그라운드 테스트 도구를 사용하여 개발 환경 설정, 인증 구성 및 에이전트 기능 유효성 검사에 대해 설명합니다.

에이전트가 로컬로 작동하면 배포하고 게시하여 Teams와 같은 Microsoft 365 애플리케이션에서 테스트할 수 있습니다.

필수 구성 요소

시작하기 전에 다음과 같은 필수 구성 요소가 있는지 확인합니다.

Python 필수 구성 요소

언어별 필수 구성 요소

에이전트 테스트 환경 구성

이 섹션에서는 환경 변수 설정, 개발 환경 인증 및 테스트를 위해 에이전트 365 기반 에이전트 준비에 대해 설명합니다.

에이전트 테스트 환경을 설정하는 것은 순차적 워크플로를 따릅니다.

  1. 환경 구성 - 환경 구성 파일 만들기 또는 업데이트

  2. LLM 구성 - API 키 가져오기 및 OpenAI 또는 Azure OpenAI 설정 구성

  3. 인증 구성 - 에이전트 인증 설정

  4. 환경 변수 참조 - 필요한 환경 변수 구성:

    1. 인증 변수
    2. 끝점 구성
    3. 관찰 가능성 변수
    4. 에이전트 애플리케이션 서버 구성

이러한 단계를 완료하면 에이전트 플레이그라운드에서 에이전트 테스트를 시작할 준비가 된 것입니다.

5단계: 환경 구성

구성 파일 설정

cp .env.template .env

참고

필요한 필드를 보여 주는 구성 템플릿을 찾으려면 Microsoft 에이전트 365 SDK 샘플을 참조하세요.

2단계: 구성

로컬 테스트를 위해 OpenAI 또는 Azure OpenAI 설정을 구성합니다. 필수 구성 요소에서 얻은 API 키 및 서비스 엔드포인트를 모델 매개 변수와 함께 구성 파일에 추가합니다.

파일에 를 추가합니다.

# Replace with your actual OpenAI API key
OPENAI_API_KEY=

# Azure OpenAI Configuration
AZURE_OPENAI_API_KEY=
AZURE_OPENAI_ENDPOINT=
AZURE_OPENAI_DEPLOYMENT=
AZURE_OPENAI_API_VERSION=

Python LLM 환경 변수

변수 Description 필수 예
OPENAI_API_KEY OpenAI 서비스에 대한 API 키 OpenAI의 경우: sk-proj-...
AZURE_OPENAI_API_KEY Azure OpenAI Service API 키 Azure OpenAI의 경우: a1b2c3d4e5f6...
AZURE_OPENAI_ENDPOINT Azure OpenAI 서비스 엔드포인트 Azure OpenAI의 경우: https://your-resource.openai.azure.com/
AZURE_OPENAI_DEPLOYMENT : Azure OpenAI 배포 이름. Azure OpenAI의 경우: gpt-4
AZURE_OPENAI_API_VERSION Azure OpenAI용 API 버전 Azure OpenAI의 경우: 2024-02-15-preview

3단계: 에이전트 ID 인증에 대한 인증 값 구성

A365 CLI a365 config display 명령을 사용하여 에이전트 청사진 자격 증명을 검색합니다.

a365 config display -g

이 명령은 에이전트 청사진 구성을 표시합니다. 다음 값을 설정합니다.

값 설명
agentBlueprintId 에이전트의 클라이언트 ID
agentBlueprintClientSecret 에이전트의 클라이언트 암호
tenantId Microsoft Entra 테넌트 ID

에이전트에서 에이전트 인증을 구성하려면 다음 값을 사용합니다.

자리 표시자 값을 실제 자격 증명으로 바꿔 파일에 다음 설정을 .env 추가합니다.

USE_AGENTIC_AUTH=true
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID=<agentBlueprintId>
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET=<agentBlueprintClientSecret>
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID=<your-tenant-id>
변수 Description 필수 예
USE_AGENTIC_AUTH 에이전트 인증 모드 사용 있음 true
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID 에서 에이전트 청사진 클라이언트 ID a365 config display -g 있음 12345678-1234-1234-1234-123456789abc
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET 에서 에이전트 청사진 클라이언트 비밀 a365 config display -g 있음 abc~123...
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID Microsoft Entra 테넌트 ID. 있음 adfa4542-3e1e-46f5-9c70-3df0b15b3f6c

참고

.NET의 경우 설정 launchSettings.json 되었는지도 확인 USE_AGENTIC_AUTH=true 합니다(4단계: 환경 변수 참조 참조).

2단계: 환경 변수

다음 필수 환경 변수를 구성하여 환경 설정을 완료합니다.

인증 변수

에이전트 인증이 제대로 작동하는 데 필요한 인증 처리기 설정을 구성합니다.

파일에 를 추가합니다.

# Agentic Authentication Settings
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__TYPE=AgenticUserAuthorization
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__SCOPES=https://graph.microsoft.com/.default
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALTERNATEBLUEPRINTCONNECTIONNAME=service_connection

# Connection Mapping
CONNECTIONSMAP_0_SERVICEURL=*
CONNECTIONSMAP_0_CONNECTION=SERVICE_CONNECTION
변수 Description 필수
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__TYPE 인증 처리기 유형 있음
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__SCOPES Microsoft Graph의 인증 범위 있음
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALTERNATEBLUEPRINTCONNECTIONNAME 대체 청사진 연결 이름 있음
CONNECTIONSMAP_0_SERVICEURL 연결 매핑에 대한 서비스 URL 패턴 있음
CONNECTIONSMAP_0_CONNECTION 매핑에 대한 연결 이름 있음

끝점 구성

에이전트가 연결해야 하는 에이전트 365 플랫폼 엔드포인트를 지정하려면 MCP(모델 컨텍스트 프로토콜) 엔드포인트 구성이 필요합니다. 에이전트의 도구 서버를 정의하는 도구 매니페스트를 생성하는 경우 MCP 플랫폼 엔드포인트를 지정해야 합니다. 이 엔드포인트는 MCP 도구 서버가 Microsoft 365 통합 기능을 위해 연결하는 환경(미리 로드, 테스트 또는 프로덕션)을 결정합니다.

파일에 를 추가합니다.

# MCP Server Configuration
MCP_PLATFORM_ENDPOINT=<MCP endpoint>
변수 Description 필수 여부 기본값 예
MCP_PLATFORM_ENDPOINT MCP 플랫폼 엔드포인트 URL(미리 로드, 테스트 또는 prod) 아니요 프로덕션 엔드포인트의 경우:

중요: 지정되지 않은 경우 MCP_PLATFORM_ENDPOINT 기본적으로 프로덕션 엔드포인트로 설정됩니다.

관찰 가능성 변수

에이전트에 대한 로깅 및 분산 추적을 사용하도록 이러한 필수 변수를 구성합니다. 관찰 기능 및 모범 사례에 대해 자세히 알아보기

참고

관찰성 구성은 모든 언어에서 동일합니다.

변수 설명 Default 예
ENABLE_A365_OBSERVABILITY 관찰 가능성 사용/사용 안 함 false true
ENABLE_A365_OBSERVABILITY_EXPORTER 추적을 관찰 서비스로 내보내기 false true
OBSERVABILITY_SERVICE_NAME 추적에 대한 서비스 이름 에이전트 이름 my-agent-service
OBSERVABILITY_SERVICE_NAMESPACE 서비스 네임스페이스입니다. agent365-samples my-company-agents

에이전트 애플리케이션 서버 구성

에이전트 애플리케이션 서버가 실행되는 포트를 구성합니다. 이는 선택 사항이며 Python 및 JavaScript 에이전트에 적용됩니다.

파일에 를 추가합니다.

# Server Configuration
PORT=3978
변수 Description 필수 여부 기본값 예
PORT 에이전트 서버가 실행되는 포트 번호 아니요 3978 3978

종속성 설치 및 에이전트 애플리케이션 서버 시작

환경이 구성되면 필요한 종속성을 설치하고 테스트를 위해 에이전트 애플리케이션 서버를 로컬로 시작해야 합니다.

종속성 설치

uv pip install -e .

이 명령은 정의된 pyproject.toml 패키지 종속성을 읽고 PyPI에서 설치합니다. 에이전트 애플리케이션을 처음부터 만들 때 종속성을 정의하는 파일을 만들어야 pyproject.toml 합니다. 샘플 리포지토리의 샘플 에이전트에는 이미 이러한 패키지가 정의되어 있습니다. 필요에 따라 추가하거나 업데이트할 수 있습니다.

애플리케이션 서버 시작

python <main.py>

에이전트 애플리케이션의 진입점(예start_with_generic_host.pyapp.pymain.py: 또는)이 포함된 기본 Python 파일의 이름으로 바꿉 <main.py> 니다.

또는 uv 사용:

uv run python <main.py>

이제 에이전트 서버가 실행 중이며 에이전트 플레이그라운드 또는 Microsoft 365 애플리케이션에서 요청을 받을 준비가 되었습니다.

에이전트 플레이그라운드에서 에이전트를 테스트합니다.

에이전트 플레이그라운드는 전체 테넌트를 설정하지 않고도 Microsoft 365 환경을 시뮬레이션하는 로컬 테스트 도구입니다. 에이전트의 논리 및 도구 호출의 유효성을 검사하는 가장 빠른 방법입니다. 자세한 내용은 에이전트 플레이그라운드 테스트를 참조 하세요.

새 터미널(Windows의 PowerShell)을 열고 에이전트 플레이그라운드를 시작합니다.

agentsplayground

그러면 에이전트 플레이그라운드 인터페이스가 있는 웹 브라우저가 열립니다. 이 도구는 에이전트에 메시지를 보낼 수 있는 채팅 인터페이스를 표시합니다.

기본 테스트

먼저 에이전트가 제대로 구성되었는지 확인합니다. // Send a message to the queue

What can you do?

에이전트는 에이전트의 시스템 프롬프트 및 기능에 따라 구성된 지침으로 회신해야 합니다. 가 인지 확인합니다.

  • 에이전트가 올바르게 실행되고 있습니다.
  • 에이전트는 메시지를 처리하고 응답할 수 있습니다.
  • 에이전트 플레이그라운드와 에이전트 간의 통신이 작동합니다.

테스트 도구 호출

MCP 도구 서버를 toolingManifest.json 구성한 후(설치 지침에 대한 도구 참조) 다음과 같은 예제를 사용하여 도구 호출을 테스트합니다.

먼저 사용할 수 있는 도구를 확인합니다.

List all tools I have access to

그런 다음, 특정 도구 호출을 테스트합니다.

메일 도구

Send email to your-email@example.com with subject "Test" and message "Hello from my agent"

예상 응답: 에이전트가 메일 MCP 서버를 사용하여 이메일을 보내고 메시지가 전송되었는지 확인합니다.

일정 도구

List my calendar events for today

예상 응답: 에이전트가 현재 날짜에 대한 일정 이벤트를 검색하고 표시합니다.

SharePoint 도구

List all SharePoint sites I have access to

예상 응답: 에이전트가 SharePoint를 쿼리하고 액세스 권한이 있는 사이트 목록을 반환합니다.

다음에서 도구 호출을 볼 수 있습니다.

  • 채팅 창 - 에이전트의 응답 및 도구 호출 참조
  • 로그 패널 - 도구 매개 변수 및 응답을 포함한 자세한 활동 정보 참조

알림 활동으로 테스트

로컬 개발 중에 에이전트 플레이그라운드에서 사용자 지정 활동을 시뮬레이션하여 알림 시나리오를 테스트할 수 있습니다. 이렇게 하면 프로덕션에 배포하기 전에 에이전트의 알림 처리를 확인할 수 있습니다.

알림 활동을 테스트하기 전에 다음이 있는지 확인합니다.

알림이 제대로 작동하려면 적절한 도구 구성과 알림 설정이 모두 필요합니다. 사용자 지정 작업 기능을 사용하여 메일 알림 또는 Word 메모와 같은 시나리오를 테스트할 수 있습니다.

사용자 지정 활동을 보내려면 다음을 수행합니다.

  1. 에이전트 및 에이전트 플레이그라운드 시작
  2. 에이전트 플레이그라운드에서 모의 작업>사용자 지정 작업으로 이동합니다.
  3. conversationId 활동에서 복사(에이전트 플레이그라운드가 다시 시작될 때마다 대화 ID가 변경됨)
  4. 사용자 지정 활동 JSON을 붙여넣고 복사한 personal-chat-id 대화 ID로 필드를 업데이트합니다. 전자 메일 알림 예제를 참조하세요.
  5. 활동 추가를 선택하십시오.
  6. 채팅 대화와 로그 패널 모두에서 결과 보기

메일 알림

에이전트로 전송된 전자 메일을 시뮬레이션합니다. 자리 표시자 값을 실제 에이전트 세부 정보로 바꿉다.

{
  "type": "message",
  "id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
  "timestamp": "2025-09-24T17:40:19+00:00",
  "serviceUrl": "http://localhost:56150/_connector",
  "channelId": "agents",
  "name": "emailNotification",
  "from": {
    "id": "manager@contoso.com",
    "name": "Agent Manager",
    "role": "user"
  },
  "recipient": {
    "id": "agent@contoso.com",
    "name": "Agent",
    "agenticUserId": "<your-agentic-user-id>",
    "agenticAppId": "<your-agent-app-id>",
    "tenantId": "<your-tenant-id>"
  },
  "conversation": {
    "conversationType": "personal",
    "tenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
    "id": "personal-chat-id"
  },
  "membersAdded": [],
  "membersRemoved": [],
  "reactionsAdded": [],
  "reactionsRemoved": [],
  "locale": "en-US",
  "attachments": [],
  "entities": [
    {
      "id": "email",
      "type": "productInfo"
    },
    {
      "type": "clientInfo",
      "locale": "en-US",
      "timezone": null
    },
    {
      "type": "emailNotification",
      "id": "bbbbbbbb-1111-2222-3333-cccccccccccc",
      "conversationId": "personal-chat-id",
      "htmlBody": "<body dir=\"ltr\">\n<div class=\"elementToProof\" style=\"font-family: Aptos, Aptos_EmbeddedFont, Aptos_MSFontService, Calibri, Helvetica, sans-serif; font-size: 12pt; color: rgb(0, 0, 0);\">\nYour email message content here</div>\n\n\n</body>"
    }
  ],
  "channelData": {
    "tenant": {
      "id": "aaaabbbb-0000-cccc-1111-dddd2222eeee"
    }
  },
  "listenFor": [],
  "textHighlights": []
}

관찰 가능성 로그 보기

로컬 개발 중에 관찰성 로그를 보려면 관찰 코드(코드 예제의 관찰 가능성 참조)를 사용하여 에이전트를 계측하고 Observability 변수에 설명된 대로 환경 변수를 구성합니다. 구성되면 콘솔에 다음과 같은 실시간 추적이 표시됩니다.

  • 에이전트 호출 추적
  • 실행 세부정보
  • LLM 유추 호출
  • 입력 및 출력 메시지
  • 토큰 사용량
  • 대응 시간
  • 오류 정보

이러한 로그는 문제를 디버그하고, 에이전트 동작을 이해하고, 성능을 최적화하는 데 도움이 됩니다.

문제 해결

이 섹션에서는 에이전트를 로컬로 테스트할 때 발생할 수 있는 일반적인 문제에 대한 솔루션을 제공합니다.

연결 및 환경 문제

이러한 문제는 네트워크 연결, 포트 충돌 및 에이전트가 제대로 통신하지 못하게 할 수 있는 환경 설정 문제와 관련이 있습니다.

에이전트 플레이그라운드 연결 문제

증상: 에이전트 플레이그라운드가 에이전트에 연결할 수 없음

해결 방법:

  • 에이전트 서버가 실행 중인지 확인
  • 에이전트와 에이전트 플레이그라운드 간에 포트 번호가 일치하는지 확인합니다.
  • Blob 컨테이너에 액세스를 제한하는 방화벽 규칙이 설정되지 않았는지 확인합니다.
  • 에이전트와 에이전트 플레이그라운드를 모두 다시 시작해 보세요.

오래된 에이전트 플레이그라운드 버전

증상: 에이전트 플레이그라운드의 예기치 않은 오류 또는 누락된 기능

해결 방법: 에이전트 플레이그라운드 제거 및 다시 설치:

winget uninstall agentsplayground
winget install agentsplayground

포트 충돌

증상: 포트가 이미 사용 중임을 나타내는 오류

해결 방법:

  • 에이전트의 다른 인스턴스 중지
  • 구성에서 변경사항을 저장합니다.
  • 포트를 사용하여 모든 프로세스를 종료합니다.
# Windows PowerShell
Get-Process -Id (Get-NetTCPConnection -LocalPort <port>).OwningProcess | Stop-Process

DeveloperMCPServer를 추가할 수 없습니다.

증상: VS Code에서 DeveloperMCPServer를 추가하려고 할 때 오류 발생

해결 방법: Visual Studio Code를 닫고 다시 연 다음 서버를 다시 추가합니다.

인증 문제

이러한 문제는 에이전트가 Microsoft 365 서비스에서 제대로 인증할 수 없거나 자격 증명이 만료되거나 잘못 구성된 경우에 발생합니다.

전달자 토큰이 만료됨

증상: 인증 오류 또는 401 권한 없는 응답

해결 방법: 전달자 토큰은 약 1시간 후에 만료됩니다. 새 토큰을 획득하고 구성을 업데이트합니다.

Python의 에이전트 인증 오류

증상: 에이전트 인스턴스 토큰 획득 오류

해결 방법: 다음에서 ALT_BLUEPRINT_NAME 설정을 확인합니다 .env.

# Change from:
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALT_BLUEPRINT_NAME=ServiceConnection

# To:
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALT_BLUEPRINT_NAME=SERVICE_CONNECTION

알려진 문제 및 알림

이러한 문제에는 도구 호출, MCP 서버 상호 작용 및 알림 배달과 관련된 문제가 포함됩니다.

이메일을 받지 못함

증상: 에이전트는 전자 메일이 전송되었지만 수신하지 않음을 나타냅니다.

해결 방법:

  • ✅ 정크/스팸 폴더를 확인합니다.
  • 전자 메일 배달이 몇 분 지연될 수 있음 - 최대 5분 대기
  • 이메일 주소가 올바른지 확인하십시오.
  • 전자 메일을 보내는 동안 에이전트 로그에서 오류가 있는지 확인합니다.

Word 주석 응답이 작동하지 않음

알려진 문제: 알림 서비스는 현재 Word 메모에 직접 응답할 수 없습니다. 이 기능은 더 이상 사용되지 않습니다.

도움말 가져오기

이 문제 해결 섹션에서 다루지 않는 문제가 발생하는 경우 다음 리소스를 탐색합니다.

Microsoft Agent 365 SDK 리포지토리

추가 지원

다음 단계:

에이전트를 로컬에서 성공적으로 테스트했으므로 Azure에 배포하고 Microsoft 365에 게시할 준비가 되었습니다.

  • 에이전트 배포 및 게시: Azure Web App에 에이전트를 배포하고 Microsoft Admin Center에 게시하여 조직에서 Microsoft 365에서 검색하고 고용할 수 있도록 하는 방법을 알아봅니다.
  • Last updated on