Configuring Semantic Kernel's OpenAI connector for n4n.ai

The Semantic Kernel OpenAI connector speaks the OpenAI HTTP contract, so retargeting it at an OpenAI-compatible gateway is a base-URL swap. This walkthrough shows how to configure the semantic kernel openai connector n4n.ai binding in Python, pass routing hints, and verify token metering without rewriting your skill or planner code. You will go from empty virtualenv to a streaming chat call in under ten minutes.

Step 1: Install the SDK and prepare credentials

Create a clean environment and install the packages. Semantic Kernel ships as semantic-kernel on PyPI; we pin a recent 1.x release to avoid API drift.

python -m venv .venv
source .venv/bin/activate
pip install "semantic-kernel>=1.10.0" python-dotenv

Export your gateway key. The connector expects an API key in the api_key field; the gateway accepts its own issued token. If you run a local mock, any non-empty string works.

export N4N_API_KEY="sk-your-token-here"

Keep the key out of source control. Load it via python-dotenv in your entrypoint:

from dotenv import load_dotenv
import os

load_dotenv()
API_KEY = os.getenv("N4N_API_KEY", "sk-local")

Step 2: Point the connector at the gateway

Instantiate a Kernel and register an OpenAIChatCompletion service. The only non-default parameter is base_url, which overrides the OpenAI default (https://api.openai.com/v1). Set it to the gateway’s OpenAI-compatible endpoint. This is the core of the semantic kernel openai connector n4n.ai configuration.

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

BASE_URL = "https://api.n4n.ai/v1"

def build_kernel() -> Kernel:
    kernel = Kernel()
    chat = OpenAIChatCompletion(
        ai_model_id="gpt-4o-mini",   # any model the gateway exposes
        api_key=API_KEY,
        base_url=BASE_URL,
    )
    kernel.add_chat_service("primary", chat)
    return kernel

kernel = build_kernel()

Model IDs are not validated client-side. Pick an ID the gateway actually routes—gpt-4o-mini, claude-3-5-sonnet, or one of the 240+ aliases it addresses. A bad ID surfaces as a 404 from the gateway, not a local error.

Step 3: Run your first chat completion

Semantic Kernel wraps the raw SDK call. Use the kernel’s prompt API for a quick smoke test:

from semantic_kernel.functions import KernelFunction

async def main():
    prompt = KernelFunction.from_prompt("Say hello in one word.")
    result = await prompt.invoke(kernel)
    print(result)

asyncio.run(main())

If you prefer the lower-level service, call it directly:

async def raw_call():
    chat = kernel.get_chat_service("primary")
    messages = [{"role": "user", "content": "What is 2+2?"}]
    resp = await chat.complete_chat_async(messages)
    print(resp[0].content)

The connector serializes the same message list you would send to OpenAI. System messages, multi-turn history, and tool calls all pass through unchanged.

Step 4: Forward routing and cache-control hints

The gateway honors client routing directives and forwards provider cache-control hints. To send them, construct an AsyncOpenAI client with default headers or extra body and hand it to the connector. This bypasses the connector’s internal client but keeps the same interface.

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

client = AsyncOpenAI(
    base_url=BASE_URL,
    api_key=API_KEY,
    default_headers={"X-Route-Prefer": "anthropic"},
)

chat = OpenAIChatCompletion(
    ai_model_id="claude-3-5-sonnet",
    api_key=API_KEY,
    client=client,
)
kernel.add_chat_service("routed", chat)

For cache hints, use the extra body field that the upstream provider expects. Anthropic-style ephemeral caching travels as extra_body={"cache_control": {"type": "ephemeral"}} on the completion call. Wrap it in a thin helper if you use it across skills.

Step 5: Rely on automatic fallback

One benefit of the gateway is automatic fallback when a provider is rate-limited or degraded. You do not need tenacity retries in your SK code. Still, wrap calls so a hard failure surfaces cleanly:

from openai import APIError

async def safe_call(messages):
    try:
        return await chat.complete_chat_async(messages)
    except APIError as e:
        log.error("gateway returned %s", e.status_code)
        raise

In production, treat 429 and 503 as retryable at the gateway layer, not in your planner loop.

Step 6: Verify token metering

Per-token usage metering is reported in the standard usage object. With the raw client you can inspect it directly:

resp = await client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Count to three."}],
)
print(resp.usage.prompt_tokens, resp.usage.completion_tokens)

If you stay inside Semantic Kernel, the chat service attaches usage to the result metadata in newer builds. Check result.metadata after an invoke. A non-zero completion_tokens value confirms the gateway processed and metered the request.

Step 7: Streaming and function calling

Streaming works by passing stream=True through the underlying client. The connector exposes complete_chat_stream_async:

async for chunk in chat.complete_chat_stream_async(messages):
    if chunk.content:
        print(chunk.content, end="")

Function calling uses the same tools schema as OpenAI. Define a SK native function and let the planner emit the schema; the gateway forwards it to the model and returns tool_calls unchanged.

Troubleshooting

401 Unauthorized: Your API_KEY is empty or revoked. The gateway returns OpenAI-shaped errors.
404 Model not found: The ai_model_id isn’t in the gateway’s catalog. List models with curl $BASE_URL/models -H "Authorization: Bearer $N4N_API_KEY".
Trailing slash: Do not append / to base_url. Semantic Kernel joins paths and will double-slash the route.
SSL errors in CI: Ensure certifi is updated; the gateway uses standard CA chains.

Following these steps gives you a working OpenAI-compatible connector setup with routing, caching, and metering under your control.