Principle:Microsoft Semantic kernel OpenAPI Plugin Import
| Knowledge Sources | |
|---|---|
| Domains | AI_Orchestration, Plugin_Architecture, API_Integration |
| Last Updated | 2026-02-11 19:00 GMT |
Overview
Dynamic plugin generation from OpenAPI specifications bridges existing REST APIs into AI-callable functions without writing native wrapper code.
Description
OpenAPI Plugin Import is the principle of automatically converting an OpenAPI (Swagger) specification into a set of AI-callable kernel functions. Rather than requiring developers to manually create native C# plugin classes for every external API, the framework parses the OpenAPI specification document, extracts operation definitions (endpoints, parameters, request/response schemas), and generates corresponding KernelFunction objects at runtime. The resulting plugin can be used identically to any native plugin for function calling, prompt templates, and AI-driven tool use.
This principle addresses a fundamental challenge in AI orchestration: modern applications need to integrate with dozens or hundreds of external APIs, and writing manual wrapper plugins for each is impractical. By leveraging the OpenAPI specification (a widely adopted standard for describing REST APIs), the framework can automatically derive function names from operation IDs, parameter schemas from the specification's parameter definitions, and descriptions from the specification's documentation fields.
The import process supports multiple input sources:
- File path: Load an OpenAPI specification from a local JSON or YAML file.
- URI: Fetch an OpenAPI specification from a remote URL.
- Stream: Parse an OpenAPI specification from an in-memory stream.
- RestApiSpecification: Use a pre-parsed specification model directly.
Each operation in the specification becomes a KernelFunction that, when invoked, constructs and sends the corresponding HTTP request with the model-provided arguments, and returns the response. The framework handles URL construction, parameter binding (path, query, header, body), authentication callbacks, and response parsing.
Usage
Use OpenAPI plugin import when you need to make an existing REST API available to an AI model without writing custom C# plugin code. This is particularly valuable for third-party APIs that already publish OpenAPI specifications (which is standard practice for most modern APIs), for internal microservices with auto-generated specifications, and for rapid prototyping where wrapping every endpoint manually would slow development.
Theoretical Basis
OpenAPI Plugin Import implements a Code Generation from Specification pattern, where a declarative API description is transformed into executable function objects at runtime. This is a form of metaprogramming where the program's behavior is derived from external metadata rather than compiled source code.
Formal model:
Given an OpenAPI specification S containing operations O1, O2, ..., On:
Import(S) = KernelPlugin {
name: pluginName,
functions: { Transform(Oi) | Oi in operations(S) }
}
Where the transformation function Transform maps each operation to a KernelFunction:
Transform(Oi) = KernelFunction {
name: Oi.operationId,
description: Oi.summary ?? Oi.description,
parameters: [ Map(pj) for pj in Oi.parameters ],
invoke: (args) => HttpRequest(Oi.method, Oi.path, bind(args, Oi.parameters))
}
The parameter mapping function Map converts OpenAPI parameter definitions to KernelParameterMetadata:
Map(pj) = {
name: pj.name,
description: pj.description,
type: json_schema_to_clr_type(pj.schema),
required: pj.required,
location: pj.in // path, query, header, cookie
}
Key invariants:
- Specification fidelity: Every operation in the OpenAPI specification becomes a function; every parameter becomes a function parameter.
- HTTP execution: When invoked, the function constructs and sends a real HTTP request to the API endpoint described in the specification.
- Authentication delegation: Authentication is handled through an optional callback, keeping credentials out of the specification parsing logic.
- Schema preservation: JSON Schema types from the OpenAPI specification are preserved in the function metadata, enabling the AI model to generate correctly typed arguments.