microsoft/Custom-Copilot-Connector-using-Connector-SDK

microsoft/Custom-Copilot-Connector-using-Connector-SDK

Description: This June 2026 Custom Copilot Connector Template (SDK-based) update includes preview enhancements for better Copilot Search and Chat results, including property descriptions for richer schema context, expanded semantic labels for improved intent understanding, and Principal/PrincipalCollection support for people fields. (342 chars)

Language: C#

License: MIT

Stars: 1

Forks: 2

Open issues: 9

Created: 2026-06-25T11:45:08Z

Pushed: 2026-09-17T07:36:13Z

Default branch: main

Fork: no

Archived: no

README:

Custom Copilot Connector Template (SDK-based · Preview)

A ready-to-use template for building custom Microsoft 365 Copilot connectors on the Graph Connectors SDK. Clone it to get a working gRPC connector you fill in for your own data source — schema definition, crawl/ingestion, and enrichment already wired up following current best practices. It runs with the Microsoft Graph Connector Agent (GCA).

It also shows how to adopt the June 2026 preview schema enhancements that improve response quality in Copilot Search and Chat:

• Property descriptions — describe each schema property so Copilot better understands its meaning and grounds answers more accurately.
• Expanded semantic labels — richer schema annotation so Copilot infers intent and relationships, improving ranking and answer quality.
• `Principal` / `PrincipalCollection` people types — model people fields (Owner, AssignedTo, Author, CreatedBy) so Copilot understands identity and improves attribution in responses.

> Note: These are preview capabilities (June 2026) and may change before general availability.

Prerequisites

This template requires the latest version of the Microsoft Graph Connectors SDK. See the custom connector SDK overview for how to get it.

Preview Changes In This Version

This preview introduces support for two people/identity property types:

New property types added

| Type | SourcePropertyType | Why this helps | |---|---|---| | Principal | SourcePropertyType.Principal | Model a single person (for example owner/author) so Search can resolve identity context accurately. | | PrincipalCollection | SourcePropertyType.PrincipalCollection | Model multiple people (for example approvers/reviewers) so users can discover and filter content by participant identities. |

ScdPrincipal fields (none of the fields are mandatory; add fields based on your principal property requirements)

• externalName, externalId, entraDisplayName, entraId, email, upn, tenantId

New semantic labels added

AssignedToPeople, ClosedBy, ClosedDate, Priority, SprintName, Tags, Severity, State, DueDate, ItemParentId, ItemPath, ItemType, NumReactions, ParentURL, PriorityNormalized, ReportedBy, SecondaryId

Property description field

• Add a description field to the schema property. The description should be relevant to the property, and its length cannot exceed 200 characters.

Why these changes are useful

• The schema enhancements will help improve the response quality in search.

If You Already Use A Custom Connector

Use this template to adopt the new changes with minimal disruption:

1. Copy these two proto files from this template into your existing connector, then update your connector to use the new fields and properties (including new semantic labels and property Description in schema definitions):

• Contracts/CommonModels.proto
• Contracts/ConnectorCrawlContract.proto

2. Compare your existing GetDataSourceSchema with this template and add the newly introduced property types, semantic labels, and property description where relevant. 3. Update your crawl mapping logic (for example in GetCrawlStream) to populate ScdPrincipal and ScdPrincipalCollectionType values for item ingestion. 4. Preserve your existing connector unique ID, authentication settings, and any stable schema fields to avoid unnecessary reconfiguration. 5. Rebuild and test end-to-end using your current test datasource before promoting to production.

If You Are A New Customer

Start from this template and customize in this order:

1. Open GraphConnectorSdkSample.sln in Visual Studio. 2. Follow these custom connector tutorials to implement your connector as required:

• Create connector tutorial: https://learn.microsoft.com/en-us/graph/custom-connector-sdk-sample-create
• Test connector tutorial: https://learn.microsoft.com/en-us/graph/custom-connector-sdk-sample-test

3. Compare your GetDataSourceSchema with this template and add the newly introduced property types, semantic labels, and property description where relevant. 4. Update your crawl mapping logic (for example in GetCrawlStream) to populate ScdPrincipal and ScdPrincipalCollectionType values for item ingestion if needed. 5. Build and test end-to-end as instructed in the overview: https://learn.microsoft.com/en-us/graph/custom-connector-sdk-overview

Example: Add Principal And PrincipalCollection

Step 1: Declare properties in schema (GetDataSourceSchema)

schema.PropertyList.Add(
new SourcePropertyDefinition
{
Name = "Owner",
Type = SourcePropertyType.Principal,
DefaultSearchAnnotations = (uint)(SearchAnnotations.IsQueryable | SearchAnnotations.IsRetrievable),
RequiredSearchAnnotations = (uint)(SearchAnnotations.IsQueryable | SearchAnnotations.IsRetrievable),
DefaultSemanticLabels = { SearchPropertyLabel.CreatedBy },
Description = "The user who owns this item",
});

schema.PropertyList.Add(
new SourcePropertyDefinition
{
Name = "Approvers",
Type = SourcePropertyType.PrincipalCollection,
DefaultSearchAnnotations = (uint)(SearchAnnotations.IsQueryable | SearchAnnotations.IsRetrievable),
RequiredSearchAnnotations = (uint)(SearchAnnotations.IsQueryable | SearchAnnotations.IsRetrievable),
DefaultSemanticLabels = { SearchPropertyLabel.ReportedBy },
Description = "Users who approved this item",
});

Step 2: Populate values during crawl (GetCrawlStream)

if (!string.IsNullOrEmpty(item.Owner))
{
sourcePropertyValueMap.Values.Add(
"Owner",
new GenericType
{
PrincipalValue = new ScdPrincipal
{
Email = item.Owner,
}
});
}

if (item.Approvers != null && item.Approvers.Count > 0)
{
var approversCollection = new ScdPrincipalCollectionType();
foreach (var approver in item.Approvers)
{
if...