Typespec Create Agent

Create TypeSpec declarative agent

GitHub Copilot uses this skill to generate a main.tsp file for a Microsoft 365 Copilot declarative agent by translating the user's purpose, knowledge sources, and interaction examples into TypeSpec decorators and scoped AgentCapabilities operations.

When to invoke

• "Create a TypeSpec declarative agent."
• "Generate main.tsp for a Microsoft 365 Copilot agent."
• "Add WebSearch and OneDrive capabilities to an agent."
• "Scaffold a TypeSpec M365 Copilot declarative agent."

Inputs

Ask or infer these facts before writing main.tsp:

TypeSpec structure

Generate one main.tsp file with these pieces:

Capability selection

Template

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] {
  op capabilityName is AgentCapabilities.[CapabilityType]<[Parameters]>;
}

Authoring rules

• Use descriptive role-based agent names such as Customer Support Assistant or Research Helper.
• Write instructions in second person: "You are...".
• Be specific about expertise, limitations, escalation, data sources, and unsupported tasks.
• Include 2-4 conversation starters that showcase different capabilities rather than duplicates.
• Use triple-quoted strings for multi-line instructions.
• Scope capabilities for performance and least privilege.
• Do not include broad capabilities just because they exist.

Gotchas

• Agent names and namespace identifiers are different: the display name may contain spaces, but the namespace must be a valid TypeSpec identifier.
• Broad knowledge sources reduce quality: scoped WebSearch, OneDriveAndSharePoint, TeamsMessages, and Email capabilities are usually better than unbounded access.
• Conversation starters are examples, not tests: they should be realistic user prompts and cover the agent's primary use cases.

Output template

## TypeSpec declarative agent

**Status:** generated | needs input | blocked
**File:** `main.tsp`
**Agent name:** <display name>
**Namespace:** <TypeSpec namespace>

### Capabilities
| Operation | AgentCapabilities type | Scope |
| --- | --- | --- |
| `<operation>` | `<CapabilityType>` | `<parameters or none>` |

### Conversation starters
- `<title>` — `<text>`

### Validation
- Name length: <pass/fail>
- Description length: <pass/fail>
- Instructions length: <pass/fail>

Quality gate

• main.tsp includes the three required imports and two required using statements.
• @agent has a descriptive name no longer than 100 characters and description no longer than 1,000 characters.
• @instructions defines role, expertise, personality, allowed behavior, and limits in fewer than 8,000 characters.
• The file includes 2-4 diverse @conversationStarter decorators.
• Capabilities are limited to actual user needs and scoped when possible.
• The namespace is a valid TypeSpec identifier.