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 功能名稱 is AgentCapabilities.[功能類型]<[參數]>;
}

最佳做法

• 使用描述性、基於角色的代理程式名稱（例如「客戶支援助理」、「研究幫手」）
• 以第二人稱撰寫指令（「你是……」）
• 具體說明代理程式的專業領域與限制
• 包含多樣的對話起手式，展示不同功能
• 僅包含代理程式實際需要的功能
• 盡可能限定功能範圍（URL、資料夾等）以獲得較佳效能
• 使用三重引號字串處理多行指令

範例

詢問使用者：

1. 代理程式的目的與角色是什麼？
2. 需要哪些功能？
3. 應存取哪些知識來源？
4. 典型的使用者互動是什麼？

然後產生完整的 TypeSpec 代理程式定義。