Setting up an autogen research team n4n.ai routing gives your multi-agent pipelines a single OpenAI-compatible endpoint that fails over when a provider is degraded. This tutorial builds a three-agent research crew that surveys a topic, drafts a brief, and critiques it, with all model traffic routed through one configurable client. You’ll end with runnable Python and a clear success signal.
Step 1: Install the runtime
Pin to AutoGen 0.4+ — the agentchat and ext packages split the old monolith into composable pieces. You do not need the full autogen meta-package.
pip install -U "autogen-agentchat" "autogen-ext[openai]" "autogen-core"If you plan to use WebSurferAgent for live browsing, also install Playwright and its browser binaries. For this walkthrough we use a stub search tool to keep the example deterministic and offline-friendly.
Step 2: Configure the model client with routing
The core of this setup is autogen research team n4n.ai routing: a single OpenAIChatCompletionClient pointed at the gateway’s OpenAI-compatible endpoint. The gateway sits in front of 240+ models and applies automatic fallback when a provider is rate-limited or degraded. It also honors client routing directives and forwards provider cache-control hints, so you can shift models per request without code changes.
import os
from autogen_ext.models.openai import OpenAIChatCompletionClient
model_client = OpenAIChatCompletionClient(
model="gpt-4o-mini", # any model id the gateway supports
api_key=os.environ["N4N_API_KEY"],
base_url=os.environ["N4N_BASE_URL"], # OpenAI-compatible base URL
extra_headers={"x-routing-preference": "cost-optimized"},
)Store credentials in environment variables. Never hardcode keys. The extra_headers field is where you express routing intent; the gateway parses it and selects or falls back across backends.
Step 3: Define agent roles and a search tool
A research team needs a gatherer, a synthesizer, and a reviewer. Keep each agent’s system prompt tight and opinionated.
from autogen_core.tools import FunctionTool
from autogen_agentchat.agents import AssistantAgent
def web_search(query: str) -> str:
"""Stubbed search. Swap for a real API or WebSurferAgent in production."""
return f"Results for '{query}': (1) arXiv:2304.1234 sparse attention; (2) blog on long-context scaling."
search_tool = FunctionTool(web_search, description="Search the web for a query")
researcher = AssistantAgent(
name="Researcher",
model_client=model_client,
tools=[search_tool],
system_message="You are a meticulous researcher. Use the search tool, then return bullet points with sources. No prose.",
)
writer = AssistantAgent(
name="Writer",
model_client=model_client,
system_message="You convert research bullets into a concise brief with sections: Summary, Evidence, Open Questions.",
)
critic = AssistantAgent(
name="Critic",
model_client=model_client,
system_message="You review the brief for gaps, bias, and clarity. Reply 'APPROVED' or list required revisions.",
)Why separate agents?
Round-robin handoffs force each role to react only to the prior message, which prevents the model from silently merging duties. If you give one agent both research and writing, you lose the critique signal. Separate clients also let you route the researcher to a cheap model and the writer to a stronger one by swapping model_client instances.
Step 4: Assemble the team with termination
RoundRobinGroupChat cycles participants until a termination condition hits. We use a text mention so the critic can halt the loop.
from autogen_agentchat.teams import RoundRobinGroupChat
from autogen_agentchat.conditions import TextMentionTermination
termination = TextMentionTermination("APPROVED")
team = RoundRobinGroupChat(
participants=[researcher, writer, critic],
termination_condition=termination,
max_turns=12,
)Set max_turns as a backstop. Without it, a critic that never approves will loop until you kill the process. Twelve turns is enough for three agents to iterate four times.
Step 5: Run the team and verify
Stream the conversation so you can watch routing and fallback in action.
import asyncio
async def main():
task = "Research the impact of sparse attention on long-context LLMs and write a brief."
result = team.run_stream(task=task)
async for message in result:
print(f"[{message.source}] {message.content}")
if __name__ == "__main__":
asyncio.run(main())Verification checklist
- The loop ends with a message from
CriticcontainingAPPROVED. - The
Writerproduced a brief with the three required sections. - No
RateLimitErrorsurfaced even if you artificially throttle the primary model — the gateway should have fallen back. - Per-token usage is metered by the gateway; inspect its dashboard or response headers to confirm billing isolation between agents.
If the critic never approves, lower the writer’s temperature or tighten the researcher’s source format. The failure mode is almost always ambiguous tool output, not model capability.
Step 6: Harden the routing for production
In a real deployment, wrap the model_client in a small factory that reads routing hints from a config file. This lets you shift the researcher to a local model and keep the writer on a frontier model without touching agent code.
{
"researcher": {"model": "mixtral-8x7b", "x-routing-preference": "latency"},
"writer": {"model": "gpt-4o", "x-routing-preference": "quality"},
"critic": {"model": "claude-3-5-sonnet", "x-routing-preference": "quality"}
}Load this JSON, build three OpenAIChatCompletionClient instances, and pass each to its agent. Because the gateway forwards cache-control hints, you can also set "cache-control": "ephemeral" on repeated research queries to cut cost.
Closing notes
The pattern above is deliberately minimal. You can replace RoundRobinGroupChat with SelectSpeakerAgent once you trust the critic to moderate, or add a CodeExecutorAgent if your research needs computation. The routing layer stays constant — one endpoint, many models, automatic fallback. That is the entire point of putting an autogen research team behind a unified gateway: the agents care about roles, not about which GPU served their tokens.