Principle:Microsoft Semantic kernel CopilotAgent Plugin OpenAPI Specs

Overview

Pattern for defining Copilot Agent plugin capabilities through OpenAPI specification documents that describe external service APIs. This principle covers how agents discover and invoke operations on services such as Microsoft Graph (Calendar, Contacts, Messages), NASA APOD, and Jira through declarative API descriptions.

Description

Copilot Agent Plugins use OpenAPI specification documents to declare the set of operations that an agent can invoke at runtime. Rather than hard-coding API interactions, each plugin is defined by an OpenAPI spec that describes available endpoints, parameters, authentication requirements, and response schemas. The Semantic Kernel runtime reads these specs and registers the described operations as callable tools for the agent.

Plugin Architecture

The plugin architecture follows a declarative pattern:

An OpenAPI specification document describes the external service's API.
The Semantic Kernel parser reads the specification and generates kernel functions for each operation.
The agent runtime registers these functions as available tools.
When the agent decides to invoke a tool, the runtime constructs the appropriate HTTP request based on the spec.

# Example: Calendar Plugin OpenAPI Spec (simplified)
openapi: "3.0.1"
info:
  title: "Microsoft Graph Calendar API"
  version: "1.0"
servers:
  - url: "https://graph.microsoft.com/v1.0"
paths:
  /me/events:
    get:
      operationId: listEvents
      summary: "List calendar events for the current user"
      parameters:
        - name: $top
          in: query
          schema:
            type: integer
          description: "Number of events to return"
      responses:
        "200":
          description: "List of calendar events"
          content:
            application/json:
              schema:
                type: object
                properties:
                  value:
                    type: array
                    items:
                      $ref: "#/components/schemas/Event"

Supported Service Integrations

The Copilot Agent plugin ecosystem includes OpenAPI specs for several categories of services:

Microsoft Graph APIs:
- Calendar Plugin: Operations for listing, creating, updating, and deleting calendar events. Supports query parameters for filtering by date range, attendee, and event status.
- Contacts Plugin: Operations for managing contact records, including listing contacts, searching by name or email, and creating new entries.
- Messages Plugin: Operations for reading, sending, and managing email messages, including folder navigation and message search.

External APIs:
- Astronomy Plugin (NASA APOD): Operations for retrieving the NASA Astronomy Picture of the Day, including date-based lookups and metadata retrieval.
- Jira Plugin: Operations for interacting with Jira project management, including issue querying, creation, status updates, and comment management.

Authentication and Security

Each OpenAPI spec includes security scheme definitions appropriate to its target service:

components:
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: "https://login.microsoftonline.com/common/oauth2/v2.0/authorize"
          tokenUrl: "https://login.microsoftonline.com/common/oauth2/v2.0/token"
          scopes:
            Calendars.ReadWrite: "Read and write calendar events"
    apiKey:
      type: apiKey
      in: header
      name: X-API-Key

The Semantic Kernel runtime handles credential injection based on these security definitions, supporting OAuth 2.0 for Microsoft Graph APIs, API keys for NASA, and token-based authentication for Jira.

Usage

Use the CopilotAgent Plugin OpenAPI pattern in the following scenarios:

Building Copilot Agent Plugins: Define new agent capabilities by creating OpenAPI specification documents for external REST APIs. The agent will automatically gain the ability to invoke the described operations.
Studying the OpenAPI Plugin Pattern: Review existing plugin specs (Calendar, Contacts, Messages, Astronomy, Jira) to understand how API operations map to agent tools and how parameters, authentication, and response schemas are declared.
Extending Agent Capabilities: Add new operations to existing plugin specs or create entirely new plugin specs for additional services.
Testing Agent Tool Selection: Use the plugin specs as a known set of available tools when testing agent planning and tool selection logic.

Theoretical Basis

OpenAPI-Driven Plugin Architecture

The plugin architecture leverages the OpenAPI Specification as a machine-readable contract that defines API capabilities. By using a standardized description format, the system decouples plugin definition from plugin implementation. New plugins can be added without writing code; only a specification document is needed. This follows the principle of declarative capability definition, where the system's abilities are described rather than programmed.

Declarative API Capability Definition

Each OpenAPI spec serves as a declarative manifest of what an agent can do with a particular service. The spec describes the what (available operations and their parameters) without prescribing the how (implementation details). This separation enables the Semantic Kernel runtime to generate the necessary HTTP client code at import time, and allows the agent to reason about available capabilities at a high level based on operation summaries and parameter descriptions.

Agent Tool Registration Through API Schemas

The process of converting an OpenAPI spec into agent tools follows a systematic mapping:

Each operation (path + HTTP method) becomes a callable function in the agent's tool set.
Each parameter becomes a function parameter with type information and descriptions that help the agent understand when and how to use it.
Each response schema informs the agent about what data to expect back, enabling it to plan multi-step workflows.
Each security scheme determines what credentials the runtime needs to provide when invoking the operation.

This schema-driven registration ensures that the agent's understanding of available tools is always consistent with the actual API capabilities.

Related Pages

Page Connections

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

Principle

Implementation

Heuristic

Environment