Skip to content

Semantic Kernel

Your kernel, plugins and agents stay as they are. Point the OpenAI chat connector at the gateway and every model call is checked against your policies, charged to the right team and recorded in Request logs, and the same connector can reach Claude and Gemini models as well as OpenAI's.

What it is

Semantic Kernel is Microsoft's SDK for building AI applications and agents; this page covers Python and .NET. Its OpenAI chat completion connector (OpenAIChatCompletion in Python, AddOpenAIChatCompletion / OpenAIChatCompletionService in .NET) speaks the OpenAI format, which the gateway accepts at /v1.

Use the OpenAI connector, not the Azure OpenAI one: the Azure connector sends the key in an api-key header (or an Entra token), which the gateway doesn't accept. Azure OpenAI models stay reachable: the gateway routes to them by model name.

Microsoft describes Microsoft Agent Framework as the successor to Semantic Kernel. The settings on this page work for applications built on Semantic Kernel 1.x.

The two settings

Setting Python .NET Value
Base address base_url on the AsyncOpenAI client you pass as async_client endpoint: new Uri(...) https://<your-gateway>/v1
Key api_key on that client apiKey Your Vidai key (starts vk_), never a provider's key

The Python OpenAIChatCompletion has no base-address argument of its own: build an AsyncOpenAI client with the gateway's address and hand it over. In .NET, a custom endpoint is marked experimental: add #pragma warning disable SKEXP0010. Both send the key as Authorization: Bearer.

The gateway's address, and the base URL for each kind of SDK, are under Connect your app on the Keys page and in System › Settings › Gateway. You get the key from Keys › Issue a key; its secret is shown once.

A minimal call

import asyncio
from openai import AsyncOpenAI
from semantic_kernel import Kernel
from semantic_kernel.connectors.ai.open_ai import OpenAIChatCompletion

client = AsyncOpenAI(base_url="https://<your-gateway>/v1", api_key="vk_…")

kernel = Kernel()
kernel.add_service(OpenAIChatCompletion(ai_model_id="gpt-4o-mini", async_client=client))

async def main() -> None:
    print(await kernel.invoke_prompt("Say hello in Dutch."))

asyncio.run(main())
using Microsoft.SemanticKernel;

#pragma warning disable SKEXP0010
var builder = Kernel.CreateBuilder();
builder.AddOpenAIChatCompletion(
    modelId: "gpt-4o-mini",
    apiKey: "vk_…",
    endpoint: new Uri("https://<your-gateway>/v1"));
var kernel = builder.Build();

Console.WriteLine(await kernel.InvokePromptAsync("Say hello in Dutch."));

The same code calls Claude or Gemini: put a model name such as claude-sonnet-4.5 in the model id. The gateway translates the request for that provider and the answer back into the OpenAI shape, streams and tool calls included.

Streaming

async for chunk in kernel.invoke_prompt_stream("Count to five."):
    print(chunk[0], end="")
await foreach (var chunk in kernel.InvokePromptStreamingAsync("Count to five."))
    Console.Write(chunk);

A stream from Claude or Gemini arrives as OpenAI chunks. Vidai records the tokens and the cost either way.

Tool calls

Plugins become tools. Let the model choose them with automatic function calling; each round trip is a call through the gateway, on any provider it translates to.

from semantic_kernel.connectors.ai import FunctionChoiceBehavior
from semantic_kernel.connectors.ai.open_ai import OpenAIChatPromptExecutionSettings
from semantic_kernel.functions import KernelArguments, kernel_function

class Weather:
    @kernel_function(description="Weather for a city")
    def get_weather(self, city: str) -> str:
        return f"Sunny in {city}"

kernel.add_plugin(Weather(), plugin_name="weather")
settings = OpenAIChatPromptExecutionSettings(function_choice_behavior=FunctionChoiceBehavior.Auto())
print(await kernel.invoke_prompt("Weather in Utrecht?", arguments=KernelArguments(settings=settings)))
using System.ComponentModel;
using Microsoft.SemanticKernel.Connectors.OpenAI;

kernel.Plugins.AddFromType<Weather>("weather");
var settings = new OpenAIPromptExecutionSettings { FunctionChoiceBehavior = FunctionChoiceBehavior.Auto() };
Console.WriteLine(await kernel.InvokePromptAsync("Weather in Utrecht?", new(settings)));

public class Weather
{
    [KernelFunction, Description("Weather for a city")]
    public string GetWeather(string city) => $"Sunny in {city}";
}

Agents (ChatCompletionAgent) use the kernel's chat service, so they go through the gateway with no more settings.

Reading what the gateway did

Semantic Kernel doesn't hand you the response headers. Find the calls in Request logs: filter by Key or Model; each prompt, plugin round trip and agent turn is its own call. The model that answered, any routing rule or fallback, and the cost are there.

Errors

The gateway writes its errors in the OpenAI format. In Python, kernel.invoke_prompt raises a KernelInvokeException; the OpenAI SDK's own exception sits at the end of its chain of causes. .NET raises an HttpOperationException with the status and the response body. Match on the code rather than the message: codes are stable.

import openai
from semantic_kernel.exceptions import KernelInvokeException

try:
    await kernel.invoke_prompt("Hi")
except KernelInvokeException as e:
    cause = e
    while cause and not isinstance(cause, openai.APIStatusError):
        cause = cause.__cause__
    if cause:
        print(cause.status_code, cause.response.headers.get("x-vidai-error-code"))
        print(cause.response.headers.get("x-vidai-request-id"))

In .NET, HttpOperationException.StatusCode and ResponseContent carry the status and the OpenAI-format body, whose error.code is the gateway's code.

Status Common gateway codes
401 missing_api_key, invalid_api_key, conflicting_auth_headers
403 api_key_disabled, model_not_allowed, denied_by_routing_rule, content_guardrail_blocked
404 model_not_found, endpoint_not_found
429 rate_limit_exceeded, token_limit_exceeded, concurrency_limit_exceeded
5xx ai_traffic_suspended, fallback_exhausted, upstream_timeout, upstream_unreachable

The full list is in Headers and errors.

Model names

Send the names your organisation has approved, as listed under Models in the Control room (for example gpt-4o-mini, claude-sonnet-4.5, gemini-3.5-flash). GET /v1/models with your key returns exactly the models it may call. See Model names.

What goes through the gateway

Feature Through the gateway
Chat completion, streaming, plugins (function calling), agents, vision Yes, to OpenAI, Azure OpenAI, Anthropic, Gemini and Vertex AI models
Text embeddings, text-to-image, audio through the OpenAI connectors Yes, to OpenAI and Azure OpenAI only; another provider gets a clear 400
The Azure OpenAI connectors No: they send the key in a header the gateway doesn't accept; use the OpenAI connectors
OpenAIAssistantAgent (Assistants API) No: see Assistants API

Check it works in a minute

python -c "import asyncio; from openai import AsyncOpenAI; from semantic_kernel.connectors.ai.open_ai import OpenAIChatCompletion as S; from semantic_kernel.contents import ChatHistory; from semantic_kernel.connectors.ai.open_ai import OpenAIChatPromptExecutionSettings as P; h=ChatHistory(); h.add_user_message('ping'); print(asyncio.run(S(ai_model_id='gpt-4o-mini', async_client=AsyncOpenAI(base_url='https://<your-gateway>/v1', api_key='vk_…')).get_chat_message_content(h, P())))"

A short answer means the address and key are right. The call shows in Request logs within seconds.

Good to know

  • The OpenAI client underneath retries on its own (twice by default). A fallback chain may already have tried another model before you see an error; in Python, build the client with AsyncOpenAI(..., max_retries=0) if you don't want both.
  • The gateway's own 429 has no Retry-After header; back off on your side.
  • Anything other than chat sent to a model of another provider is refused with a 400, never sent somewhere else.