Orchestrate Microsoft AutoGen multi-agent workflows with nRouter. Connect agents via OpenAI-compatible endpoints with intelligent routing and budget controls.

Microsoft AutoGen is a multi-agent conversation framework that enables developers to build complex, cooperative AI systems where specialized agents collaborate to solve intricate tasks. Because multi-agent conversations generate high request volumes and token loops, running AutoGen directly through nRouter (https://api.nrouter.ai/v1) delivers vital architectural safeguards: hard spend ceilings via virtual keys, server-side prompt injection defense, cross-provider failover, and exact per-turn cost accounting.

AutoGen's OpenAIChatCompletionClient connects natively to nRouter's OpenAI-compatible gateway. Guardrails and content moderation rules apply transparently to each individual turn in multi-agent group chats, preventing compromised agent outputs from derailing conversation trees.

Prerequisites & Installation

AutoGen requires Python 3.10 or higher. For multi-agent systems, managing dependencies in a dedicated virtual environment is strongly advised.

Install the AutoGen AgentChat and OpenAI extension packages:

pip install autogen-agentchat autogen-ext[openai] nrouter-sdk

Setup & Configuration

Set your virtual API key in your environment:

export NROUTER_API_KEY="sk-nrouter-your-virtual-key"

Initializing the Client

Configure OpenAIChatCompletionClient with the nRouter gateway endpoint:

import os
from autogen_ext.models.openai import OpenAIChatCompletionClient

model_client = OpenAIChatCompletionClient(
    model="claude-sonnet-4-5-20250929",
    api_key=os.environ["NROUTER_API_KEY"],
    base_url="https://api.nrouter.ai/v1",
    timeout=60.0,
    max_retries=2,
)

Configuration Parameters

When deploying multi-agent swarms, configure client parameters to balance throughput, timeouts, and cost:

Parameter	Type	Default	Description
`base_url`	`str`	`https://api.nrouter.ai/v1`	Unified gateway base URL. Must include `/v1`.
`api_key`	`str`	`None`	nRouter virtual key (`sk-nrouter-...`).
`model`	`str`	Required	Model identifier, custom alias, or comma-separated fallback list.
`timeout`	`float`	`60.0`	Maximum wait time per agent turn in seconds.
`max_retries`	`int`	`2`	Client-side retry limit. nRouter handles upstream retries automatically.
`extra_create_args`	`dict`	`{}`	Payload additions, including `nrouter_*` template parameters and cache flags.

import os
from autogen_ext.models.openai import OpenAIChatCompletionClient

# Production model client configured for high concurrency
model_client = OpenAIChatCompletionClient(
    model="gpt-5.4-mini",
    api_key=os.environ["NROUTER_API_KEY"],
    base_url="https://api.nrouter.ai/v1",
    timeout=45.0,
    max_retries=3,
    extra_create_args={
        "nrouter_cache": True,
    },
)

Implementation Patterns

1. Single Agent Task Execution

Create a standalone assistant agent and execute a single prompt asynchronously:

import asyncio
import os
from autogen_agentchat.agents import AssistantAgent
from autogen_agentchat.messages import TextMessage
from autogen_core import CancellationToken
from autogen_ext.models.openai import OpenAIChatCompletionClient

async def run_single_agent():
    model_client = OpenAIChatCompletionClient(
        model="gpt-5.4-mini",
        api_key=os.environ["NROUTER_API_KEY"],
        base_url="https://api.nrouter.ai/v1",
    )

    agent = AssistantAgent(
        name="technical_architect",
        model_client=model_client,
        system_message="You are a senior systems architect. Provide direct, actionable analysis.",
    )

    response = await agent.on_messages(
        [TextMessage(content="What are the trade-offs of read-heavy LLM caching gateways?", source="user")],
        cancellation_token=CancellationToken(),
    )
    print(response.chat_message.content)

asyncio.run(run_single_agent())

2. Multi-Agent Group Chat

Construct a collaborative multi-agent loop with researchers and critics, guarded by maximum message limits:

import asyncio
import os
from autogen_agentchat.agents import AssistantAgent
from autogen_agentchat.teams import RoundRobinGroupChat
from autogen_agentchat.conditions import MaxMessageTermination
from autogen_ext.models.openai import OpenAIChatCompletionClient

async def run_multi_agent_team():
    model_client = OpenAIChatCompletionClient(
        model="gpt-5.4-mini",
        api_key=os.environ["NROUTER_API_KEY"],
        base_url="https://api.nrouter.ai/v1",
    )

    researcher = AssistantAgent(
        name="researcher",
        model_client=model_client,
        system_message="You research topics thoroughly and present structured evidence.",
    )

    critic = AssistantAgent(
        name="critic",
        model_client=model_client,
        system_message="You critique research findings for logical fallacies and incomplete data.",
    )

    team = RoundRobinGroupChat(
        [researcher, critic],
        termination_condition=MaxMessageTermination(max_messages=4),
    )

    result = await team.run(task="Evaluate zero-markup model pricing versus token-based markups.")
    for msg in result.messages:
        print(f"[{msg.source}]: {msg.content}\n")

asyncio.run(run_multi_agent_team())

3. Tool Calling with Server-side Guardrails

Register custom tools with AutoGen agents. nRouter scans all conversation turns before tool execution, preventing prompt-injected inputs from invoking dangerous operations:

import asyncio
import os
from autogen_agentchat.agents import AssistantAgent
from autogen_ext.models.openai import OpenAIChatCompletionClient

async def get_service_latency(service_name: str) -> str:
    """Check P99 latency for an internal microservice."""
    return f"{service_name}: P99 latency is 14ms (healthy)"

async def run_tool_agent():
    model_client = OpenAIChatCompletionClient(
        model="gpt-5.4-mini",
        api_key=os.environ["NROUTER_API_KEY"],
        base_url="https://api.nrouter.ai/v1",
    )

    agent = AssistantAgent(
        name="ops_agent",
        model_client=model_client,
        tools=[get_service_latency],
        system_message="You assist with production infrastructure health checks.",
    )

    # If the user prompt contains prompt injection, nRouter rejects the call before get_service_latency executes
    response = await agent.on_messages(...)

4. Multi-Tier Model Allocation

Optimize multi-agent budgets by allocating fast, lightweight models to high-frequency workers and frontier reasoning models to coordinators:

import os
from autogen_ext.models.openai import OpenAIChatCompletionClient

fast_client = OpenAIChatCompletionClient(
    model="gpt-5.4-mini",
    api_key=os.environ["NROUTER_API_KEY"],
    base_url="https://api.nrouter.ai/v1",
)

reasoning_client = OpenAIChatCompletionClient(
    model="claude-sonnet-4-5-20250929",
    api_key=os.environ["NROUTER_API_KEY"],
    base_url="https://api.nrouter.ai/v1",
)

# Assign appropriate model client per agent role
triage_agent = AssistantAgent(name="triage", model_client=fast_client)
synthesizer_agent = AssistantAgent(name="synthesizer", model_client=reasoning_client)

Production Best Practices

Multi-Agent Budget Ceilings

Multi-agent conversations can trigger unexpected cost spikes if conversation loops fail to terminate. Protect your infrastructure:

Virtual Key Hard Limits: Mint dedicated virtual keys with strict USD budget limits for each multi-agent workload.
Termination Conditions: Always set explicit MaxMessageTermination or regex-based termination conditions.
Turn-Level Semantic Caching: Enable nrouter_cache: True to prevent repeated identical evaluation turns from burning tokens.

Deterministic Routing & Failovers

When running complex agent trees, provider reliability is critical:

model_client = OpenAIChatCompletionClient(
    # Automatic fallback if primary model is degraded
    model="gpt-5.4-mini,claude-haiku-4-5-20251001",
    api_key=os.environ["NROUTER_API_KEY"],
    base_url="https://api.nrouter.ai/v1",
)

Observability & FinOps

Every AutoGen turn through nRouter produces metadata headers:

x-nr-request-id: Trace ID linking application logs with nRouter spend ledgers.
x-nr-model: The specific model instance that served the completion.
x-nr-cost-status: Status indicator (exact or unpriced).
x-nr-request-cost: Exact USD cost incurred for the request.
x-nr-input-tokens / x-nr-output-tokens: Exact provider token usage.

Troubleshooting & Error Handling

nRouter signals errors via standard HTTP status codes.

Common Error Codes

Status	Code	Cause	Recommended Action
`400`	`guardrail_blocked`	Prompt injection or forbidden content detected	Inspect agent input; adjust guardrail rules in the nRouter dashboard.
`401`	`authentication_error`	Missing, incorrect, or revoked virtual API key	Verify `NROUTER_API_KEY` in environment variables.
`402`	`insufficient_credits`	Zero organization balance or key spending ceiling hit	Refill account credits or raise key budget ceilings.
`429`	`rate_limit_exceeded`	Organization RPM/TPM quota exceeded	Apply exponential backoff; check retry headers.
`500` / `503`	`service_unavailable`	Downstream provider outage or network disruption	Specify multiple models in a comma-separated fallback list.

Error Catching in Asynchronous Loops

import openai

try:
    result = await team.run(task="Run critical analysis...")
except openai.BadRequestError as e:
    if "guardrail" in str(e).lower():
        print("An agent turn was blocked by nRouter server-side guardrails.")
    else:
        print(f"Bad request error: {e}")
except openai.AuthenticationError:
    print("Authentication failed: Check NROUTER_API_KEY.")
except openai.RateLimitError:
    print("Rate limit reached: Backing off before retrying conversation.")
except openai.APIError as e:
    print(f"Gateway error ({e.code}): {e.message}")

Next Steps

CrewAI Guide — Alternative role-based multi-agent framework
Python SDK Guide — Official nRouter Python SDK documentation
Chat Completions API — HTTP endpoint specifications

AutoGen

On this page