通过

TypeSpec for Microsoft 365 Copilot 概述

重要

适用于 Microsoft 365 Copilot 的 TypeSpec 处于预览状态，仍可能发生中断性变更。 适用于 Microsoft 365 Copilot 的 TypeSpec 的当前版本为 1.0.0-rc.5。

TypeSpec for Microsoft 365 Copilot 是一种功能强大的特定于域的语言， (DSL) ，使开发人员能够使用简洁的表达语法创建声明性代理和 API 插件。 这种专用语言以 TypeSpec 为基础，提供Microsoft 365 种特定修饰器和功能，可简化扩展 Microsoft 365 Copilot 的开发过程。 TypeSpec 是手动创作 JSON 清单文件的替代方法，提供了一种更便于开发人员使用的方法，同时提高了工作效率和可维护性。

TypeSpec for Microsoft 365 Copilot 通过针对复杂 JSON 架构和 OpenAPI 文件提供高级抽象层来转换开发人员构建 Copilot 扩展性解决方案的方式。 该语言自动生成所需的清单文件和配置，从而减少开发时间并最大程度地减少错误。 凭借丰富的 IntelliSense 支持、类型安全性和全面的验证，TypeSpec 使开发人员能够专注于构建创新的 AI 支持体验，而不是与配置细节搏斗。

类型安全性和开发人员体验

typeSpec for Microsoft 365 Copilot 提供强类型开发体验，在编译时而不是运行时捕获错误。 该语言包括对所有 Microsoft 365 Copilot 特定构造进行全面的类型检查，确保在部署之前正确配置声明性代理和 API 插件。 此类型安全性扩展到代理定义的所有方面，从基本元数据到复杂的功能配置和 API作定义。

通过 Visual Studio Code 和 Visual Studio 中丰富的 IntelliSense 支持来增强开发人员体验，提供实时反馈、自动完成和内联文档。 该语言与 Microsoft 365 代理工具包无缝集成，提供从创建到部署的完整开发工作流。 错误消息清晰且可作，可帮助开发人员在开发过程中快速识别和解决问题。

简化的代理和插件创作

TypeSpec 通过将详细 JSON 配置替换为基于修饰器的直观语法，极大地简化了创建声明性代理和 API 插件的过程。 开发人员可以使用 、 和 @capabilities 等@agent@instructions语义修饰器来定义其代理，而不是手动创建复杂的清单文件。 此方法可降低配置错误的可能性，并使代码库更易于维护和可读。

使用复杂的 API 图面时，TypeSpec 会让传统 OpenAPI 文件变得笨拙且难以管理。 具有数百个终结点、复杂嵌套架构和复杂身份验证模式的大型 OpenAPI 规范可能难以创作、维护和理解。 TypeSpec 通过提供自动生成基础 OpenAPI 规范的更高级别抽象来解决这些难题。 开发人员可以专注于使用 TypeSpec 的表达语法定义业务逻辑和 API 行为，而编译器则处理 OpenAPI 合规性、架构验证和交叉引用管理的繁琐详细信息。

该语言为所有 Microsoft 365 Copilot 功能提供内置修饰器，包括 Web 搜索、OneDrive 和 SharePoint 集成、Teams 消息、代码解释器等。 API 插件受益于自动 OpenAPI 规范生成，其中 TypeSpec作可无缝转换为 REST API 定义。 这种自动化无需维护单独的 API 文档，并确保 TypeSpec 定义与生成的 API 协定之间的一致性。

自动生成和验证清单

TypeSpec for Microsoft 365 Copilot 的最强大功能之一是它能够从 TypeSpec 定义自动生成有效的清单文件。 语言编译器分析 TypeSpec 代码，并为声明性代理和 API 插件生成相应的 JSON 清单，确保它们符合最新的架构要求。 此生成过程包括全面验证，在常见配置错误到达生产环境之前捕获这些错误。

自动生成超出了基本清单创建的范围，包括复杂的配置，例如自适应卡、身份验证设置和特定于功能的元数据。 TypeSpec 验证所有引用，确保自适应卡的正确数据绑定，并验证是否存在所有必需的属性。 此验证在生成过程中进行，为开发人员提供即时反馈，并防止部署无效配置。

示例

下面是演示 typeSpec for Microsoft 365 Copilot 语法的实用示例：

基本声明性代理

@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://free.blessedness.top"
    }
  ]>;

  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 Microsoft.M365Copilot;

@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;
}

入门

准备好开始使用 TypeSpec for Microsoft 365 Copilot 生成了吗？ 请按照下列步骤操作：

相关内容