Fluxo de Decisão de Roteamento

O Floopy tem várias camadas que podem decidir qual provedor e modelo atendem uma requisição: o corpo da requisição, headers, prompts, testes A/B, Smart Selector, regras de roteamento, Smart Cost e roteamento por feedback. Configure várias delas e elas vão discordar.

Esta página é o critério de desempate. Ela lista cada camada na ordem em que executa, diz o que cada uma pode sobrescrever e responde diretamente: se tudo estiver configurado ao mesmo tempo, o que de fato é chamado?

A lista de targets da regra de roteamento decide o (provedor, modelo) final. Tudo acima — corpo da requisição, headers, prompts, Smart Selector — alimenta essa decisão, mas uma regra de roteamento despacha os seus próprios targets, e o modelo do target é o que vai para o provedor.

Duas coisas sobrescrevem a lista de targets:

1. Smart Cost, quando troca o modelo, vira o target primário e os targets da regra viram fallbacks dele.
2. O loop de agente MCP, quando ativo, assume o despacho por completo.

Se não houver regra de roteamento, não há targets, e o modelo resolvido acima (corpo da requisição, prompt ou modelo padrão do provedor) é o usado.

Cada camada executa depois da anterior, então uma camada posterior sobrescreve a anterior.

O model do corpo da requisição é o ponto de partida. O header floopy-model-override o substitui por completo, antes de qualquer outra coisa — nada depois dele chega a ver o valor original.

Os dois escolhem uma variante, mas não são equivalentes:

• O Smart Selector pode definir modelo e provedor.
• Um teste A/B só troca qual prompt é usado. Ele nunca define um modelo.

Quando os dois estão configurados, o Smart Selector vence e o teste A/B não é consultado.

Um prompt pode carregar seu próprio modelo e provedor, que sobrescrevem o corpo da requisição.

O prompt_overwrite inverte isso: devolve o controle ao cliente, então o modelo do corpo da requisição vence o do prompt. Ele também faz o provedor do prompt ser descartado.

Ele é definido no prompt pelo dashboard, e o header floopy-prompt-overwrite sobrescreve essa coluna nos dois sentidos — uma requisição pode forçá-lo a ligado para um prompt que o tem desligado, e vice-versa.

Usado só quando nada acima resolveu um modelo. É um piso, não um override.

O Smart Cost classifica a complexidade do prompt e, nos níveis simples e moderado, troca por um modelo mais barato entre os provedores que você configurou na regra.

Quando ele troca, a escolha dele vira o target primário da regra, e os seus targets configurados ficam atrás como fallbacks — então uma troca que falha ainda degrada para a sua lista em vez de dar erro.

Um prompt complexo ignora o Smart Cost por completo e deixa a sua estratégia configurada intacta. Ou seja: o Smart Cost é dono do nível barato, e a sua estratégia de roteamento — inclusive o roteamento por feedback — é dona de tudo que o Smart Cost recusar.

É aqui que o modelo é finalmente decidido. Uma regra de roteamento despacha os próprios targets, e cada target carrega seu próprio (provedor, modelo). Qualquer que seja o target escolhido pela estratégia, é o modelo daquele target que vai para o provedor — o modelo resolvido nas camadas 1–7 é substituído.

Dentro da regra, a estratégia escolhe qual target:

• O roteamento por feedback, se o seu plano o habilita, substitui inteiramente a estratégia configurada na regra. Uma regra definida como weighted não se comportará como weighted para uma organização em roteamento por feedback.
• Caso contrário, roda a estratégia da própria regra: fallback, round-robin, weighted ou latency-based.

Se um target é pulado (sem API key, provedor desconhecido, circuit breaker aberto) ou falha, o próximo é tentado.

Se o seu plano tem MCP outbound e a organização tem ao menos um servidor outbound habilitado, a requisição entra no loop de agente em vez da cadeia normal de estratégias. Envie floopy-mcp-disabled para desativar por requisição.

flowchart TD
    A[Modelo do corpo da requisição] --> B{Header floopy-model-override?}
    B -->|sim| C[Modelo do header substitui]
    B -->|não| D[Mantém o modelo do corpo]
    C --> E{Smart Selector?}
    D --> E

    E -->|sim| F[Smart Selector define modelo + provedor<br/>Teste A/B é ignorado]
    E -->|não| G{Teste A/B?}
    G -->|sim| H[Troca só o prompt<br/>modelo inalterado]
    G -->|não| I[Sem variante]

    F --> J{Prompt resolvido?}
    H --> J
    I --> J

    J -->|sim| K{prompt_overwrite?}
    J -->|não| L{Modelo ainda vazio?}

    K -->|false| M[Modelo + provedor do prompt vencem]
    K -->|true| N[Modelo da requisição vence<br/>provedor do prompt descartado]

    M --> O
    N --> O
    L -->|sim| P[Modelo padrão do provedor]
    L -->|não| O[Modelo resolvido]
    P --> O

    O --> Q{Agente MCP ativo?}
    Q -->|sim| R[Loop de agente assume o despacho]
    Q -->|não| S{Existe regra de roteamento?}

    S -->|não| T[Cascata legada<br/>o modelo resolvido é despachado]
    S -->|sim| U{Smart Cost habilitado<br/>e prompt não complexo?}

    U -->|sim| V[Modelo mais barato vira target PRIMÁRIO<br/>targets configurados viram fallbacks<br/>estratégia fixada em fallback]
    U -->|não| W{Roteamento por feedback?}

    W -->|sim| X[Pontua os targets, ignora a estratégia da regra<br/>explora conforme o orçamento de exploração]
    W -->|não| Y[Estratégia da regra:<br/>fallback / round-robin / weighted / latency]

    V --> Z
    X --> Z
    Y --> Z[Despacha o target<br/>MODELO DO TARGET substitui o modelo resolvido]

    Z --> AA{Target OK?}
    AA -->|pulado ou falhou| AB[Tenta o próximo target]
    AB --> Z
    AA -->|sucesso| AC[Resposta]
    T --> AC
    R --> AC

Chega uma requisição com:

• corpo model: "gpt-4o"
• header floopy-model-override: gpt-4o-mini
• um prompt cujo modelo é claude-sonnet-5, com prompt_overwrite = false
• uma regra de roteamento com targets [openai/gpt-4o, anthropic/claude-3], estratégia weighted
• Smart Cost habilitado, com openai/gpt-4o-mini configurado para o nível simples
• a organização em um plano com roteamento por feedback

O que acontece:

1. O header substitui o modelo do corpo → gpt-4o-mini.
2. O prompt define o modelo → claude-sonnet-5 (prompt_overwrite é false, então o prompt vence).
3. O prompt é simples, então o Smart Cost troca por openai/gpt-4o-mini e o torna o target primário. Os targets da regra viram fallbacks, e a estratégia é fixada em fallback.
4. openai/gpt-4o-mini é chamado. Se falhar, tenta-se openai/gpt-4o, depois anthropic/claude-3.

Repare no que não aconteceu: weighted nunca rodou, o roteamento por feedback nunca rodou, e nem gpt-4o nem claude-sonnet-5 foram chamados. O Smart Cost recusa em um prompt complexo — e só então o roteamento por feedback pontuaria os dois targets da regra e escolheria entre eles.

O roteamento por feedback e o Smart Cost nem sempre escolhem o modelo de melhor pontuação — isso significaria nunca testar mais nada, e um modelo que perde uma vez perderia para sempre, porque nunca é despachado e portanto nunca coleta os dados que o fariam vencer.

Uma fração do tráfego explora. Um sorteio por requisição, semeado pelo id da requisição, para que a decisão seja reproduzível:

A fatia de não testados sai de dentro do orçamento de exploração, ela não é somada a ele. Com uma taxa de exploração de 20% e uma fatia de não testados de 50%, os modelos não testados recebem 10% de todo o tráfego e a exploração pontuada recebe os outros 10%. A exploração total continua sendo 20%.

Um modelo sem histórico não tem nota de qualidade, então a barreira o julgaria pelo benchmark estático — e um modelo sem benchmark publicado recebe um valor neutro padrão que fica abaixo da nota mínima usual. Ele seria filtrado antes que a exploração pudesse testá-lo, e assim nunca conquistaria a nota que o deixaria passar. A própria barreira é o que o manteria não testado.

Defina a fatia de não testados como 0% para desativar isso e explorar apenas modelos que já passam da nota mínima.

Os dois valores são configurados em Roteamento → Por feedback no dashboard, e a porcentagem efetiva sobre o tráfego total aparece abaixo do slider.

• Estratégias de roteamento — como fallback, round-robin, weighted e latency-based distribuem o tráfego
• Smart Cost Routing
• Roteamento por feedback
• Prompts
• Explicando uma decisão — pergunte ao gateway por que ele escolheu o que escolheu, para uma requisição específica