Connect CrewAI multi-agent systems to nRouter using OpenAI-compatible endpoints. Enable resilient model routing, automated fallbacks, and usage monitoring.

CrewAI is an orchestration framework for autonomous, role-playing AI agents. It enables autonomous swarms where agents assume specific personas, delegate subtasks, and collaborate sequentially or hierarchically. Pointing CrewAI at nRouter (https://api.nrouter.ai/v1) equips your autonomous swarms with centralized governance: hard USD budget limits per virtual key, server-side prompt injection filtering across agent communication chains, and automatic cross-provider failover.

CrewAI's native LLM class supports any OpenAI-compatible gateway. By designating nRouter as the base URL, every agent, task execution, and background delegation is routed through the gateway, recording exact provider costs and enforcing organization guardrails without code changes.

Prerequisites & Installation

CrewAI requires Python 3.10 or higher. We recommend using a dedicated virtual environment for multi-agent workflows.

Install CrewAI and the optional nRouter SDK:

pip install crewai nrouter-sdk

Setup & Configuration

Store your nRouter virtual key in your environment:

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

Initializing the LLM Instance

Instantiate CrewAI's LLM object pointing at nRouter:

import os
from crewai import LLM

llm = LLM(
    model="openai/claude-sonnet-4-5-20250929",
    base_url="https://api.nrouter.ai/v1",
    api_key=os.environ["NROUTER_API_KEY"],
    temperature=0.2,
    timeout=60.0,
)

Configuration Parameters

When deploying multi-agent crews, tune connection and execution settings:

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 string with `openai/` prefix, custom alias, or fallback list.
`timeout`	`float`	`60.0`	Total HTTP timeout in seconds per agent execution.
`extra_body`	`dict`	`{}`	Payload parameters, including `nrouter_*` template tags and cache directives.

import os
from crewai import LLM

# Production LLM configuration with caching and fallbacks
llm = LLM(
    model="openai/gpt-5.4-mini,openai/claude-haiku-4-5-20251001",
    base_url="https://api.nrouter.ai/v1",
    api_key=os.environ["NROUTER_API_KEY"],
    timeout=45.0,
    extra_body={
        "nrouter_cache": True,
    },
)

Implementation Patterns

1. Collaborative Multi-Agent Crew

Build a two-agent research and writing pipeline:

import os
from crewai import Agent, Task, Crew, Process, LLM

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

# Define specialized role-playing agents
researcher = Agent(
    role="Senior Technical Researcher",
    goal="Uncover cutting-edge architectural patterns in AI gateways",
    backstory="A veteran infrastructure engineer specializing in distributed systems and LLM proxies.",
    llm=llm,
    verbose=True,
)

writer = Agent(
    role="Principal Technical Writer",
    goal="Synthesize complex infrastructure analysis into clear executive briefings",
    backstory="An editor known for eliminating jargon and producing concise architectural guides.",
    llm=llm,
    verbose=True,
)

# Define tasks with explicit dependencies
research_task = Task(
    description="Research the advantages of zero-markup pricing and prompt injection filtering at the gateway layer.",
    expected_output="A bulleted summary of 3 architectural advantages.",
    agent=researcher,
)

write_task = Task(
    description="Transform the research summary into a 2-paragraph executive briefing.",
    expected_output="A polished 2-paragraph executive summary.",
    agent=writer,
    context=[research_task],
)

# Execute crew sequentially
crew = Crew(
    agents=[researcher, writer],
    tasks=[research_task, write_task],
    process=Process.sequential,
)

result = crew.kickoff()
print(result)

2. Multi-Model Crew Cost Optimization

Assign lightweight, cost-effective models to high-iteration agents and frontier reasoning models to synthesizers:

import os
from crewai import Agent, LLM

# High-throughput, cost-efficient model for data gathering
worker_llm = LLM(
    model="openai/gpt-5.4-mini",
    base_url="https://api.nrouter.ai/v1",
    api_key=os.environ["NROUTER_API_KEY"],
)

# High-capability reasoning model for final review
synthesis_llm = LLM(
    model="openai/claude-sonnet-4-5-20250929",
    base_url="https://api.nrouter.ai/v1",
    api_key=os.environ["NROUTER_API_KEY"],
)

scout = Agent(role="Data Scout", goal="Gather raw facts", llm=worker_llm)
lead_analyst = Agent(role="Lead Analyst", goal="Synthesize final conclusions", llm=synthesis_llm)

3. Per-Request Gateway Overrides

Control gateway features like prompt templates and semantic caching via extra_body:

llm = LLM(
    model="openai/gpt-5.5",
    base_url="https://api.nrouter.ai/v1",
    api_key=os.environ["NROUTER_API_KEY"],
    extra_body={
        "nrouter_prompt_template_id": "tmpl_agent_executive_brief_v1",
        "nrouter_prompt_variables": {"domain": "cloud-infrastructure"},
        "nrouter_cache": True,
    },
)

Production Best Practices

Multi-Agent Budget Isolation

Autonomous agents with delegation capabilities can consume tokens rapidly. Safeguard your budget:

Virtual Key Hard Limits: Mint dedicated virtual keys with defined USD ceilings for each autonomous crew.
Deterministic Routing: Specify fallback models directly in the model parameter (openai/primary,openai/secondary).
Turn-by-Turn Guardrails: When agents delegate tasks to other agents, nRouter inspects all inter-agent messages, neutralizing prompt injections passed via simulated tool outputs or untrusted documents.

Telemetry & FinOps Tracking

Every request executed by CrewAI returns standard nRouter telemetry headers:

x-nr-request-id: UUID tracking the individual turn through edge WAF and provider egress.
x-nr-model: The exact provider model that served the task.
x-nr-cost-status: Status indicator (exact or unpriced).
x-nr-request-cost: Precise USD cost charged for the call.
x-nr-input-tokens / x-nr-output-tokens: Exact provider token usage figures.

Troubleshooting & Error Handling

nRouter reports errors using standard HTTP status codes.

Common Error Codes

Status	Code	Cause	Recommended Action
`400`	`guardrail_blocked`	Content violated safety filters or prompt injection defense	Inspect task prompt; review 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 Crew Executions

try:
    result = crew.kickoff()
    print(result)
except Exception as e:
    err_str = str(e).lower()
    if "guardrail" in err_str:
        print("An agent execution was blocked by nRouter server-side guardrails.")
    elif "insufficient_credits" in err_str or "402" in err_str:
        print("Budget ceiling reached for this virtual key.")
    elif "429" in err_str:
        print("Rate limit reached. Ensure backoff is configured.")
    else:
        print(f"Execution error: {e}")

Next Steps

AutoGen Guide — Alternative conversational multi-agent framework
LangChain Integration — Building chains and document RAG
Python SDK Guide — Official nRouter Python SDK documentation

CrewAI

On this page