Exercise - Create your first connector project

Completed

In this exercise, you'll use the Microsoft 365 Agents Toolkit in VS Code to generate a starter connector project and explore its structure.

Learning objective

Scaffold a new Microsoft 365 Copilot connector project using the Microsoft 365 Agents Toolkit, provide a project name, and observe the created files including default schema and code.

Scenario

You need to create a baseline connector project that can be customized to connect to GitHub issues. You'll use the Microsoft 365 Agents Toolkit's scaffolding capabilities to create a project with all the necessary structure and sample code.

Task 1: Create a new Copilot connector project

Use the Microsoft 365 Agents Toolkit to generate a new connector project.

1. Open Visual Studio Code.

2. In the Activity Bar (sidebar), select the Microsoft 365 Agents Toolkit extension icon.

3. In the Microsoft 365 Agents Toolkit panel, select Create a New Agent/App.

   

4. When prompted to choose a project type, select Copilot connector.

   

5. Enter GitHub Issues Connector as the connector name when prompted.

6. For the connector ID, enter a unique identifier that follows the requirements:

   • Must be between 3-32 characters
   • Can only contain alphanumeric characters and underscores
   • Must be unique within your tenant

   Example: github_issues_connector_001

7. When prompted for the folder location, select Default folder or browse to your preferred location.

8. Wait for the project scaffolding to complete. VS Code will create the project and open it automatically.

Task 2: Explore the project structure

Now examine the files that were generated to understand the connector architecture.

1. In the Explorer pane, expand the project folders to see the structure.

2. Explore the key folders and files:

   File/Folder	Description
   /src/custom/	Contains customizable logic for integrating with external data sources, transforming items, and defining access control. This is where you adapt the connector to your specific data and business rules.
   /src/models	Defines TypeScript interfaces and data models used throughout the project, ensuring type safety and consistent data structures.
   /src/models/Config.ts	TypeScript interface defining the configuration structure for the entire connector application. Add new configuration properties like API endpoints, feature flags, caching settings, or authentication parameters.
   /src/models/Item.ts	TypeScript interface representing the internal data model for items retrieved from the source system. Add new fields (tags, priority, categories, custom metadata) or modify properties to match your source system's structure.
   /src/references/	Stores static reference files such as the Microsoft Graph connector schema and Adaptive Card templates, which define how data is structured and displayed in Microsoft 365.
   config.ts	Initializes and validates configuration settings from environment variables for the Copilot connector. Add custom validation logic in validateConfig() or initialization logic in initConfig() for extra parameters or rules.
   ingest.ts	Orchestrates content ingestion by fetching items from the data source and loading them into Microsoft Graph one by one. Replace single-item loading with batch API calls, add custom error handling, or implement different ingestion strategies.

3. In addition to those folders, other parts of the code might be customized depending on the scenario. You can search the code for comments starting with the [Customization point] string, which indicate areas for customization.

Task 3: Initial project setup verification

Verify that your development environment is ready to work with the connector.

1. Open the Terminal in VS Code (Terminal > New Terminal).

2. Ensure you're in the project directory and check if dependencies are installed:

   npm list
   

3. If dependencies aren't installed, run:

   npm install
   

4. Verify that the Microsoft 365 Agents Toolkit is connected to your accounts:

   • In the Microsoft 365 Agents Toolkit panel, check the Accounts section
   • Ensure you're signed in to your Microsoft 365 tenant
   • Ensure you're signed in to your Azure subscription

5. If not connected, use the Sign in links in the Accounts section to authenticate.

What you've accomplished

You've successfully created a baseline connector project using the Microsoft 365 Agents Toolkit. Your project now has:

• Complete project structure with all necessary files and folders
• Default sample code that demonstrates connector patterns
• Configuration files ready for customization
• Schema definitions that define how data will be structured in Microsoft Graph
• Development environment verified and ready for customization

By completing these steps, you’ve successfully created a foundation for your Copilot connector. You have:

• A Microsoft 365 Copilot connector ready in VS Code with all necessary files.

• An understanding of the default content and where you’ll plug in your own logic.

In the next exercise, you'll configure this connector to connect to a specific GitHub repository and customize it to work with real GitHub issues data.