OpenRouter Setup & Routing Best Practices

Q: What is the minimum log schema?

request_id, policy, requested_model, resolved_model, status, latency_ms, prompt_tokens, completion_tokens, error_type.

Ten practices for a clean, swappable OpenRouter integration from day one.

Use this list when wiring the first gateway client so auth, slugs, routing, and observability do not need a rewrite two sprints later.

How to Use This Checklist

Work A through D in order for a new service.
Require evidence for each item - a file path, env name, log field, or PR link.
Revisit when you add agents, raise traffic, or change model vendors.
Pair with the troubleshooting cheatsheet when something is already on fire.

A - Client and Secrets

1. Centralize base URL and API key in one client factory. Every call site imports the factory; nobody retypes https://openrouter.ai/api/v1.
2. Load OpenRouter keys from a secret store, never from git. Separate keys per environment with optional per-key credit limits.
3. Keep optional attribution headers out of the credential path. HTTP-Referer and X-OpenRouter-Title are rankings metadata, not auth.

B - Model Identity

4. Address models through logical policies, not scattered raw slugs. Map fast / balanced / strong (or route names) in config.
5. Copy slugs from the live catalog and verify at build. Pin versions for production agents; treat latest aliases as deliberate drift.
6. Log requested slug, resolved response.model, usage, and latency every call. Especially for auto-router and fallback chains.

C - Routing Resilience

7. Decide fallbacks explicitly. Use OpenRouter models arrays and/or provider preferences; avoid improvised retry-to-random-model code.
8. Constrain Auto Router before enabling it on paid traffic. Allowlists, cost/quality tradeoff, session ids, and spend caps.
9. Separate streaming UX concerns from failover hopes. Mid-stream errors cannot silently change providers after tokens started.

D - Operability

10. Ship smoke tests: curl auth, non-stream completion, stream comment-safe parse, and one invalid-model negative test. Run them in CI against a cheap model.

Expanded Practice Notes

1-3 Client hygiene

# one module, many importers
from app.llm.openrouter import client, complete

Rotate keys on any exposure alert.

Do not embed keys in frontends.

4-6 Config and logging

{
  "balanced": {
    "model": "anthropic/claude-sonnet-4.5",
    "fallbacks": ["openai/gpt-4o-mini"]
  }
}

Illustrative slugs only - verify at build.

Emit structured logs:

policy=balanced requested=anthropic/claude-sonnet-4.5 resolved=... tokens=... ms=...

7-9 Routing

Prefer price/uptime defaults until you have a compliance reason to pin providers.

When you pin, document why allow_fallbacks is false.

For agents, pass session_id when using openrouter/auto so multi-turn model choice stays sticky.

10 Smoke tests

Test	Expect
curl with valid key	200 + content
wrong key	401
bad slug	400
stream	tokens without JSON parse crash on comments
fallback map (optional)	resolved model logged

FAQs

Do all ten apply to a weekend prototype?

Practices 1-3 and 10 are enough for a prototype.

Add 4-9 before shared production traffic.

Is OpenRouter required for model swapping?

No.

The policy-map habit applies to direct providers too; OpenRouter makes multi-model ops easier.

Should every team use openrouter/auto?

No.

Use it for mixed unknown prompts with constraints; pin models for scored, regulated, or SLA paths.

How often should we re-verify slugs?

On every model change PR and on a scheduled dependency review (for example monthly).

Where do provider data policies fit?

In route config and account privacy settings - expand in the cost and fallback section.

What is the minimum log schema?

request_id, policy, requested_model, resolved_model, status, latency_ms, prompt_tokens, completion_tokens, error_type.

Can framework defaults replace this checklist?

They help with client construction.

They rarely enforce policy maps, fallback discipline, or smoke tests for you.

How do credit limits interact with best practices?

Per-key limits are a safety rail, not a substitute for agent max-turn budgets.

Should streaming be default?

Default on for user-facing chat; default off for batch evals and many background agents.

What belongs in CI vs production monitors?

CI: auth shape, slug validation, unit tests for the resolver.

Production: error rate, p95 latency, cost per successful task, fallback rate.

How does this relate to agent fundamentals model-swapping rules?

Those rules are product-level.

This checklist is the OpenRouter-specific implementation of the same idea.

When should we add a second gateway?

When OpenRouter is a single point of failure for a critical path and the business accepts multi-key operational cost.

OpenRouter Setup & Routing Basics - first working call
Authenticating and Configuring the OpenRouter Base URL - client factory
Switching Models by Config, Not Code: A Routing Pattern - policy maps
Auto-Router: Letting OpenRouter Pick the Best Model for a Prompt - constrained auto
Troubleshooting Common OpenRouter Setup Errors - failure checklist
How Model Routing Actually Works Under an OpenRouter Request - conceptual backbone

Stack versions: Pins from the category manifest (verify at build): OpenRouter (~315+ models, July 2026 pricing/fees); LangGraph 1.0+; CrewAI 1.14+; Microsoft Agent Framework 1.0; Vercel AI SDK 6; Pydantic AI (latest); LlamaIndex (latest); OpenAI Agents SDK (latest + MCP); MCP (Linux Foundation governance); A2A (HTTP+SSE+JSON-RPC 2.0); Solana @solana/web3.js + @solana/spl-token.

OpenRouter Setup & Routing Best Practices

Ten practices for a clean, swappable OpenRouter integration from day one.

Use this list when wiring the first gateway client so auth, slugs, routing, and observability do not need a rewrite two sprints later.

How to Use This Checklist

Work A through D in order for a new service.
Require evidence for each item - a file path, env name, log field, or PR link.
Revisit when you add agents, raise traffic, or change model vendors.
Pair with the troubleshooting cheatsheet when something is already on fire.

A - Client and Secrets

1. Centralize base URL and API key in one client factory. Every call site imports the factory; nobody retypes https://openrouter.ai/api/v1.
2. Load OpenRouter keys from a secret store, never from git. Separate keys per environment with optional per-key credit limits.
3. Keep optional attribution headers out of the credential path. HTTP-Referer and X-OpenRouter-Title are rankings metadata, not auth.

B - Model Identity

4. Address models through logical policies, not scattered raw slugs. Map fast / balanced / strong (or route names) in config.
5. Copy slugs from the live catalog and verify at build. Pin versions for production agents; treat latest aliases as deliberate drift.
6. Log requested slug, resolved response.model, usage, and latency every call. Especially for auto-router and fallback chains.

C - Routing Resilience

7. Decide fallbacks explicitly. Use OpenRouter models arrays and/or provider preferences; avoid improvised retry-to-random-model code.
8. Constrain Auto Router before enabling it on paid traffic. Allowlists, cost/quality tradeoff, session ids, and spend caps.
9. Separate streaming UX concerns from failover hopes. Mid-stream errors cannot silently change providers after tokens started.

D - Operability

10. Ship smoke tests: curl auth, non-stream completion, stream comment-safe parse, and one invalid-model negative test. Run them in CI against a cheap model.

Expanded Practice Notes

1-3 Client hygiene

# one module, many importers
from app.llm.openrouter import client, complete

Rotate keys on any exposure alert.

Do not embed keys in frontends.

4-6 Config and logging

{
  "balanced": {
    "model": "anthropic/claude-sonnet-4.5",
    "fallbacks": ["openai/gpt-4o-mini"]
  }
}

Illustrative slugs only - verify at build.

Emit structured logs:

policy=balanced requested=anthropic/claude-sonnet-4.5 resolved=... tokens=... ms=...

7-9 Routing

Prefer price/uptime defaults until you have a compliance reason to pin providers.

When you pin, document why allow_fallbacks is false.

For agents, pass session_id when using openrouter/auto so multi-turn model choice stays sticky.

10 Smoke tests

Test	Expect
curl with valid key	200 + content
wrong key	401
bad slug	400
stream	tokens without JSON parse crash on comments
fallback map (optional)	resolved model logged

FAQs

Do all ten apply to a weekend prototype?

Practices 1-3 and 10 are enough for a prototype.

Add 4-9 before shared production traffic.

Is OpenRouter required for model swapping?

No.

The policy-map habit applies to direct providers too; OpenRouter makes multi-model ops easier.

Should every team use openrouter/auto?

No.

Use it for mixed unknown prompts with constraints; pin models for scored, regulated, or SLA paths.

How often should we re-verify slugs?

On every model change PR and on a scheduled dependency review (for example monthly).

Where do provider data policies fit?

In route config and account privacy settings - expand in the cost and fallback section.

What is the minimum log schema?

request_id, policy, requested_model, resolved_model, status, latency_ms, prompt_tokens, completion_tokens, error_type.

Can framework defaults replace this checklist?

They help with client construction.

They rarely enforce policy maps, fallback discipline, or smoke tests for you.

How do credit limits interact with best practices?

Per-key limits are a safety rail, not a substitute for agent max-turn budgets.

Should streaming be default?

Default on for user-facing chat; default off for batch evals and many background agents.

What belongs in CI vs production monitors?

CI: auth shape, slug validation, unit tests for the resolver.

Production: error rate, p95 latency, cost per successful task, fallback rate.

How does this relate to agent fundamentals model-swapping rules?

Those rules are product-level.

This checklist is the OpenRouter-specific implementation of the same idea.

When should we add a second gateway?

When OpenRouter is a single point of failure for a critical path and the business accepts multi-key operational cost.

OpenRouter Setup & Routing Basics - first working call
Authenticating and Configuring the OpenRouter Base URL - client factory
Switching Models by Config, Not Code: A Routing Pattern - policy maps
Auto-Router: Letting OpenRouter Pick the Best Model for a Prompt - constrained auto
Troubleshooting Common OpenRouter Setup Errors - failure checklist
How Model Routing Actually Works Under an OpenRouter Request - conceptual backbone

Stack versions: Pins from the category manifest (verify at build): OpenRouter (~315+ models, July 2026 pricing/fees); LangGraph 1.0+; CrewAI 1.14+; Microsoft Agent Framework 1.0; Vercel AI SDK 6; Pydantic AI (latest); LlamaIndex (latest); OpenAI Agents SDK (latest + MCP); MCP (Linux Foundation governance); A2A (HTTP+SSE+JSON-RPC 2.0); Solana @solana/web3.js + @solana/spl-token.

OpenRouter Setup & Routing Best Practices

Search Documentation

OpenRouter Setup & Routing Best Practices