Implementation:Microsoft Semantic kernel AstronomyPlugin OpenAPI
| Knowledge Sources | |
|---|---|
| Domains | OpenAPI, Copilot_Agent_Plugins |
| Last Updated | 2026-02-11 00:00 GMT |
Overview
Concrete OpenAPI 3.0.1 specification for the Microsoft Graph Messages API, used as the AstronomyPlugin's backing API 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. Despite being located in the AstronomyPlugin directory, the specification actually defines operations for the Microsoft Graph Messages API, serving as a demonstration plugin for the Copilot Agent Plugins framework. It includes:
- GET /me/messages -- Lists messages in the signed-in user's mailbox with support for OData query parameters ($top, $skip, $search, $filter, $count, $orderby, $select, $expand) and includeHiddenMessages. Supports pagination via @odata.nextLink.
- POST /me/sendMail -- Sends a message specified in the request body using JSON or MIME format.
The specification defines comprehensive schema components for Microsoft Graph entities including microsoft.graph.message, microsoft.graph.recipient, microsoft.graph.itemBody, microsoft.graph.attachment, microsoft.graph.followupFlag, microsoft.graph.importance, and related types. The server URL is https://graph.microsoft.com/v1.0.
Usage
This file is used by the Copilot Agent Plugins Concepts sample to demonstrate how OpenAPI specifications can be loaded as Copilot Agent Plugin definitions. Developers studying the Copilot Agent Plugins pattern use this file to understand how Microsoft Graph operations are exposed as agent-callable tools.
Code Reference
Source Location
- Repository: Microsoft_Semantic_kernel
- File: dotnet/samples/Concepts/Resources/Plugins/CopilotAgentPlugins/AstronomyPlugin/messages-openapi.yml
- Lines: 1-513
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/messages:
get:
tags:
- me.message
summary: Get the messages in the signed-in user's mailbox
operationId: me_ListMessages
parameters:
- name: includeHiddenMessages
in: query
description: Include Hidden Messages
schema:
type: string
- $ref: '#/components/parameters/top'
- $ref: '#/components/parameters/skip'
Import
// Loaded as part of the Copilot Agent Plugin configuration:
await kernel.ImportPluginFromOpenApiAsync(
"AstronomyPlugin",
Path.Combine("Resources", "Plugins", "CopilotAgentPlugins",
"AstronomyPlugin", "messages-openapi.yml"));
I/O Contract
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
| includeHiddenMessages | string (query) | no | Include hidden messages in the response. |
| $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. |
| Message | microsoft.graph.message (body) | yes | Message object for sendMail operation. |
| SaveToSentItems | boolean (body) | no | Whether to save the sent message. Default: false. |
Outputs
| Name | Type | Description |
|---|---|---|
| messageCollectionResponse | object | Paginated collection of message objects with @odata.count, @odata.nextLink, and value array. |
| 204 No Content | (empty) | Success response for the sendMail operation. |
Usage Examples
Loading the AstronomyPlugin in a Concepts Sample
var kernel = Kernel.CreateBuilder()
.AddAzureOpenAIChatCompletion(deploymentName, endpoint, apiKey)
.Build();
// Import the plugin from its OpenAPI spec
await kernel.ImportPluginFromOpenApiAsync(
"AstronomyPlugin",
Path.Combine("Resources", "Plugins", "CopilotAgentPlugins",
"AstronomyPlugin", "messages-openapi.yml"));
// Agent can now list messages or send mail via the plugin
var result = await kernel.InvokeAsync("AstronomyPlugin", "me_ListMessages");