Point AutoGen's base_url at n4n.ai in 5 minutes

AutoGen’s base_url parameter lets you redirect OpenAI-compatible requests to any gateway. Pointing it at n4n.ai gives you one endpoint that reaches 240+ models, automatic fallback when a provider degrades, and per-token metering — all without changing your agent code. This guide walks through the complete autogen base_url n4n.ai setup in five minutes.

Step 1: Install or upgrade AutoGen

AutoGen 0.2+ supports the base_url argument on OpenAIChatCompletionClient and the older config_list pattern. If you’re on an earlier version, upgrade first.

pip install --upgrade "autogen-agentchat>=0.2" "autogen-ext[openai]>=0.2"

Verify the import works:

from autogen_ext.models.openai import OpenAIChatCompletionClient
print(OpenAIChatCompletionClient.__init__.__doc__[:200])

You should see base_url documented in the signature.

Step 2: Get your n4n.ai credentials

You need two values:

• API key — issued from the n4n.ai dashboard (Settings → API Keys). Treat it like any secret.
• Base URL — https://api.n4n.ai/v1 (this is the OpenAI-compatible endpoint).

Store them in environment variables rather than hardcoding:

export N4N_API_KEY="sk-n4n-..."
export N4N_BASE_URL="https://api.n4n.ai/v1"

Step 3: Create a minimal client wrapper

AutoGen’s OpenAIChatCompletionClient accepts base_url and api_key directly. Wrap the env lookup so the rest of your code stays clean.

# n4n_client.py
import os
from autogen_ext.models.openai import OpenAIChatCompletionClient

def make_n4n_client(model: str = "gpt-4o-mini") -> OpenAIChatCompletionClient:
    """
    Return an AutoGen model client pointed at n4n.ai.
    The model name maps to whatever n4n.ai has registered under that alias.
    """
    api_key = os.getenv("N4N_API_KEY")
    base_url = os.getenv("N4N_BASE_URL", "https://api.n4n.ai/v1")

    if not api_key:
        raise RuntimeError("N4N_API_KEY not set in environment")

    return OpenAIChatCompletionClient(
        model=model,
        api_key=api_key,
        base_url=base_url,
        # Optional: tune timeouts for gateway latency
        timeout=60.0,
        max_retries=2,
    )

Why this pattern? It keeps the autogen base_url n4n.ai setup in one place. When you swap models — say from gpt-4o-mini to claude-3-5-sonnet — you only change the model argument. The gateway handles provider routing.

Step 4: Wire the client into an agent

AutoGen 0.2 uses AssistantAgent with a model_client parameter. Here’s a complete runnable script that spins up a coding agent and asks it to write a “hello world” in Python.

# run_agent.py
import asyncio
from autogen_agentchat.agents import AssistantAgent
from autogen_agentchat.teams import RoundRobinGroupChat
from autogen_agentchat.conditions import MaxMessageTermination
from n4n_client import make_n4n_client

async def main():
    # 1. Build the model client
    model_client = make_n4n_client(model="gpt-4o-mini")

    # 2. Create an agent that uses it
    coder = AssistantAgent(
        name="coder",
        model_client=model_client,
        system_message=(
            "You are a senior Python engineer. Write clean, typed, "
            "production-ready code. No markdown unless asked."
        ),
    )

    # 3. Run a simple task
    team = RoundRobinGroupChat(
        participants=[coder],
        termination_condition=MaxMessageTermination(max_messages=2),
    )

    result = await team.run(task="Write a function that returns the nth Fibonacci number.")
    print(result.messages[-1].content)

if __name__ == "__main__":
    asyncio.run(main())

Run it:

python run_agent.py

You should see a typed Fibonacci function printed to stdout. The request traveled: your script → n4n.ai → whichever provider serves gpt-4o-mini → back through n4n.ai → your script.

Step 5: Verify the request actually hit n4n.ai

Two quick checks confirm the routing works.

Check 1: Response headers

The OpenAIChatCompletionClient returns a ChatCompletionClient result object that includes the raw response. Inspect the headers field for gateway-added fields.

# verify_headers.py
import asyncio
from n4n_client import make_n4n_client

async def main():
    client = make_n4n_client(model="gpt-4o-mini")
    response = await client.create(
        messages=[{"role": "user", "content": "ping"}],
        model="gpt-4o-mini",
    )
    # The underlying httpx response is attached
    raw = response.raw_response
    print("Status:", raw.status_code)
    print("Via header:", raw.headers.get("via"))
    print("X-Request-ID:", raw.headers.get("x-request-id"))

asyncio.run(main())

Look for a via header that references the gateway (e.g., via: n4n.ai) and an x-request-id you can quote in support tickets.

Check 2: Usage metering in the dashboard

Log into the n4n.ai dashboard → Usage. You should see the request counted with:

• Model alias (gpt-4o-mini)
• Input / output token breakdown
• Latency percentile

If the dashboard shows zero usage after a successful run, double-check that N4N_BASE_URL is exactly https://api.n4n.ai/v1 (trailing /v1 matters) and that your API key belongs to the same workspace.

Step 6: Swap models without code changes

One reason to use a gateway is model flexibility. Change the model argument to any alias n4n.ai recognizes — claude-3-5-sonnet, gemini-1.5-pro, llama-3.1-70b — and the same agent code routes to a different provider.

# Same client factory, different model
client = make_n4n_client(model="claude-3-5-sonnet")

No import changes, no new SDKs. The gateway normalizes tool-calling formats and streaming deltas across providers, so your agent’s system_message and tool schemas keep working.

Step 7: Enable automatic fallback (optional)

If you want the gateway to retry a different provider when the primary is rate-limited or returns 5xx, pass a routing hint in the extra_body parameter. AutoGen forwards extra_body untouched to the chat completions endpoint.

from n4n_client import make_n4n_client

client = make_n4n_client(model="gpt-4o-mini")

response = await client.create(
    messages=[{"role": "user", "content": "Summarize this paper..."}],
    model="gpt-4o-mini",
    extra_body={
        "routing": {
            "fallback": ["claude-3-5-sonnet", "gemini-1.5-pro"],
            "strategy": "latency"  # or "cost", "quality"
        }
    },
)

The gateway honors this directive and forwards provider cache-control hints back to you, so conditional GETs work if you implement your own caching layer.

Common pitfalls

What you’ve built

• A reusable make_n4n_client() factory that centralizes the autogen base_url n4n.ai setup
• An agent that routes through a single gateway endpoint to any of 240+ models
• Verification steps using response headers and dashboard metering
• A pattern for zero-code model swaps and optional fallback routing

The next time you need to benchmark claude-3-5-sonnet against gpt-4o for a coding task, you change one string. The gateway handles the rest.