> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Compactação de contexto para conversas longas

> Resuma os turnos mais antigos de uma conversa da Responses API em um único item de compactação para que um histórico longo continue dentro da janela de contexto do modelo.

Consulte [URLs e autenticação HTTP](/docs/pt-BR/reference/base-urls.md) 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](/docs/pt-BR/ai-gateway/features/responses-api.md), 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`.

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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.

> [!NOTE]
>
> 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](/docs/pt-BR/ai-gateway/features/responses-api.md#statefulness).

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
# 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](#provider-native-compaction). |

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.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "context_management": [
    { "type": "compaction", "compact_threshold": 1000, "provider_native": true }
  ]
}
```

> [!NOTE]
>
> 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](/docs/pt-BR/ai-gateway/features/prompt-caching.md).

## 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 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.