typespec-create-agent

创建 TypeSpec 声明式代理

为 Microsoft 365 Copilot 创建一个完整的 TypeSpec 声明式代理，结构如下：

要求

生成一个 main.tsp 文件，包含：

1. 代理声明

   • 使用 @agent 装饰器，提供描述性名称和描述
   • 名称不超过 100 个字符
   • 描述不超过 1,000 个字符

2. 指令

   • 使用 @instructions 装饰器，提供清晰的行为指南
   • 定义代理的角色、专业知识和个性
   • 指定代理应该做什么和不应该做什么
   • 保持在 8,000 个字符以内

3. 对话启动器

   • 包含 2-4 个 @conversationStarter 装饰器
   • 每个包含标题和示例查询
   • 多样化，展示不同能力

4. 能力（基于用户需求）

   • WebSearch - 用于网页内容，可选站点范围限定
   • OneDriveAndSharePoint - 用于文档访问，支持 URL 过滤
   • TeamsMessages - 用于 Teams 频道/聊天访问
   • Email - 用于电子邮件访问，支持文件夹过滤
   • People - 用于组织人员搜索
   • CodeInterpreter - 用于 Python 代码执行
   • GraphicArt - 用于图像生成
   • GraphConnectors - 用于 Copilot 连接器内容
   • Dataverse - 用于 Dataverse 数据访问
   • Meetings - 用于会议内容访问

模板结构

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

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

@agent({
  name: "[代理名称]",
  description: "[代理描述]"
})
@instructions("""
  [关于代理行为、角色和指南的详细指令]
""")
@conversationStarter(#{
  title: "[启动器标题1]",
  text: "[示例查询1]"
})
@conversationStarter(#{
  title: "[启动器标题2]",
  text: "[示例查询2]"
})
namespace [代理名称] {
  // 在此处添加能力作为操作
  op capabilityName is AgentCapabilities.[能力类型]<[参数]>;
}

最佳实践

• 使用描述性的、基于角色的代理名称（例如，“客户支持助手”、“研究助手”）
• 以第二人称编写指令（“你是……”）
• 明确代理的专业知识和限制
• 包含多样化的对话启动器，展示不同功能
• 只包含代理实际需要的能力
• 尽可能限定能力范围（URL、文件夹等）以获得更好性能
• 对多行指令使用三引号字符串

示例

询问用户：

1. 代理的目的和角色是什么？
2. 它需要哪些能力？
3. 它应该访问哪些知识源？
4. 典型的用户交互是什么？

然后生成完整的 TypeSpec 代理定义。