Session Affinity

Um Smart Router escolhe um modelo por requisição. Em uma conversa com vários turnos, isso significa que cada turno é pontuado novamente e pode ir para um modelo diferente, o que reinicia o cache de prompt do provedor. A Session affinity fixa uma conversa no modelo escolhido no primeiro turno. Os turnos seguintes reutilizam esse modelo sem chamada de pontuação no caminho da requisição e mantêm o cache aquecido. A session affinity vem desativada por padrão e é configurada por router. Só participam as requisições que levam um ID de thread ou, no endpoint Responses, um ID de conversa. Todo o resto continua sendo roteado por requisição, como antes.

Casos de uso

Assistentes de chat e copilots em que turnos consecutivos compartilham um prompt de sistema ou um conjunto de ferramentas longo e se beneficiam do cache de prompt do provedor.
Loops de agentes que chamam o router várias vezes por turno do usuário e não devem trocar de modelo no meio do caminho.
Conversas de suporte em que o tom e o nível de detalhe devem permanecer consistentes da primeira à última resposta.

Habilitar a Session Affinity

Na interface

Abra o Smart Router no AI Gateway e edite-o, ou crie um novo.
Em Session affinity, ative Pin conversations to one model.
Defina Pin for como a janela de inatividade: 1, 5, 10, 30 ou 60 minutos. O padrão é 10 minutos.
Clique em Save changes, ou em Create no caso de um router novo.

Pela API

Envie session_affinity ao criar ou atualizar um Smart Router. ttl_seconds é a janela de inatividade em segundos, entre 60 e 3600, e o padrão é 600 quando omitido. Na atualização, o objeto é substituído por inteiro; omitir ttl_seconds redefine a janela para o padrão de 600.

curl -X PATCH https://router.toqan.ai/eu/v2/smart-routers/$SMART_ROUTER_ID \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "session_affinity": { "enabled": true, "ttl_seconds": 600 }
  }'

const response = await fetch(
  `https://router.toqan.ai/eu/v2/smart-routers/${process.env.SMART_ROUTER_ID}`,
  {
    method: "PATCH",
    headers: {
      Authorization: `Bearer ${process.env.TOQAN_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      session_affinity: { enabled: true, ttl_seconds: 600 },
    }),
  },
);

console.log(await response.json());

import os
import requests

response = requests.patch(
    f"https://router.toqan.ai/eu/v2/smart-routers/{os.environ['SMART_ROUTER_ID']}",
    headers={"Authorization": f"Bearer {os.environ['TOQAN_API_KEY']}"},
    json={"session_affinity": {"enabled": True, "ttl_seconds": 600}},
)

print(response.json())

O mesmo objeto é aceito em POST /v2/smart-routers. Consulte a referência da API de Smart Routers.

Definir a origem da fixação

A fixação é indexada por um ID enviado por quem faz a chamada. Nada é derivado do conteúdo das mensagens.

Endpoint	Origem	Como enviar
`/v3/router/chat/completions`	ID de thread	`thread.id` no corpo ou o header `X-TOQAN-THREAD-ID`
`/v3/anthropic/v1/messages`	ID de thread	`thread.id` no corpo ou o header `X-TOQAN-THREAD-ID`
`/v3/router/responses`	ID de thread; se ausente, ID de conversa	`thread.id` ou `X-TOQAN-THREAD-ID`; `conversation.id` quando nenhum ID de thread é enviado
`/v2/deployments/invoke`	ID de thread	`thread.id` no corpo ou o header `X-TOQAN-THREAD-ID`
Agents	ID de thread; se ausente, ID de conversa	Igual ao endpoint Responses

Quando ambos estão presentes, o corpo prevalece sobre o header. Um ID de thread e um ID de conversa com o mesmo valor geram duas fixações independentes. Consulte Request Metadata para o campo thread e os headers.

Início rápido

Chame o Smart Router duas vezes com o mesmo ID de thread. O primeiro turno é pontuado e retorna X-Orq-Session-Affinity: miss; o segundo turno reutiliza o modelo fixado e retorna hit.

for turn in "What does the refund policy say about digital goods?" "And for physical goods?"; do
  curl -s -D - -o /dev/null -X POST https://router.toqan.ai/eu/v3/router/chat/completions \
    -H "Authorization: Bearer $TOQAN_API_KEY" \
    -H "Content-Type: application/json" \
    -d "{
      \"model\": \"workspace_name@orq/my-smart-router\",
      \"messages\": [{ \"role\": \"user\", \"content\": \"$turn\" }],
      \"thread\": { \"id\": \"conversation-abc123\" }
    }" | grep -i x-orq-session-affinity
done

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.TOQAN_API_KEY,
  baseURL: "https://router.toqan.ai/eu/v3/router",
});

const thread = { id: "conversation-abc123" };

for (const content of [
  "What does the refund policy say about digital goods?",
  "And for physical goods?",
]) {
  const { data, response } = await client.chat.completions
    .create({
      model: "workspace_name@orq/my-smart-router",
      messages: [{ role: "user", content }],
      // @ts-expect-error Toqan Router extension
      thread,
    })
    .withResponse();

  console.log(response.headers.get("x-orq-session-affinity"), data.model);
}

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ.get("TOQAN_API_KEY"),
    base_url="https://router.toqan.ai/eu/v3/router",
)

for content in [
    "What does the refund policy say about digital goods?",
    "And for physical goods?",
]:
    raw = client.chat.completions.with_raw_response.create(
        model="workspace_name@orq/my-smart-router",
        messages=[{"role": "user", "content": content}],
        extra_body={"thread": {"id": "conversation-abc123"}},
    )
    print(raw.headers.get("x-orq-session-affinity"), raw.parse().model)

O campo model na resposta indica o modelo concreto nos dois turnos.

Como a fixação é decidida

O primeiro turno de uma thread é pontuado e roteado normalmente. A fixação só é gravada depois que a primeira chamada ao provedor desse turno é bem-sucedida, então um primeiro turno com falha ou repetido nunca fixa um modelo. Um turno que o avaliador não conseguiu classificar com confiança é atendido, mas não fixado; o turno seguinte tenta novamente. Em um hit, a requisição vai direto para o modelo fixado, sem chamada de pontuação no caminho da requisição, e a janela de inatividade é renovada. Hits Easy e Medium ainda disparam uma chamada de pontuação em segundo plano para o escalonamento; hits Hard não disparam nenhuma.

Escalonamento

Uma thread que começa fácil pode se tornar difícil. Em todo hit com uma fixação Easy ou Medium, o router pontua o turno novamente em segundo plano. Quando a nova pontuação cai em uma faixa superior, a fixação sobe para o modelo dessa faixa e permanece lá. Uma fixação nunca desce: um rebaixamento reiniciaria o cache do provedor em troca de uma economia pequena. Fixações Hard nunca são pontuadas novamente. O escalonamento mantém o tempo de vida restante da fixação, de modo que dois turnos concorrentes na mesma thread não conseguem fazer a decisão retroceder.

Tempo de vida da fixação

A janela de inatividade é deslizante. Cada hit a renova, então uma conversa ativa mantém seu modelo enquanto permanecer ativa, e uma thread que fica inativa por mais tempo que a janela é roteada do zero no turno seguinte. Não há limite absoluto. Uma fixação é descartada, e a requisição passa a ser roteada por requisição, quando:

O modelo fixado falha na primeira chamada ao provedor de um turno.
O modelo fixado não está mais no pool do router ou não pode mais ser chamado no workspace.
A fixação armazenada não pode ser interpretada.

Quando o armazenamento das fixações não pode ser lido, a fixação é ignorada naquele turno e o turno é roteado do zero. Uma fixação descartada ou ignorada nunca faz a requisição falhar.

Onde se aplica

Superfície	Session affinity	Header `X-Orq-Session-Affinity`
`/v3/router/chat/completions`	Sim	`hit` ou `miss`
`/v3/anthropic/v1/messages`	Sim	`hit` ou `miss`
`/v3/router/responses`	Sim	`hit` ou `miss`
`/v2/deployments/invoke` (JSON e streaming)	Sim, quando o modelo da variante é um Smart Router	`hit` ou `miss`
Agents cujo modelo principal é um Smart Router	Sim	Não definido
Respostas em segundo plano (`background: true`)	Apenas lê uma fixação existente	`hit` ou `miss`

Nos endpoints Responses e Messages, um turno que executa um loop de ferramentas define a fixação apenas na primeira chamada ao provedor. Subagentes fazem a fixação sob seu próprio router e sua própria chave. Execuções agendadas de agentes não levam ID de thread nem de conversa e são roteadas por requisição.

Observabilidade

Toda requisição roteada registra a decisão em seu span:

Atributo	Significado
`orq.session_affinity.enabled`	A session affinity está ativada para este router
`orq.session_affinity.seed`	`thread` ou `conversation`
`orq.session_affinity.hit`	O turno reutilizou uma fixação
`orq.session_affinity.ttl_seconds`	A janela de inatividade do router
`orq.session_affinity.escalated`	A fixação subiu neste turno
`orq.session_affinity.escalated_from`, `orq.session_affinity.escalated_to`	As faixas envolvidas

Os atributos de escalonamento são registrados em um span auto-router.escalation separado, no mesmo trace, porque a nova pontuação é executada depois que a resposta é enviada.

Uma fixação guarda o nome de um modelo, uma faixa e um timestamp. Nenhum conteúdo de mensagem ou dado de usuário é armazenado com ela.

Limitações

Limitação	Impacto	Alternativa
Exige um ID de thread ou ID de conversa	Requisições sem nenhum dos dois são roteadas por requisição	Envie `thread.id`, o header `X-TOQAN-THREAD-ID` ou `conversation.id` no endpoint Responses
As fixações são por router	Um load balancer na frente de vários Smart Routers redistribui as requisições a cada turno	Ative a session affinity em um único Smart Router e chame-o diretamente
As fixações são por chave de API e identidade	A mesma thread chamada com outra chave de API ou identidade recebe sua própria fixação	Mantenha uma única chave de API e identidade por conversa
Respostas em segundo plano	Requisições `background: true` reutilizam uma fixação, mas nunca gravam nem descartam uma	Inicie a thread com uma requisição em primeiro plano
Agents não retornam o header	A decisão fica visível no span, não na resposta	Filtre os traces por `orq.session_affinity.hit`

Toqan Router

Visão geral

APIs

MCP Portal

Roteamento

Segurança e privacidade

Recursos dos modelos

Ferramentas de servidor

Cenários comuns

Configuração de provedores

Casos de uso

Habilitar a Session Affinity

Na interface

Pela API

Definir a origem da fixação

Início rápido

Como a fixação é decidida

Escalonamento

Tempo de vida da fixação

Onde se aplica

Observabilidade

Limitações

​Casos de uso

​Habilitar a Session Affinity

​Na interface

​Pela API

​Definir a origem da fixação

​Início rápido

​Como a fixação é decidida

​Escalonamento

​Tempo de vida da fixação

​Onde se aplica

​Observabilidade

​Limitações

Casos de uso

Habilitar a Session Affinity

Na interface

Pela API

Definir a origem da fixação

Início rápido

Como a fixação é decidida

Escalonamento

Tempo de vida da fixação

Onde se aplica

Observabilidade

Limitações