typespec-create-agent

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Create TypeSpec Declarative Agent

创建TypeSpec声明式Agent

Create a complete TypeSpec declarative agent for Microsoft 365 Copilot with the following structure:

为Microsoft 365 Copilot创建一个完整的TypeSpec声明式Agent，需遵循以下结构：

Requirements

要求

Generate a

main.tsp

file with:

Agent Declaration
- Use
```
@agent
```
  decorator with a descriptive name and description
- Name should be 100 characters or less
- Description should be 1,000 characters or less
Instructions
- Use
```
@instructions
```
  decorator with clear behavioral guidelines
- Define the agent's role, expertise, and personality
- Specify what the agent should and shouldn't do
- Keep under 8,000 characters
Conversation Starters
- Include 2-4
```
@conversationStarter
```
  decorators
- Each with a title and example query
- Make them diverse and showcase different capabilities
Capabilities (based on user needs)
- ```
WebSearch
```
  - for web content with optional site scoping
- ```
OneDriveAndSharePoint
```
  - for document access with URL filtering
- ```
TeamsMessages
```
  - for Teams channel/chat access
- ```
Email
```
  - for email access with folder filtering
- ```
People
```
  - for organization people search
- ```
CodeInterpreter
```
  - for Python code execution
- ```
GraphicArt
```
  - for image generation
- ```
GraphConnectors
```
  - for Copilot connector content
- ```
Dataverse
```
  - for Dataverse data access
- ```
Meetings
```
  - for meeting content access

生成一个

main.tsp

文件，包含：

Agent声明
- 使用
```
@agent
```
  装饰器，包含描述性名称和说明
- 名称长度不超过100个字符
- 说明长度不超过1000个字符
指令
- 使用
```
@instructions
```
  装饰器，定义清晰的行为准则
- 明确Agent的角色、专业能力和个性
- 指定Agent可以做和不可以做的事情
- 内容长度不超过8000个字符
对话起始项
- 包含2-4个
```
@conversationStarter
```
  装饰器
- 每个装饰器包含标题和示例查询语句
- 确保起始项多样化，展示不同的功能
功能配置（基于用户需求）
- ```
WebSearch
```
  - 用于网页内容搜索，支持可选的站点范围限定
- ```
OneDriveAndSharePoint
```
  - 用于访问文档，支持URL过滤
- ```
TeamsMessages
```
  - 用于访问Teams频道/聊天内容
- ```
Email
```
  - 用于访问邮件，支持文件夹过滤
- ```
People
```
  - 用于组织内人员搜索
- ```
CodeInterpreter
```
  - 用于执行Python代码
- ```
GraphicArt
```
  - 用于生成图片
- ```
GraphConnectors
```
  - 用于Copilot连接器内容访问
- ```
Dataverse
```
  - 用于访问Dataverse数据
- ```
Meetings
```
  - 用于访问会议内容

Template Structure

模板结构

typescript

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

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

@agent({
  name: "[Agent Name]",
  description: "[Agent Description]"
})
@instructions("""
  [Detailed instructions about agent behavior, role, and guidelines]
""")
@conversationStarter(#{
  title: "[Starter Title 1]",
  text: "[Example query 1]"
})
@conversationStarter(#{
  title: "[Starter Title 2]",
  text: "[Example query 2]"
})
namespace [AgentName] {
  // Add capabilities as operations here
  op capabilityName is AgentCapabilities.[CapabilityType]<[Parameters]>;
}

typescript

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

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

@agent({
  name: "[Agent Name]",
  description: "[Agent Description]"
})
@instructions("""
  [Detailed instructions about agent behavior, role, and guidelines]
""")
@conversationStarter(#{
  title: "[Starter Title 1]",
  text: "[Example query 1]"
})
@conversationStarter(#{
  title: "[Starter Title 2]",
  text: "[Example query 2]"
})
namespace [AgentName] {
  // Add capabilities as operations here
  op capabilityName is AgentCapabilities.[CapabilityType]<[Parameters]>;
}

Best Practices

最佳实践

Use descriptive, role-based agent names (e.g., "Customer Support Assistant", "Research Helper")
Write instructions in second person ("You are...")
Be specific about the agent's expertise and limitations
Include diverse conversation starters that showcase different features
Only include capabilities the agent actually needs
Scope capabilities (URLs, folders, etc.) when possible for better performance
Use triple-quoted strings for multi-line instructions

使用描述性的、基于角色的Agent名称（例如："Customer Support Assistant"、"Research Helper"）
指令使用第二人称撰写（"你是..."）
明确说明Agent的专业能力和局限性
包含多样化的对话起始项，展示不同功能
仅添加Agent实际需要的功能
尽可能限定功能范围（如URL、文件夹等）以提升性能
多行指令使用三引号字符串

Examples

示例流程

Ask the user:

What is the agent's purpose and role?
What capabilities does it need?
What knowledge sources should it access?
What are typical user interactions?

Then generate the complete TypeSpec agent definition.

询问用户以下问题：

Agent的用途和角色是什么？
它需要哪些功能？
它应该访问哪些知识源？
典型的用户交互场景有哪些？

然后生成完整的TypeSpec Agent定义。