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-Afterheader; 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.