Microsoft 365 Copilot용 TypeSpec 개요

Microsoft 365 Copilot용 TypeSpec은 클린하고 표현력이 풍부한 구문으로 선언적 에이전트 및 API 플러그 인을 만드는 데 사용할 수 있는 DSL(도메인 특정 언어)입니다. TypeSpec을 기반으로 구축된 이 특수 언어는 Microsoft 365 Copilot을 확장하기 위한 개발 프로세스를 간소화하는 Microsoft 365 특정 데코레이터 및 기능을 제공합니다. TypeSpec은 JSON 매니페스트 파일을 수동으로 작성하는 대안으로 사용되며, 향상된 생산성과 유지 관리 가능성으로 보다 개발자 친화적인 접근 방식을 제공합니다.

Microsoft 365 Copilot용 TypeSpec은 복잡한 JSON 스키마 및 OpenAPI 파일에 대한 고급 추상화 계층을 제공합니다. 이 언어는 필요한 매니페스트 파일과 구성을 자동으로 생성하여 개발 시간을 줄이고 오류를 최소화합니다. IntelliSense 지원, 형식 안전성 및 포괄적인 유효성 검사를 통해 구성 세부 정보보다는 에이전트의 동작에 집중할 수 있습니다.

팁

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

형식 안전 및 개발자 환경

Microsoft 365 Copilot용 TypeSpec은 런타임이 아닌 컴파일 타임에 오류를 catch하는 강력한 형식의 개발 환경을 제공합니다. 이 언어에는 모든 Microsoft 365 Copilot 관련 구문에 대한 포괄적인 형식 검사가 포함되어 있어 프로비전하기 전에 선언적 에이전트 및 API 플러그 인이 올바르게 구성되었는지 확인합니다. 이러한 유형 안전성은 기본 메타데이터에서 복잡한 기능 구성 및 API 작업 정의에 이르기까지 에이전트 정의의 모든 측면으로 확장됩니다.

Visual Studio Code 및 Visual Studio의 IntelliSense 지원은 실시간 피드백, 자동 완성 및 인라인 설명서를 제공합니다. 이 설명서의 TypeSpec 연습에서는 컴파일, 프로비전 및 게시에 Microsoft 365 에이전트 도구 키트를 사용합니다. 이러한 절차는 계속 사용할 수 있습니다. WIQD 권장 사항은 WIQD가 동일한 TypeSpec 워크플로를 지원함을 의미하지는 않습니다. 오류 메시지는 명확하고 실행 가능하므로 개발 중에 문제를 신속하게 식별하고 resolve 수 있습니다.

간소화된 에이전트 및 플러그인 작성

TypeSpec은 자세한 JSON 구성을 직관적인 데코레이터 기반 구문으로 대체하여 선언적 에이전트 및 API 플러그인을 만드는 프로세스를 단순화합니다. 복잡한 매니페스트 파일을 수동으로 만드는 대신 , , @instructions및 @capabilities 같은 @agent의미 체계 데코레이터를 사용하여 에이전트를 정의할 수 있습니다. 이 방법을 사용하면 구성 오류의 가능성이 줄어들고 코드베이스를 유지 관리하고 읽기 쉽게 만들 수 있습니다.

복잡한 API 표면으로 작업할 때 TypeSpec은 기존 OpenAPI 파일이 다루기 힘들고 관리하기 어려운 곳에서 도움을 줍니다. 수백 개의 엔드포인트, 복잡하게 중첩된 스키마 및 복잡한 인증 패턴이 있는 대규모 OpenAPI 사양은 작성, 유지 관리 및 이해가 어려울 수 있습니다. TypeSpec은 기본 OpenAPI 사양을 자동으로 생성하는 상위 수준의 추상화를 제공하여 이러한 문제점을 해결합니다. 컴파일러는 OpenAPI 준수, 스키마 유효성 검사 및 상호 참조 관리의 세부 정보를 처리하는 동안 TypeSpec의 표현 구문을 사용하여 비즈니스 논리 및 API 동작을 정의하는 데 집중할 수 있습니다.

이 언어는 웹 검색, OneDrive 및 SharePoint 통합, Teams 메시지, 코드 인터프리터 등을 포함한 모든 Microsoft 365 Copilot 기능에 대한 기본 제공 데코레이터를 제공합니다. API 플러그인은 TypeSpec 작업이 REST API 정의로 변환되는 자동 OpenAPI 사양 생성의 이점을 활용합니다. 이 자동화를 통해 별도의 API 문서를 유지할 필요가 없고 TypeSpec 정의와 결과 API 계약 간의 일관성이 보장됩니다.

자동 매니페스트 생성 및 유효성 검사

Microsoft 365 Copilot용 TypeSpec은 TypeSpec 정의에서 유효한 매니페스트 파일을 자동으로 생성합니다. 언어 컴파일러는 TypeSpec 코드를 분석하고 선언적 에이전트 및 API 플러그인에 대한 적절한 JSON 매니페스트를 생성하여 최신 스키마 요구 사항을 준수하는지 확인합니다. 이 생성 프로세스에는 포괄적인 유효성 검사가 포함되어 일반적인 구성 오류가 프로덕션에 도달하기 전에 이를 포착합니다.

자동 생성은 기본적인 매니페스트 만들기를 넘어 적응형 카드, 인증 설정 및 기능별 메타데이터와 같은 복잡한 구성을 포함합니다. TypeSpec은 모든 참조의 유효성을 검사하고, 적응형 카드에 대한 적절한 데이터 바인딩을 보장하고, 모든 필수 속성이 있는지 확인합니다. 이 유효성 검사는 빌드 프로세스 중에 수행되므로 즉시 피드백을 받고 잘못된 구성을 프로비전하지 않습니다.

예제

다음은 Microsoft 365 Copilot 구문에 대한 TypeSpec을 보여주는 실제 예제입니다.

기본 선언적 에이전트

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

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

@agent(
  "Customer Support Assistant",
  "An AI agent that helps with customer support inquiries and ticket management"
)
@instructions("""
  You are a customer support specialist. Help users with their inquiries,
  provide troubleshooting steps, and escalate complex issues when necessary.
  Always maintain a helpful and professional tone.
""")
@conversationStarter(#{
  title: "Check Ticket Status",
  text: "What's the status of my support ticket?"
})
namespace CustomerSupportAgent {
  // Agent capabilities defined here
}

기능을 갖춘 에이전트

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

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

@agent(
  "Multi-Capability Assistant",
  "An AI agent that can search the web, access SharePoint content, and execute Python code"
)
@instructions("""
  You are a versatile assistant that can help users with research, data analysis, and document management.
  Use web search for current information, access SharePoint for company documents, and execute Python code for calculations and data analysis.
  Always provide clear explanations of your findings and methodology.
""")
namespace MyAgent {
  op webSearch is AgentCapabilities.WebSearch<Sites = [
    {
      url: "https://learn.microsoft.com"
    }
  ]>;

  op oneDriveSearch is AgentCapabilities.OneDriveAndSharePoint<
   ItemsByUrl = [
      {
        url: "https://contoso.sharepoint.com/sites/projects"
      }
    ]
  >;

  op codeInterpreter is AgentCapabilities.CodeInterpreter;
}

작업이 포함된 API 플러그인

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

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

@agent(
  "Project Management Assistant",
  "An AI agent that helps manage projects and tasks through API operations"
)
@instructions("""
  You are a project management assistant that helps users create, track, and manage projects.
  Use the available API operations to list projects, get project details, and create new projects.
  Always provide clear status updates and help users organize their work effectively.
""")
@service
@server("https://api.contoso.com")
@actions(#{
  nameForHuman: "Project Management API",
  descriptionForHuman: "Manage projects and tasks",
  descriptionForModel: "API for creating, updating, and tracking project tasks"
})
namespace ProjectAPI {
  model Project {
    id: string;
    name: string;
    description?: string;
    status: "active" | "completed" | "on-hold";
    createdDate: utcDateTime;
  }

  model CreateProjectRequest {
    name: string;
    description?: string;
    status?: "active" | "on-hold";
  }

  @route("/projects")
  @get op listProjects(): Project[];

  @route("/projects/{id}")
  @get op getProject(@path id: string): Project;

  @route("/projects")
  @post op createProject(@body project: CreateProjectRequest): Project;
}

시작하기

Microsoft 365 Copilot용 TypeSpec을 사용하여 빌드를 시작하려면 다음 리소스를 참조하세요.