Implementation:Microsoft Semantic kernel ContactsPlugin OpenAPI

Knowledge Sources	Microsoft_Semantic_kernel
Domains	OpenAPI, Copilot_Agent_Plugins
Last Updated	2026-02-11 00:00 GMT

Overview

Concrete OpenAPI 3.0.1 specification for the Microsoft Graph Contacts API, used as the ContactsPlugin definition within the Copilot Agent Plugins sample of Semantic Kernel.

Description

This file is an OpenAPI 3.0.1 YAML specification describing a subset of the Microsoft Graph v1.0 OData service focused on contact management. It defines a single endpoint:

GET /me/contacts -- Lists contacts from the default contacts folder of the signed-in user with full OData query parameter support ($top, $skip, $search, $filter, $count, $orderby, $select, $expand). Supports pagination via @odata.nextLink.

The specification includes comprehensive schema definitions for Microsoft Graph contact entities:

microsoft.graph.contact -- Full contact model with extensive properties including displayName, givenName, surname, emailAddresses, businessPhones, homePhones, mobilePhone, jobTitle, companyName, department, officeLocation, businessAddress, homeAddress, otherAddress, birthday, assistantName, manager, profession, spouseName, children, personalNotes, and Japanese phonetic name fields (yomiGivenName, yomiSurname, yomiCompanyName).
microsoft.graph.physicalAddress -- Address with city, countryOrRegion, postalCode, state, and street.
microsoft.graph.emailAddress -- Email address with address and display name.
microsoft.graph.profilePhoto -- Optional contact photo navigation property.

Usage

This file is used by the Copilot Agent Plugins Concepts sample to demonstrate how contact management operations can be exposed as agent-callable tools. Developers use this to understand how to build Copilot Agent Plugins that access Microsoft Graph Contacts data.

Code Reference

Source Location

Repository: Microsoft_Semantic_kernel
File: dotnet/samples/Concepts/Resources/Plugins/CopilotAgentPlugins/ContactsPlugin/contacts-openapi.yml
Lines: 1-403

Signature

openapi: 3.0.1
info:
  title: OData Service for namespace microsoft.graph - Subset
  description: This OData service is located at https://graph.microsoft.com/v1.0
  version: v1.0
servers:
  - url: https://graph.microsoft.com/v1.0
paths:
  /me/contacts:
    get:
      tags:
        - me.contact
      summary: List contacts
      description: 'Get a contact collection from the default contacts folder
        of the signed-in user.'
      operationId: me_ListContacts
      parameters:
        - $ref: '#/components/parameters/top'
        - $ref: '#/components/parameters/skip'
        - $ref: '#/components/parameters/search'
        - $ref: '#/components/parameters/filter'
        - $ref: '#/components/parameters/count'

Import

// Loaded as part of the Copilot Agent Plugin configuration:
await kernel.ImportPluginFromOpenApiAsync(
    "ContactsPlugin",
    Path.Combine("Resources", "Plugins", "CopilotAgentPlugins",
                 "ContactsPlugin", "contacts-openapi.yml"));

I/O Contract

Inputs

Name	Type	Required	Description
$top	integer (query)	no	Show only the first n items.
$skip	integer (query)	no	Skip the first n items.
$search	string (query)	no	Search items by search phrases.
$filter	string (query)	no	Filter items by property values.
$count	boolean (query)	no	Include count of items.
$orderby	array of strings (query)	no	Order items by property values.
$select	array of strings (query)	no	Select properties to be returned.
$expand	array of strings (query)	no	Expand related entities (e.g., extensions, photo).

Outputs

Name	Type	Description
contactCollectionResponse	object	Paginated collection of contact objects with @odata.count, @odata.nextLink, and value array containing microsoft.graph.contact entities.

Usage Examples

Loading the ContactsPlugin

var kernel = Kernel.CreateBuilder()
    .AddAzureOpenAIChatCompletion(deploymentName, endpoint, apiKey)
    .Build();

await kernel.ImportPluginFromOpenApiAsync(
    "ContactsPlugin",
    Path.Combine("Resources", "Plugins", "CopilotAgentPlugins",
                 "ContactsPlugin", "contacts-openapi.yml"));

// List contacts with filtering
var contacts = await kernel.InvokeAsync("ContactsPlugin", "me_ListContacts",
    new KernelArguments { ["$top"] = "10", ["$select"] = "displayName,emailAddresses" });

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment