智能 智能 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 Agents Toolkit 进行编译、预配和发布。 这些程序仍然可用;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 验证所有引用,确保自适应卡的数据正确绑定,并验证所有必需的属性是否存在。 此验证在生成过程中进行,因此您可以立即获得反馈,并且不会预配无效的配置。

示例

下面是演示适用于智能 智能 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 进行构建,请参阅以下资源: