Compactação de contexto para conversas longas

Consulte URLs e autenticação HTTP e a referência da API para os formatos completos de solicitação e resposta. Casos de uso

Manter um loop de agente longo dentro da janela de contexto, resumindo os turnos que já não alteram o resultado.
Reduzir os tokens de entrada de cada turno seguinte, que de outra forma reenviariam o histórico completo.
Compactar sob demanda, em vez de esperar que um limite seja ultrapassado.

Visão geral

A compactação de contexto resume os itens mais antigos de uma conversa por meio de um modelo e os substitui por um único item de compactação, mantendo os itens mais recentes literalmente. Trata-se de uma reescrita do histórico, não de compressão ou truncamento do prompt. O resumo é escrito para preservar o que um agente que dá continuidade à conversa precisa:

Decisões tomadas e sua justificativa.
Arquivos lidos ou modificados e seu estado atual.
Resultados de ferramentas que ainda são relevantes.
Tarefas em aberto e questões não resolvidas.

A sumarização tem perdas. Um turno omitido pelo resumo não pode ser recuperado a partir do item de compactação, portanto mantenha a transcrição original sempre que o detalhe for importante. A compactação se aplica à Responses API, que mantém o estado da conversa no servidor. Recorra a ela quando o histórico de uma conversa ultrapassar a janela de contexto do modelo ou quando os tokens de entrada dominarem a fatura.

Início rápido

POST /v3/router/responses/compact resume uma conversa e retorna a próxima janela de contexto a partir da qual continuar. A mesma operação está disponível na base compatível com OpenAI como POST /v1/responses/compact.

curl -X POST https://router.toqan.ai/eu/v3/router/responses/compact \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o",
    "input": [
      { "type": "message", "role": "user", "content": [{ "type": "input_text", "text": "We chose Postgres for the managed failover." }] },
      { "type": "message", "role": "assistant", "content": [{ "type": "input_text", "text": "Recorded." }] },
      { "type": "message", "role": "user", "content": [{ "type": "input_text", "text": "Add the migration." }] }
    ]
  }'

Versões dos SDKs geradas antes desta mudança de esquema tipam o content de uma mensagem como string; o corpo REST aceita uma string ou um array de partes de conteúdo.

{
  "id": "resp_01m47nq46dmgc1rqa7wmgje0hh",
  "object": "response.compaction",
  "output": [
    {
      "type": "compaction",
      "id": "cmpct_01m47nq46d2v7e3cq1xyh073xw",
      "encrypted_content": "### Decisions Made\n- Database: Postgres, chosen for the managed failover.\n\n### Outstanding Tasks\n- Add the migration.",
      "created_by": "openai/gpt-4o"
    }
  ],
  "created_at": 1791259021,
  "usage": { "input_tokens": 156, "output_tokens": 49, "total_tokens": 205 }
}

Campos da requisição

Parâmetro	Tipo	Obrigatório	Descrição
`model`	string	Sim	Modelo que escreve o resumo.
`input`	string ou array	Não	Conversa a ser compactada, como string ou lista de itens.
`prompt_cache_key`	string	Não	Chave de cache para a chamada de sumarização.

O endpoint não tem limite, e uma conversa curta é compactada por inteiro. Uma conversa mais longa mantém os cerca de 20.000 tokens mais recentes literalmente, fora do resumo. O output da resposta contém o item de compactação seguido desses itens recentes; por isso, continue a partir do output inteiro. Somente uma conversa que cabe na reserva volta apenas como o item de compactação.

Compactação automática

Defina context_management em uma requisição Responses de continuação e o gateway compactará à medida que a conversa crescer:

Ele carrega o histórico armazenado a partir de previous_response_id.
Tudo o que for mais antigo que a reserva é resumido em um único item.
O item é inserido no início do output da resposta.

A passagem lê o histórico que o gateway carregou, portanto a resposta que está sendo continuada precisa estar armazenada. store tem true como padrão; um primeiro turno enviado com store: false não tem histórico para compactar. Consulte Statefulness.

# Second turn of a stored conversation. Once the history loaded from
# previous_response_id passes compact_threshold tokens, the older items
# are replaced by one compaction item.
curl -X POST https://router.toqan.ai/eu/v3/router/responses \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o",
    "previous_response_id": "resp_01m47nq46dmgc1rqa7wmgje0hh",
    "context_management": [
      { "type": "compaction", "compact_threshold": 1000 }
    ],
    "input": "Confirm the decisions so far."
  }'

Campos da entrada

context_management recebe uma lista de entradas. Uma entrada compaction contém:

Parâmetro	Tipo	Obrigatório	Descrição
`type`	string	Sim	`compaction` é a entrada aceita.
`compact_threshold`	integer	Não	Quantidade de tokens que o histórico carregado precisa exceder antes que a passagem seja executada. Sem ele, a entrada não faz nada. Modelos da OpenAI exigem no mínimo `1000`.
`provider_native`	boolean	Não	Permite que um modelo da OpenAI compacte por meio do provedor em vez do gateway. Consulte Compactação nativa do provedor.

A passagem é executada apenas sobre o histórico que o gateway carregou, seja a partir de previous_response_id ou de uma conversa. Os itens enviados no corpo da requisição atual não fazem parte dele, portanto uma única requisição grande demais não é reduzida.

Limite e reserva

A passagem é executada somente quando o histórico carregado excede compact_threshold. Tudo o que for mais antigo que a janela de reserva é enviado ao sumarizador; a própria reserva permanece literal.

`compact_threshold`	Tokens recentes mantidos literalmente
40000 ou mais	20000
Abaixo de 40000	Metade do limite

Continuar a partir de um item de compactação

Envie o output de uma chamada de compactação de volta no input de uma requisição Responses posterior para continuar a partir do resumo e dos itens recentes que ele mantém. O gateway lê um item pelo seu formato, não pela sua origem:

Um item compaction sem content, com created_by e com encrypted_content é expandido em uma mensagem de developer, de modo que o modelo lê seu texto como contexto.
Qualquer outro item mantém seu próprio envelope e é repassado sem alterações.

Compactação nativa do provedor

Um modelo da OpenAI pode compactar por meio do provedor em vez do gateway. Toda entrada compaction é encaminhada à OpenAI junto com a requisição, independentemente do valor de provider_native; portanto, defina a flag como true para desativar a passagem própria do gateway: o provedor então aplica sozinho sua compactação e retorna o item em seu próprio formato.

{
  "context_management": [
    { "type": "compaction", "compact_threshold": 1000, "provider_native": true }
  ]
}

A configuração se aplica a modelos da OpenAI. Em todos os outros modelos, o gateway realiza a passagem.

Cache de prompt

A compactação é uma chamada de modelo por si só e carrega o prompt_cache_key da requisição quando ele está definido, de modo que a requisição de sumarização participa do cache de prompt como qualquer outra chamada. Consulte Cache de prompt.

Limitações

Limitação	Impacto	Alternativa
A passagem abrange apenas o histórico carregado	Os itens enviados na requisição atual nunca são compactados, portanto uma única requisição grande demais não é reduzida	Continue a conversa com `previous_response_id`
`compact_threshold` não tem efeito sozinho	Sem o campo, a entrada não faz nada	Defina o limite ou chame o endpoint de compactação
Um limite abaixo de 1000 falha em modelos da OpenAI	O provedor rejeita a requisição com `integer_below_min_value`	Use `1000` ou mais
A sumarização tem perdas	Detalhes omitidos pelo resumo não podem ser recuperados a partir do item de compactação	Mantenha a transcrição original ou aumente o limite para que os turnos recentes permaneçam literais
A procedência do item não é verificada	Um item `compaction` com o mesmo formato dos itens do próprio gateway é expandido em uma mensagem de developer, e `encrypted_content` contém texto simples enquanto `created_by` é fornecido pelo chamador; assim, texto de qualquer origem pode chegar ao modelo nessa função	Reenvie apenas itens retornados pelo gateway e trate o resumo como texto controlado pelo chamador

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

Compactação de contexto para conversas longas

Visão geral

Início rápido

Campos da requisição

Compactação automática

Campos da entrada

Limite e reserva

Continuar a partir de um item de compactação

Compactação nativa do provedor

Cache de prompt

Limitações

​Visão geral

​Início rápido

​Campos da requisição

​Compactação automática

​Campos da entrada

​Limite e reserva

​Continuar a partir de um item de compactação

​Compactação nativa do provedor

​Cache de prompt

​Limitações

Visão geral

Início rápido

Campos da requisição

Compactação automática

Campos da entrada

Limite e reserva

Continuar a partir de um item de compactação

Compactação nativa do provedor

Cache de prompt

Limitações