Microsoft 365 Copilot에 대한 TypeSpec 에이전트 시나리오

팁

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

이 가이드에서는 간단한 기본 에이전트부터 여러 기능 및 인증 방법을 사용하는 복잡한 구현에 이르기까지 Microsoft 365 Copilot용 TypeSpec 에이전트를 만드는 전체 예제를 제공합니다.

기능이 없는 기본 에이전트

사용 사례: 외부 통합이나 특수 기능 없이 기본 정보와 인사말을 제공하는 간단한 에이전트입니다.

수행하는 작업: 이 에이전트는 간단한 질문에 답변하고, 일반 정보를 제공하며, 기본적인 대화를 할 수 있습니다. 외부 API에 액세스하거나, 웹을 검색하거나, Microsoft 365 데이터에 액세스할 필요가 없습니다.

import "@typespec/http";
import "@typespec/openapi3";
import "@microsoft/typespec-m365-copilot";

using TypeSpec.Http;
using TypeSpec.M365.Copilot.Agents;

@agent("Basic Helper Agent", "A simple agent that provides basic information and assistance")
@instructions("""
  You are a helpful assistant that provides basic information and support.
  Be friendly, professional, and helpful in all interactions. Provide clear,
  concise answers to user questions. If you don't know something, be honest
  about your limitations and suggest alternative ways to find the information.
""")
namespace BasicHelperAgent {
  // No capabilities defined - agent relies only on built-in conversational abilities
}

여러 기능을 갖춘 에이전트

사용 사례: 웹에서 정보를 검색하고, organization의 SharePoint 콘텐츠에 액세스하고, organization에 있는 동료에 대한 정보를 찾을 수 있는 지식 근로자 도우미입니다.

수행하는 작업: 이 에이전트는 외부 정보에 대한 웹 검색, 문서 검색을 위한 파일 액세스, 동료 찾기 및 연락처 정보 검색을 결합하여 지식 근로자를 지원합니다. 이 패턴은 연구 및 공동 작업 시나리오에 적합합니다.

import "@typespec/http";
import "@typespec/openapi3";
import "@microsoft/typespec-m365-copilot";

using TypeSpec.Http;
using TypeSpec.M365.Copilot.Agents;

@agent("Knowledge Worker Assistant", "An intelligent assistant that helps with research, file management, and finding colleagues")
@instructions("""
  You are a knowledgeable research assistant specialized in helping knowledge workers
  find information efficiently. You can search the web for external research, access
  SharePoint documents for organizational content, and help locate colleagues within
  the organization. Always provide comprehensive research results, cite your sources,
  and suggest additional resources when relevant. When searching for people, respect
  privacy and only share publicly available organizational information.
""")
namespace KnowledgeWorkerAgent {
  // Web search capability for external research
  op webSearch is AgentCapabilities.WebSearch<Sites = [
    {
      url: "https://learn.microsoft.com";
    },
    {
      url: "https://www.microsoft.com";
    }
  ]>;

  // OneDrive and SharePoint access for document retrieval
  op oneDriveAndSharePoint is AgentCapabilities.OneDriveAndSharePoint<
    ItemsByUrl = [
      { url: "https://contoso.sharepoint.com/sites/IT" }
    ]
  >;

  // People search for finding colleagues
  op people is AgentCapabilities.People;
}

익명 API 작업을 사용하는 간단한 에이전트

사용 사례: 사용자가 공공 수리 API를 사용하여 유지 관리 문제를 보고하고 추적하는 데 도움이 되는 시설 관리 에이전트입니다.

수행하는 작업: 이 에이전트를 사용하면 사용자가 시설 문제(장비 고장, 조명 문제 등)를 보고하고 기존 수리 요청의 상태를 검사할 수 있습니다. 수리 API는 공개적으로 액세스할 수 있고 인증이 필요하지 않으므로 누구나 쉽게 문제를 보고할 수 있습니다.

import "@typespec/http";
import "@typespec/openapi3";
import "@microsoft/typespec-m365-copilot";
import "./actions.tsp";

using TypeSpec.Http;
using TypeSpec.M365.Copilot.Agents;
using TypeSpec.M365.Copilot.Actions;

@agent("Facilities Repair Agent", "Report and track facility maintenance issues and repair requests")
@instructions("""
  You are a facilities management assistant that helps employees report and track
  maintenance issues. You can help users submit new repair requests by gathering
  all necessary details (description, location, category, priority) and submit
  them to the facilities team. You can also check the status of existing repair
  tickets and provide updates on progress. Always be helpful in categorizing
  issues correctly and setting appropriate priority levels based on safety and
  business impact.
""")
namespace FacilitiesRepairAgent {
  op reportIssue is RepairsAPI.reportIssue;
  op getRepairStatus is RepairsAPI.getRepairStatus;
  op getOpenRepairs is RepairsAPI.getOpenRepairs;
}

API 키 인증을 사용하는 고급 에이전트

사용 사례: API 키 인증과 함께 공개적으로 사용 가능한 API를 사용하여 팀이 시설 유지 관리 작업을 추적하고 관리하는 데 도움이 되는 수리 관리 에이전트입니다.

수행하는 작업: 이 에이전트는 유지 관리 팀을 위한 포괄적인 복구 관리 기능을 제공합니다. 수리 작업을 나열, 생성, 업데이트 및 삭제하고, 담당자 또는 설명별로 수리를 필터링하고, 이미지가 포함된 풍부한 카드 기반 응답을 제공할 수 있습니다. API 키 인증은 실제 API 통합 패턴을 보여주는 동시에 수리 관리 시스템에 대한 제어된 액세스를 보장합니다.

import "@typespec/http";
import "@typespec/openapi3";
import "@microsoft/typespec-m365-copilot";
import "./actions.tsp";

using TypeSpec.Http;
using TypeSpec.M365.Copilot.Agents;
using TypeSpec.M365.Copilot.Actions;

@agent("Repairs Hub Agent", "Smart repair management agent for tracking and coordinating facility maintenance tasks")
@instructions("""
  You are a specialized repairs management assistant that helps teams efficiently track,
  organize, and coordinate facility maintenance tasks. You excel at managing repair
  workflows including creating detailed repair tickets, assigning tasks to team members,
  tracking progress, and providing status updates. You can filter repairs by various
  criteria such as assignee, keywords in descriptions, or completion status. Always
  provide clear, organized information using tables and cards when displaying repair
  data. When creating repairs, gather all necessary details and confirm the information
  before submission. Help prioritize urgent repairs and ensure proper task assignment
  for optimal team productivity.
""")
@conversationStarter(#{
  title: "List repairs",
  text: "List all repairs"
})
@conversationStarter(#{
  title: "List Karin's repairs",
  text: "List all repairs assigned to Karin"
})
@conversationStarter(#{
  title: "Find oil repairs",
  text: "List all repairs that are about oil"
})
@conversationStarter(#{
  title: "Create repair",
  text: "Create a new repair and assign it to me"
})
namespace RepairsAgent {
  // Repair management operations
  op listRepairs is RepairsHub.listRepairs;
  op createRepair is RepairsHub.createRepair;
  op updateRepair is RepairsHub.updateRepair;
  op deleteRepair is RepairsHub.deleteRepair;
}

OAuth2 및 GitHub API 통합을 사용하는 복잡한 에이전트

사용 사례: 개발 팀이 GitHub 리포지토리를 관리하고, 문제를 추적하고, 풀 요청을 관리하고, GitHub의 포괄적인 API를 사용하여 프로젝트 활동을 조정하는 데 도움이 되는 프로젝트 관리 에이전트입니다.

하는 일: 이 에이전트는 GitHub와 통합되어 개발 팀이 워크플로를 간소화할 수 있도록 돕는 프로젝트 관리 도우미 역할을 합니다. 문제를 생성 및 관리하고, 끌어오기 요청을 검토 및 병합하고, 프로젝트 마일스톤을 추적하고, 리포지토리 활동에 대한 통찰력을 제공할 수 있습니다. OAuth2 인증은 적절한 권한을 가진 GitHub 리포지토리에 대한 안전한 액세스를 보장하므로 팀이 자연어 상호 작용을 통해 프로젝트를 효율적으로 관리할 수 있습니다.

import "@typespec/http";
import "@typespec/openapi3";
import "@microsoft/typespec-m365-copilot";
import "./actions.tsp";

using TypeSpec.Http;
using TypeSpec.M365.Copilot.Agents;
using TypeSpec.M365.Copilot.Actions;

@agent("GitHub Project Manager", "Smart project management agent with GitHub integration for issue tracking, pull request management, and project coordination")
@instructions("""
  You are an intelligent project management assistant specialized in GitHub workflows
  and development team coordination. You excel at managing GitHub repositories including
  creating and tracking issues, reviewing pull requests, coordinating project milestones,
  and providing insights about development activity. You can help prioritize work,
  track progress, manage code reviews, and facilitate team collaboration through GitHub's
  project management features. Always consider development best practices, help maintain
  code quality through proper review processes, and provide actionable insights to
  improve team productivity and project delivery.
""")
namespace GitHubProjectManager {
  // GitHub API operations for project management
  op createIssue is GitHubAPI.createIssue;
  op getIssues is GitHubAPI.getIssues;
  op updateIssue is GitHubAPI.updateIssue;
  op getPullRequests is GitHubAPI.getPullRequests;
  op createPullRequest is GitHubAPI.createPullRequest;
  op mergePullRequest is GitHubAPI.mergePullRequest;
  op getProjectInsights is GitHubAPI.getProjectInsights;
}

요약​​

다음 예제에서는 간단한 TypeSpec 에이전트에서 복잡한 TypeSpec 에이전트로의 진행 상황을 보여 줍니다.

각 예제는 이전 예제를 기반으로 하며, 기능, 인증 및 사용자 지정 작업을 추가하여 실제 시나리오에 대한 더 복잡한 에이전트를 만드는 방법을 보여줍니다.