Microsoft 365 Copilot 的 TypeSpec 概觀

TypeSpec for Microsoft 365 Copilot 是一種網域特定語言 (DSL) ,可用來建立具有乾淨、富有表現力的語法的宣告式代理程式和 API 外掛程式。 這種特殊語言以 TypeSpec 為基礎而建置,提供 Microsoft 365 特定的裝飾器和功能,以簡化延伸 Microsoft 365 Copilot 的開發程序。 TypeSpec 可作為手動編寫 JSON 資訊清單檔案的替代方案,提供對開發人員更友善的方法,並具有更高的生產力和可維護性。

適用於 Microsoft 365 Copilot 的 TypeSpec 針對複雜的 JSON 結構描述和 OpenAPI 檔案提供高階抽象層。 該語言會自動產生所需的資訊清單檔案和配置,從而減少開發時間並最大限度地減少錯誤。 有了 IntelliSense 支援、類型安全性和全面驗證,您可以專注於代理程式的行為,而非設定詳細資料。

秘訣

推薦項目: 從 Work IQ 開發工具 開始,支援專業程式碼宣告式代理程式和外掛程式案例。 請參閱 WIQD 快速入門。 工具組式指示仍然適用於需要工具組的指示的現有專案和工作流程。 在選擇工具之前,請先檢查 功能和目標體驗支援 : WIQD 不會以自訂引擎代理程式為目標。

類型安全性和開發人員體驗

適用於 Microsoft 365 Copilot 的 TypeSpec 提供強型別開發體驗,可在編譯時間而非執行階段擷取錯誤。 該語言包含所有 Microsoft 365 Copilot 特定建構的全面類型檢查,確保您的宣告式代理程式和 API 外掛程式在您佈建之前已正確設定。 此類型安全性延伸至代理程式定義的所有層面,從基本中繼資料到複雜的功能組態和 API 作業定義。

Visual Studio Code 和 Visual Studio 的 IntelliSense 支援提供即時意見反應、自動完成和內嵌文件。 本文件中的 TypeSpec 逐步解說使用 Microsoft 365 代理程式工具組進行編譯、佈建和發佈。 這些程序仍然可用;WIQD 建議並不表示 WIQD 支援相同的 TypeSpec 工作流程。 錯誤訊息清晰且可操作,幫助您在開發過程中快速識別和解決問題。

簡化代理程式和外掛程式製作

TypeSpec 透過用直覺的、基於裝飾器的語法替換冗長的 JSON 配置,簡化了建立宣告式代理程式和 API 外掛程式的過程。 您可以使用語意裝飾器(如 @agent、 @instructions和 @capabilities )來定義代理程式,而不是手動製作複雜的資訊清單檔案。 這種方法降低了配置錯誤的可能性,並使程式碼庫更具可維護性和可讀性。

在處理複雜的 API 介面時,TypeSpec 有助於解決傳統 OpenAPI 檔案變得笨重且難以管理的問題。 具有數百個端點、複雜巢狀架構和複雜身份驗證模式的大型 OpenAPI 規範可能難以編寫、維護和理解。 TypeSpec 透過提供自動產生底層 OpenAPI 規範的更高層級抽象來解決這些痛點。 您可以專注於使用 TypeSpec 的表達語法定義業務邏輯和 API 行為,而編譯器則處理 OpenAPI 合規性、架構驗證和交叉引用管理的詳細資訊。

此語言為所有 Microsoft 365 Copilot 功能提供內建裝飾器,包括 Web 搜尋、OneDrive 和 SharePoint 整合、Teams 訊息、程式碼解譯器等。 API 外掛程式受益於自動 OpenAPI 規格產生,其中 TypeSpec 作業會轉換為 REST API 定義。 這種自動化消除了維護單獨 API 文檔的需要,並確保 TypeSpec 定義和產生的 API 合約之間的一致性。

自動資訊清單產生和驗證

適用於 Microsoft 365 Copilot 的 TypeSpec 會自動從您的 TypeSpec 定義產生有效的資訊清單檔案。 語言編譯器會分析您的 TypeSpec 程式碼,並為宣告式代理程式和 API 外掛程式產生適當的 JSON 資訊清單,確保它們符合最新的架構要求。 此產生過程包括全面的驗證,在常見配置錯誤到達生產環境之前捕獲它們。

自動產生不僅限於基本資訊清單建立,還包含複雜的組態,例如調適型卡片、驗證設定和功能特定的中繼資料。 TypeSpec 會驗證所有參照、確保自適性卡片的資料繫結正確,並驗證所有必要的屬性都存在。 此驗證會在建置過程中發生,因此您可以立即獲得意見反應,而不會佈建無效的設定。

範例

以下是示範 TypeSpec for Microsoft 365 Copilot 語法的實際範例:

基本宣告式代理程式

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 進行建置,請參閱下列資源: