빠른 시작: Python 에이전트 프레임워크 샘플 에이전트 설정 및 실행

이 빠른 시작에서는 에이전트 플레이그라운드 및 Teams를 사용하여 에이전트를 도구, 알림, 관찰 가능성 및 테스트하기 위해 에이전트 365를 사용하여 작동하는 Python 에이전트 프레임워크 에이전트를 설정하는 단계를 안내합니다.

필수 구성 요소

Visual Studio Code를 사용하려는 경우 .NET이 설치되어 있어야 합니다. (.NET 8.0을 사용하는 것이 좋습니다.)
Python 3.x가 설치되었습니다.
UV 패키지 관리자 가 설치되었습니다. 를 사용하여 pip install uv터미널에 설치합니다.
Microsoft Agents Toolkit/Agent Framework 종속성

연습에 사용된 샘플은 Microsoft 365 에이전트 도구 키트 또는 ATK를 통해 제공되는 에이전트 프레임워크 라이브러리를 사용합니다. VS Code에서 에이전트 도구 키트 확장을 사용하여 샘플을 스캐폴드하거나 이 명령을 사용하여 패키지를 수동으로 설치할 때 자동으로 설치합니다.
```
uv pip install -e . --find-links ../dist --pre
```
GitHub에 대한 액세스
기존 AI 에이전트 프로젝트입니다. 이 빠른 시작에서는 VS Code의 ATK라고도 하는 Microsoft 365 에이전트 도구 키트의 에이전트 365 샘플 에이전트를 사용합니다.
A365 CLI
에이전트 ID 인증

Microsoft 365 에이전트 도구 키트에서 에이전트 프레임워크 + Python 샘플 설정

모든 것을 준비하려면 VS Code에 Microsoft 365 에이전트 도구 키트를 설치하고, 샘플 갤러리를 열고, 에이전트 프레임워크 + Python 샘플을 로컬로 스캐폴드하여 나중에 구성하고 실행할 수 있습니다. 다음 스크린샷은 진행하면서 예상되는 내용을 보여 줍니다.

Visual Studio Code를 연 다음 확장 패널 Ctrl+Shift+X를 엽니다.
검색 창에서 "에이전트 도구 키트"를 입력합니다.
여기에 스크린샷에 표시된 결과가 표시됩니다.
Microsoft 365 에이전트 도구 키트
설치를 선택합니다.

VS Code는 다음과 유사한 확장 세부 정보 보기를 표시합니다.
설치 되면 M365 에이전트 도구 키트 아이콘이 왼쪽 탐색 모음에 나타납니다.
실험을 선택하여 엽니다.

이제 다음과 같이 선언적 에이전트 빌드, 새 에이전트/앱 만들기 및 샘플 보기와 같은 옵션이 표시됩니다.
샘플 보기를 선택합니다.
샘플 목록에서 스크롤하여 에이전트 프레임워크 + Python 에이전트 샘플을 찾습니다.
이 폴더를 선택합니다.

두 가지 선택 항목인 만들기 (로컬로 스캐폴드) 또는 GitHub에서 보기가 표시됩니다.
만들기를 선택합니다.
메시지가 표시되면 샘플을 생성해야 하는 컴퓨터의 폴더를 선택합니다. 예: C:\A365-python-sample

도구 키트는 에이전트 프레임워크 + Python 샘플을 하위 폴더(예: sample_agent)로 스캐폴드한 다음 VS Code에서 자동으로 엽니다.

스캐폴딩이 완료되면 이제 컴퓨터에 완전한 기능의 에이전트 프레임워크 + Python 에이전트 프로젝트가 생성됩니다.
필요한 패키지 설치

샘플을 실행하기 전에 프로젝트에서 열고 package.json 필요한 모든 에이전트 365 및 에이전트 프레임워크 종속성이 나열되어 있는지 확인합니다. Microsoft 365 에이전트 도구 키트에서 생성된 샘플에는 이러한 항목이 이미 포함되어 있습니다.

package.json 검토한 후에는 다음 명령을 실행하여 모든 항목을 설치합니다.
```
uv pip install -e
```
그러면 모든 에이전트 365 SDK 라이브러리, 에이전트 프레임워크 종속성, 호스팅 구성 요소 및 샘플에 정의된 기타 종속성이 모두 삭제됩니다.
설치 후 다음 명령을 사용하여 개발 서버를 시작하여 프로젝트가 빌드되고 실행되는지 확인합니다.
```
uv run python start_with_generic_host.py
```

Microsoft 365 도구 추가(MCP 서버)

CLI에서 a365 개발 명령을 사용하여 MCP 서버를 탐색하고 관리할 수 있습니다 .

MCP 서버를 사용하는 경우 다음을 수행할 수 있습니다.

사용할 수 있는 MCP 서버 검색
에이전트 구성에 하나 이상의 MCP 서버 추가
현재 구성된 MCP 서버 검토
더 이상 필요하지 않은 MCP 서버 제거

MCP 서버가 추가되면 에이전트의 도구 매니페스트가 확장되어 다음과 유사한 항목이 포함됩니다.

{
   "mcpServers": [
      {
         "mcpServerName": "mcp_MailTools",
         "mcpServerUniqueName": "mcp_MailTools",
         "scope": "McpServers.Mail.All",
         "audience": "api://00001111-aaaa-2222-bbbb-3333cccc4444"
      }
   ]
}

도구를 추가하고 관리하는 방법 알아보기

알림 구독 및 처리

샘플 에이전트는 모든 에이전트 365 SDK 알림을 사용하여 onAgentNotification("*") 구독하고 단일 처리기로 라우팅합니다. 이 처리기를 사용하면 에이전트가 직접 사용자 메시지뿐만 아니라 백그라운드 또는 시스템 이벤트에 반응할 수 있습니다.

에이전트에 알리는 방법 알아보기

다음 코드는 파일에서 알림을 구성하는 방법을 보여 있습니다 agent.py .

if notification_type == NotificationTypes.EMAIL_NOTIFICATION: 
if not hasattr(notification_activity, "email") or not notification_activity.email: return "I could not find the email notification details."
email = notification_activity.email
email_body = getattr(email, "html_body", "") or getattr(email, "body", "")

message = (
    "You have received the following email. "
    "Please follow any instructions in it. "
    f"{email_body}"
)

result = await self.agent.run(message)
return self._extract_result(result) or "Email notification processed."

가시성

이 코드 조각은 샘플에서 관찰 가능성을 사용하도록 설정하는 데 필요한 최소한의 변경 내용을 보여 줍니다. 에이전트 365 Observability SDK를 초기화하고 각 에이전트 호출 InferenceScope 을 래핑하여 입력, 출력 및 메타데이터를 자동으로 캡처할 수 있습니다.

다음 코드는 파일의 간소화된 관찰 가능성 예제를 agent.py 보여줍니다.

def _enable_agentframework_instrumentation(self): 
"""Enable Agent Framework instrumentation.""" 
try: 
AgentFrameworkInstrumentor().instrument() 
logger.info("✅ Instrumentation enabled")
 except Exception as e: 
logger.warning(f"⚠️ Instrumentation failed: {e}")

이 코드는 Python + 에이전트 프레임워크 샘플에 필요한 전체 가시성 설정입니다. 관찰 가능성에 대해 자세히 알아보기

에이전트 테스트

필요한 환경 변수를 설정하고, 인증 모드를 선택하고, 에이전트를 로컬로 시작합니다. 에이전트를 게시하고 Teams 또는 Outlook과 같은 앱에서 사용하지 않으려면 Microsoft 365 테넌트를 사용하지 않고도 에이전트 플레이그라운드를 사용하여 모든 것을 엔드 투 엔드(end-to-end)로 테스트할 수 있습니다.

테스트 단계 개요

샘플이 LLM과 통신할 .env 수 있도록 파일에 API 키 및 모델 설정을 추가합니다.
인증 방법 선택 로컬 개발의 경우 샘플은 에이전트 청사진에서 만든 값을 사용하여 에이전트 인증을 지원합니다.
에이전트를 로컬로 시작하여 에이전트 플레이그라운드와 같은 도구에 노출합니다.
에이전트 플레이그라운드를 사용하여 테넌트를 설정하거나 아무것도 배포하지 않고 메시지, 도구 및 알림을 테스트합니다.
실제 동작에 대한 준비가 되면 Microsoft 365 테넌트를 게시하고 Teams, Outlook 또는 기타 Microsoft 365 화면 내에서 에이전트를 테스트합니다.

테스트에 대해 자세히 알아보기

에이전트 게시

에이전트가 Teams 채팅, Outlook 메시지, Word @mentions와 같은 실제 Microsoft 365 환경에 대해 준비가 되면 Microsoft 365 테넌트에 게시합니다. 에이전트 365 CLI publish 명령은 패키징을 처리합니다. 매니페스트를 업데이트하고, 모든 항목을 번들로 묶고, 에이전트를 Microsoft 관리 센터에 업로드합니다.

게시하는 동안 업로드를 완료하기 전에 에이전트의 이름, 설명, 아이콘 및 버전을 검토하고 사용자 지정합니다. 게시되면 에이전트가 테넌트 내에서 검색 가능하고 설치 가능해집니다.

게시된 에이전트는 여기에서 볼 수 있습니다. https://admin.cloud.microsoft/#/agents/all

전체 워크플로 및 단계별 지침에 대해 자세히 알아보기

피드백

이 페이지가 도움이 되었나요?

Last updated on 2025-12-02