npm package: @microsoft/typespec-m365-copilot
Description: TypeSpec Copilot Skills provides tooling to generate Declarative Agents and their associated Action plugins.
Author: Microsoft Corporation
Latest version: 1.0.0

# TypeSpec for Copilot Skills Libraries

This repository provides a TypeSpec decorator library to enable Copilot skill builders to define their Copilot plugins / Declarative Copilots in TypeSpec. It is defined to be used along with [Kiota](https://github.com/microsoft/kiota) to generate the OpenAPI description and API Plugin manifest files.

TypeSpec is a language for describing cloud service APIs and generating other API description languages, client and service code, documentation, and other assets.

## Contributing

For Contributing steps, see [CONTRIBUTING.md](CONTRIBUTING.md)

# Overview of TypeSpec for Copilot and the basic declarative agent template

## TypeSpec for Copilot
TypeSpec for Copilot is a specialized library that enhances the core TypeSpec language with features specific to Copilot skills. It is designed to generate API configuration files from TypeSpec definitions, which include OpenAPI spec files, as well as the skill’s functions and metadata used to create plugin manifests for AI orchestrators like Sydney.

The architecture of TypeSpec for Copilot is chosen to abstract the author and reviewer from the rapid pace of change of underlying artifacts, providing readable yet expressive syntax, robust validation tooling, and IntelliSense support. This approach simplifies the creation and ongoing updates of Copilot Declarative Agents, reducing the burden on developers and ensuring they stay up to date without excessive effort.

## Build a basic declarative agent

With the declarative agent, you can build a custom version of Copilot that can be used for specific scenarios, such as for specialized knowledge, implementing specific processes, or simply to save time by reusing a set of AI prompts. For example, a grocery shopping Copilot declarative agent can be used to create a grocery list based on a meal plan that you send to Copilot.

## Getting started with TypeSpec

# Set up your development environment

You will need a user with a Copilot license in a tenant that has sufficient permission to side load an agent.

## Installing all dependencies into your own machine

### Ensure SDK is installed

Install the SDK
If you install the SDK, you don't need to install the corresponding runtime.

To install the SDK, follows these steps:
1. Install WinGet
2. Open a terminal, such as PowerShell or Command Prompt.

On Windows, install the SDK with the following command: 
```bash
winget install Microsoft.DotNet.SDK.9
```

On MacOS, install the SDK with the following 
```bash
brew install --cask dotnet-sdk
```

On Linux, install the SDK with the following command:
```bash
sudo apt-get install dotnet-sdk-9
```

### NVM installation

Install NVM on Mac/Linux (https://nvm.sh) or NVM-Windows on Windows (winget install CoreyButler.NVMforWindows). Then, install and use the current recommended Node version (currently 20.12.1).

```bash
nvm install 20.12.1
nvm use 20.12.1
```

### Install TypeSpec and other package dependencies
```
npm install
```

### Install Kiota
1. Install Kiota
```
dotnet tool install Microsoft.OpenApi.Kiota
```

Note: Kiota's preview feature must be enabled in the environment.
```
$Env:KIOTA_CONFIG_PREVIEW = "true"
```

### Install Teams Toolkit (TTK) and TypeSpec Extensions
In the Visual Studio Code Extensions, 
1. Install Teams Toolkit.
    - Once installed, select the TTK from the left-hand menu and add your licensed user account to the Accounts section and sign in.
2. Install TypeSpec for VS Code


### Provisioning and running your agent
1. First, select the Teams Toolkit icon on the left in the VS Code toolbar.
2. In the Account section, sign in with your [Microsoft 365 account](https://docs.microsoft.com/microsoftteams/platform/toolkit/accounts) if you haven't already.
3. Create your app
- Create a teams app by clicking on 'Create a new app'
![Create a new app](image.png)

- Add an action
![Add an action](image-1.png)

- Start with TypeSpec
![Start with TypeSpec](image-2.png)

   Make your edits to the main.tsp file
4. Create Teams app by clicking `Provision` in "Lifecycle" section.
5. Select `Preview in Copilot (Edge)` or `Preview in Copilot (Chrome)` from the launch configuration dropdown.
6. Once the Copilot app is loaded in the browser, click on the "…" menu and select "Copilot chats". You will see your declarative agent on the right rail. Clicking on it will change the experience to showcase the logo and name of your declarative agent.
7. Ask a question to your declarative agent and it should respond based on the instructions provided.
After provisioning the agent for the first time, the agent will appear in the Copilot's right rail under Agents.  You will need to confirm that Copilot is allowed to interact with the API plugin.  If an "Allow" button is not rendered in the Copilot chat dialog, you can type "confirm" when prompted.

### Important Notes
From the TTK, under Lifecycle, click provision to generate your agent artifacts and provision them.  The agent will appear in the https://www.microsoft365.com/chat right rail under Agents.

When updating the agent, a version is added to the title. If the version is incrementing in the Agent title when loading Copilot, uninstall the agent and reprovision.


## Trademarks

This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft 
trademarks or logos is subject to and must follow 
[Microsoft's Trademark & Brand Guidelines](https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general).
Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship.
Any use of third-party trademarks or logos are subject to those third-party's policies.