Flux RouterDocumentation

Use Flux for a coding agent

Point a coding agent at Flux, let flux-auto pick a model for each call, and pin a strong model only for the steps that need one.

A coding agent does not make one big call. It makes many: read a file, decide the next step, call a tool, summarise the result, plan, edit, repeat. Most of those calls are routine. A few are genuinely hard. Flux is OpenAI-compatible, so any agent that lets you set an OpenAI base URL works without code changes: set the base URL to https://api.fluxrouter.ai/v1, use your Flux key (sk-...), and set the model to flux-auto.

Why flux-auto fits an agent

With flux-auto, Flux picks among vetted models for each kind of task, cost-aware: routine tool calls and short decisions can go to fast models, and hard reasoning steps to stronger ones. You do not have to classify each call yourself.

How it bills: flux-auto bills at the Standard rate, or the Fast rate when it sends your request to the Fast lane and a Fast model answers. Never more than Standard. If you want the Fast rate on every routine call, send those calls to flux-fast yourself, and send the hard ones to flux-reasoning or a pinned model. Rates are on Pricing, and How billing works explains the rest.

Connect a coding tool

If you are using an existing agent or editor (Claude Code, Codex, Cursor, Hermes, OpenClaw, Cline, aider, Continue and others), you usually do not touch code at all. You point the tool at Flux and paste your Flux key. See Connect your agent for the exact setting per tool.

Build your own agent loop

If you are writing the agent yourself, it is the standard OpenAI chat-completions loop with tools. Only the base URL, key, and model differ from a direct OpenAI setup.

python
from openai import OpenAI

client = OpenAI(
    api_key="sk-...",                          # your Flux key
    base_url="https://api.fluxrouter.ai/v1",   # the one line you change
)

tools = [
    {
        "type": "function",
        "function": {
            "name": "read_file",
            "description": "Read a file from the repo.",
            "parameters": {
                "type": "object",
                "properties": {"path": {"type": "string"}},
                "required": ["path"],
            },
        },
    }
]

messages = [{"role": "user", "content": "Find and fix the failing test."}]

while True:
    response = client.chat.completions.create(
        model="flux-auto",
        messages=messages,
        tools=tools,
    )
    msg = response.choices[0].message
    messages.append(msg)

    if not msg.tool_calls:
        print(msg.content)
        break

    for call in msg.tool_calls:
        result = run_tool(call.function.name, call.function.arguments)  # your code
        messages.append({
            "role": "tool",
            "tool_call_id": call.id,
            "content": result,
        })

flux-auto picks a model for each iteration of this loop. For the full tool-calling request and response shape, see Tool and function calling.

Pin a strong model for the hard steps

If a specific step needs a known frontier model every time (for example, the final plan or a tricky refactor), you do not have to send the whole run there. Pin just that call to a strong model with a flux-pinned-* id or a tier alias, and leave the rest of the loop on flux-auto:

python
# Routine steps: let Flux pick
response = client.chat.completions.create(model="flux-auto", messages=messages, tools=tools)

# A hard planning step: pin a strong model just for this call
plan = client.chat.completions.create(model="flux-reasoning", messages=plan_messages)

This gives you a known model exactly where you want one. See Models for the available aliases and flux-pinned-* ids.

Practical tips

  • Retry on 429. Long agent runs make many calls; back off and retry rather than aborting the run.
  • Set a spend cap. Agents can fan out into many calls fast. A per-key cap stops a runaway loop from burning through your budget. See Spend caps.
  • Log which model answered. The X-Flux-Model and X-Flux-Routed response headers show what served each call, which is useful when debugging an agent's behaviour. See Receipts.

Next steps