Microsoft 365 에이전트 도구 키트 및 TypeSpec을 사용하여 선언적 에이전트 만들기

선언적 에이전트는 Microsoft 365 Copilot에서 제공하는 목표 지향적 대화형 환경을 제공합니다. 개발자가 그 목적, 지침, 지식 및 작업을 정의합니다. 이 가이드에서는 TypeSpec 및 Microsoft 365 에이전트 도구 키트를 사용하여 선언적 에이전트를 빌드하는 방법을 보여줍니다.

참고

이 자습서에서 빌드하는 에이전트는 라이선스가 있는 Microsoft 365 Copilot 사용자를 대상으로 합니다. 기능이 제한된 Microsoft 365 Copilot Chat 사용자용 에이전트를 빌드할 수도 있습니다. 자세한 내용은 Microsoft 365 Copilot 개발자 라이선스를 참조하세요.

팁

권장: 지원되는 프로 코드 선언적 에이전트 및 플러그인 시나리오에 대한 Work IQ Dev 도구 로 시작하십시오. WIQD 빠른 시작을 참조하세요. 도구 키트 기반 지침은 이를 필요로 하는 기존 프로젝트 및 워크플로에 계속 사용할 수 있습니다. 도구를 선택하기 전에 기능 및 대상 환경 지원을 확인하세요. WIQD는 사용자 지정 엔진 에이전트를 대상으로 하지 않습니다.

참고

이제 Microsoft 365 Copilot 기반의 선언적 에이전트가 Word 및 PowerPoint에서 지원됩니다.

필수 구성 요소

이 문서에 설명된 단계를 완료하려면 다음 리소스가 필요합니다.

참고

이 문서의 스크린샷 및 사용자 인터페이스 참조는 릴리스 버전의 Microsoft 365 에이전트 도구 키트를 사용합니다. 시험판 버전은 표시된 사용자 인터페이스와 다를 수 있습니다.

Microsoft 365 Copilot의 선언적 에이전트에 대한 다음 표준 및 지침을 숙지하세요.

선언적 에이전트 만들기

기본 선언적 에이전트를 만드는 것부터 시작합니다.

  1. Visual Studio Code를 엽니다.

  2. Microsoft 365 에이전트 도구 키트 > 를 선택하고 새 에이전트/앱을 만듭니다.

    Microsoft 365 에이전트 도구 키트 사이드바의 새 앱 만들기 단추 스크린샷

  3. 선언적 에이전트를 선택합니다.

    에이전트가 선택된 새 프로젝트 옵션의 스크린샷

  4. Microsoft 365 Copilot용 TypeSpec으로 시작을 선택하여 기본 선언적 에이전트를 만듭니다.

  5. 기본 폴더를 선택하여 프로젝트 루트 폴더를 기본 위치에 저장합니다.

  6. 응용 프로그램 이름으로 입력 My Agent 하고 Enter 키를 누릅니다.

  7. 열리는 새 Visual Studio Code 창에서 Microsoft 365 에이전트 도구 키트를 선택합니다. 수명 주기 창에서 프로비전을 선택합니다.

    Microsoft 365 에이전트 도구 키트의 수명 주기 창에 있는 프로비저닝 옵션의 스크린샷

에이전트 테스트

  1. 에서 Copilot 애플리케이션으로 이동합니다.https://m365.cloud.microsoft/chat

  2. 새 Chat 단추 옆에 있는 대화 서랍 아이콘을 선택합니다.

  3. 선언적 에이전트 내 에이전트를 선택합니다.

    Copilot의 선언적 에이전트 스크린샷

  4. 선언적 에이전트에 대한 질문을 입력하여 실제로 작동하는 모습을 확인할 수 있습니다.

지침 추가

지침은 에이전트의 동작 방식을 변경합니다.

  1. 파일을 열고 main.tsp 데코레이터를 @instructions 다음 코드로 바꿉니다.

    @instructions("""
      You are an expert at creating poems.
      Every time a user asks a question, you **must** turn the answer into a poem. The poem **must** not use the quote markdown and use regular text.
    """)
    

    프로비전 프로세스는 이 데코레이터의 콘텐츠를 에이전트 매니페스트의 속성에 instructions 삽입합니다. 자세한 내용은 선언적 에이전트 매니페스트 개체를 참조하세요.

  2. 에이전트 도구 키트의 수명 주기 창에서 프로비저닝을 선택합니다.

선언적 에이전트는 페이지를 다시 로드한 후 업데이트된 지침을 사용합니다.

업데이트된 지침에 따른 선언적 에이전트의 답변 스크린샷

대화 시작 요소 추가

대화 시작자는 Copilot이 선언적 에이전트를 사용하여 시작하는 방법을 보여주기 위해 사용자에게 표시하는 힌트입니다.

  1. 파일을 열고 main.tsp 주석이 추가된 @conversationStarter 데코레이터를 다음 콘텐츠로 바꿉니다.

    @conversationStarter(#{
      title: "Getting started",
      text: "How can I get started with Agents Toolkit?"
    })
    
    @conversationStarter(#{
      title: "Getting Help",
      text: "How can I get help with Agents Toolkit?"
    })
    

    자세한 내용은 대화 시작 개체를 참조하세요.

  2. 에이전트 도구 키트의 수명 주기 창에서 프로비저닝을 선택합니다.

업데이트된 대화 시작자는 페이지를 새로 고친 후 선언적 에이전트에서 사용할 수 있습니다.

Microsoft 365 Copilot의 선언적 에이전트에서 대화 시작을 보여주는 스크린샷

웹 콘텐츠 추가

웹 검색 기능을 사용하면 에이전트가 Bing의 검색 인덱스를 사용하여 사용자 프롬프트에 응답할 수 있습니다.

  1. 파일을 열고 main.tsp 다음 콘텐츠와 함께 네임스페이스에 MyAgent 기능을 추가합니다WebSearch.

    namespace MyAgent {
      op webSearch is AgentCapabilities.WebSearch<Sites = [
        {
          url: "https://learn.microsoft.com",
        },
      ]>;
    }
    

    자세한 내용은 웹 검색 개체를 참조하십시오.

    참고

    배열을 Sites 지정하지 않으면 에이전트가 모든 웹 콘텐츠에 액세스할 수 있습니다.

  2. 에이전트 도구 키트의 수명 주기 창에서 프로비저닝을 선택합니다.

선언적 에이전트는 페이지를 다시 로드한 후 웹 콘텐츠에 액세스하여 답변을 생성할 수 있습니다.

웹 콘텐츠를 포함하는 선언적 에이전트의 응답을 보여주는 스크린샷

OneDrive 및 SharePoint 콘텐츠 추가

SharePoint 기능을 통해 에이전트는 OneDrive 및 SharePoint 콘텐츠를 지식으로 사용할 수 있습니다.

  1. 파일을 열고 main.tsp 다음 값을 사용하여 네임스페이스에 MyAgent 기능을 추가 OneDriveAndSharePoint 하여 Microsoft 365 organization의 SharePoint 사이트 URL로 바꿉 https://contoso.sharepoint.com/sites/ProductSupport 니다.

    namespace MyAgent {
      // Omitted for brevity
      op od_sp is AgentCapabilities.OneDriveAndSharePoint<ItemsByUrl = [
        {
          url: "https://contoso.sharepoint.com/sites/ProductSupport"
        }
      ]>;
      // Omitted for brevity
    }
    

    자세한 내용은 OneDrive 및 SharePoint 개체를 참조하세요.

    참고

    • URL은 SharePoint 항목(사이트, 문서 라이브러리, 폴더 또는 파일)의 전체 경로여야 합니다. SharePoint에서 "직접 링크 복사" 옵션을 사용하여 전체 경로 또는 파일 및 폴더를 가져올 수 있습니다. 파일 또는 폴더를 마우스 오른쪽 버튼으로 클릭하고 세부 정보를 선택합니다. 경로로 이동하여 복사 아이콘을 선택합니다.
    • 배열(또는 대체 ItemsBySharePointIds 배열)을 지정 ItemsByUrl 하지 않으면 에이전트는 로그인한 사용자가 액세스할 수 있는 Microsoft 365 organization의 모든 OneDrive 및 SharePoint 콘텐츠에 액세스할 수 있습니다.
  2. 에이전트 도구 키트의 수명 주기 창에서 프로비저닝을 선택합니다.

선언적 에이전트는 페이지를 다시 로드한 후 OneDrive 및 SharePoint 콘텐츠에 액세스하여 답변을 생성할 수 있습니다.

SharePoint 및 OneDrive 콘텐츠가 포함된 선언적 에이전트의 응답을 보여주는 스크린샷

Teams 메시지 추가

Teams 메시지 기능을 사용하면 에이전트가 Teams 채널, 팀 및 모임 채팅을 지식으로 사용할 수 있습니다.

  1. 파일을 열고 main.tsp 네임스페이스에 MyAgent 기능을 다음 값으로 추가 TeamsMessages 하여 organization의 Teams 채널 또는 팀 URL로 바꿉 https://teams.microsoft.com/l/team/... 니다.

    namespace MyAgent {
      // Omitted for brevity
      op teamsMessages is AgentCapabilities.TeamsMessages<TeamsMessagesByUrl = [
        {
          url: "https://teams.microsoft.com/l/team/...",
        }
      ]>;
      // Omitted for brevity
    }
    

    자세한 내용은 Microsoft Teams 메시지 개체를 참조하세요.

    참고

    • 속성의 url URL은 Teams 채팅, 팀 또는 모임 채팅에 대한 올바른 형식의 링크여야 합니다.
    • 배열을 TeamsMessagesByUrl 지정하지 않으면 에이전트는 인증된 사용자가 액세스할 수 있는 Microsoft 365 organization의 모든 Teams 채널, 팀, 모임, 1:1 채팅 및 그룹 채팅에 액세스할 수 있습니다.
  2. 에이전트 도구 키트의 수명 주기 창에서 프로비저닝을 선택합니다.

선언적 에이전트는 페이지를 다시 로드한 후 Teams 데이터에 액세스하여 답변을 생성할 수 있습니다.

Teams 콘텐츠가 포함된 선언적 에이전트의 응답을 보여주는 스크린샷

사용자 지식 추가

피플 기능을 사용하면 에이전트가 organization의 개인에 대한 질문에 답변하도록 scope할 수 있습니다.

  1. 파일을 열고 main.tsp 다음 콘텐츠와 함께 네임스페이스에 MyAgent 기능을 추가합니다People.

    namespace MyAgent {
      // Omitted for brevity
      op people is AgentCapabilities.People;
      // Omitted for brevity
    }
    

    자세한 내용은 People 개체를 참조하세요.

  2. 에이전트 도구 키트의 수명 주기 창에서 프로비저닝을 선택합니다.

선언적 에이전트는 페이지를 다시 로드한 후 사용자 정보에 액세스할 수 있습니다.

사용자 정보가 포함된 선언적 에이전트의 응답을 보여주는 스크린샷

전자 메일 정보 추가

전자 메일 기능을 사용하면 사용자의 사서함 또는 공유 사서함의 전자 메일을 지식 원본으로 사용하도록 에이전트 scope할 수 있습니다.

  1. 파일을 열고 main.tsp 다음 콘텐츠와 함께 네임스페이스에 MyAgent 기능을 추가합니다Email.

    namespace MyAgent {
      // Omitted for brevity
      op email is AgentCapabilities.Email<Folders = [
        {
          folder_id: "Inbox",
        }
      ]>;
      // Omitted for brevity
    }
    

    자세한 내용은 Email 개체를 참조하십시오.

    참고

    • 이 예제에서는 에이전트 사서함의 사용자에 액세스합니다. 대신 공유 사서함에 액세스하려면 공유 사서함의 전자 메일 주소에 선택적 shared_mailbox 속성 집합을 추가합니다.
    • 배열은 Folders 사서함 액세스를 특정 폴더로 제한합니다. 전체 사서함에 액세스하려면 배열을 생략합니다.folders
  2. 에이전트 도구 키트의 수명 주기 창에서 프로비저닝을 선택합니다.

선언적 에이전트는 페이지를 다시 로드한 후 전자 메일 정보에 액세스할 수 있습니다.

전자 메일 정보가 포함된 선언적 에이전트의 응답을 보여주는 스크린샷

이미지 생성기 추가

이미지 생성기 기능을 사용하면 에이전트가 사용자 프롬프트를 기반으로 이미지를 생성할 수 있습니다.

  1. 파일을 열고 main.tsp 다음 콘텐츠와 함께 네임스페이스에 MyAgent 기능을 추가합니다GraphicArt.

    namespace MyAgent {
      // Omitted for brevity
      op graphicArt is AgentCapabilities.GraphicArt;
      // Omitted for brevity
    }
    

    자세한 내용은 그래픽 아트 개체를 참조하세요.

  2. 에이전트 도구 키트의 수명 주기 창에서 프로비저닝을 선택합니다.

선언적 에이전트는 페이지를 다시 로드한 후 이미지를 생성할 수 있습니다.

생성된 그래픽 아트가 포함된 선언적 에이전트의 응답을 보여주는 스크린샷

코드 인터프리터 추가

코드 인터프리터 기능은 Python 코드를 통해 복잡한 작업을 해결하도록 설계된 고급 도구입니다.

  1. 파일을 열고 main.tsp 다음 콘텐츠와 함께 네임스페이스에 MyAgent 기능을 추가합니다CodeInterpreter.

    namespace MyAgent {
      // Omitted for brevity
      op codeInterpreter is AgentCapabilities.CodeInterpreter;
      // Omitted for brevity
    }
    

    자세한 내용은 코드 인터프리터 개체를 참조하세요.

  2. 에이전트 도구 키트의 수명 주기 창에서 프로비저닝을 선택합니다.

선언적 에이전트에는 페이지를 다시 로드한 후 코드 인터프리터 기능이 있습니다.

생성된 그래프를 포함하는 선언적 에이전트의 응답을 보여주는 스크린샷

요청된 그래프를 생성하는 데 사용되는 Python 코드를 보여주는 스크린샷

Copilot 커넥터 콘텐츠 추가

Copilot 커넥터에서 수집한 항목을 에이전트의 사용 가능한 정보에 추가합니다.

  1. 파일을 열고 main.tsp 다음 값을 사용하여 네임스페이스에 MyAgent 기능을 추가 GraphConnectors 하여 Microsoft 365 organization에서 유효한 Copilot 커넥터 ID로 바꿉 policieslocal 니다. Copilot 커넥터 ID를 찾는 방법에 대한 자세한 내용은 선언적 에이전트 매니페스트에 대한 기능 ID 검색을 참조하세요.

    namespace MyAgent {
      // Omitted for brevity
      op copilotConnectors is AgentCapabilities.GraphConnectors<Connections = [
        {
          connectionId: "policieslocal",
        }
      ]>;
      // Omitted for brevity
    }
    

    자세한 내용은 Copilot 커넥터 개체를 참조하세요.

    참고

    배열을 Connections 지정하지 않으면 에이전트는 로그인한 사용자가 액세스할 수 있는 Microsoft 365 organization의 모든 Copilot 커넥터에서 콘텐츠를 가져옵니다.

  2. 에이전트 도구 키트의 수명 주기 창에서 프로비저닝을 선택합니다.

선언적 에이전트는 페이지를 다시 로드한 후 Copilot 커넥터 콘텐츠에 액세스하여 답변을 생성할 수 있습니다.

Copilot 커넥터 콘텐츠가 포함된 선언적 에이전트의 응답을 보여주는 스크린샷

완료됨

Microsoft 365 Copilot에 대한 선언적 에이전트 가이드를 완료했습니다. 이제 TypeSpec을 사용하여 선언적 에이전트를 빌드하는 방법에 익숙해졌으므로 다음 문서에서 자세히 알아볼 수 있습니다.

다음 단계