Loading...
    • Guia do Desenvolvedor
    • Referência da API
    • MCP
    • Recursos
    • Notas de lançamento
    Search...
    ⌘K
    Primeiros passos
    Introdução ao ClaudeInício rápido
    Modelos e preços
    Visão geral dos modelosEscolhendo um modeloNovidades no Claude 4.6Guia de migraçãoDescontinuação de modelosPreços
    Construir com Claude
    Visão geral de recursosUsando a API MessagesTratando motivos de paradaMelhores práticas de prompting
    Capacidades do modelo
    Pensamento estendidoPensamento adaptativoEsforçoModo rápido (visualização de pesquisa)Saídas estruturadasCitaçõesStreaming de mensagensProcessamento em loteSuporte a PDFResultados de pesquisaSuporte multilíngueEmbeddingsVisão
    Ferramentas
    Visão geralComo implementar o uso de ferramentasFerramenta de pesquisa na webFerramenta de busca na webFerramenta de execução de códigoFerramenta de memóriaFerramenta BashFerramenta de uso do computadorFerramenta de editor de texto
    Infraestrutura de ferramentas
    Pesquisa de ferramentasChamada de ferramentas programáticaStreaming de ferramentas de granulação fina
    Gerenciamento de contexto
    Janelas de contextoCompactaçãoEdição de contextoCache de promptsContagem de tokens
    Arquivos e ativos
    API de arquivos
    Habilidades do agente
    Visão geralInício rápidoMelhores práticasHabilidades para empresasUsando habilidades com a API
    SDK do agente
    Visão geralInício rápidoSDK TypeScriptTypeScript V2 (visualização)SDK PythonGuia de migração
    MCP na API
    Conector MCPServidores MCP remotos
    Claude em plataformas de terceiros
    Amazon BedrockMicrosoft FoundryVertex AI
    Engenharia de prompts
    Visão geralGerador de promptsUsar modelos de promptsMelhorador de promptsSeja claro e diretoUse exemplos (prompting multishot)Deixe Claude pensar (CoT)Use tags XMLDê um papel ao Claude (prompts do sistema)Encadear prompts complexosDicas de contexto longoDicas de pensamento estendido
    Testar e avaliar
    Definir critérios de sucessoDesenvolver casos de testeUsando a ferramenta de avaliaçãoReduzindo latência
    Fortalecer proteções
    Reduzir alucinaçõesAumentar consistência de saídaMitigar jailbreaksRecusas de streamingReduzir vazamento de promptsManter Claude em personagem
    Administração e monitoramento
    Visão geral da API de administraçãoResidência de dadosEspaços de trabalhoAPI de uso e custoAPI de análise de código ClaudeRetenção zero de dados
    Console
    Log in
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...
    Loading...

    Solutions

    • AI agents
    • Code modernization
    • Coding
    • Customer support
    • Education
    • Financial services
    • Government
    • Life sciences

    Partners

    • Amazon Bedrock
    • Google Cloud's Vertex AI

    Learn

    • Blog
    • Catalog
    • Courses
    • Use cases
    • Connectors
    • Customer stories
    • Engineering at Anthropic
    • Events
    • Powered by Claude
    • Service partners
    • Startups program

    Company

    • Anthropic
    • Careers
    • Economic Futures
    • Research
    • News
    • Responsible Scaling Policy
    • Security and compliance
    • Transparency

    Learn

    • Blog
    • Catalog
    • Courses
    • Use cases
    • Connectors
    • Customer stories
    • Engineering at Anthropic
    • Events
    • Powered by Claude
    • Service partners
    • Startups program

    Help and security

    • Availability
    • Status
    • Support
    • Discord

    Terms and policies

    • Privacy policy
    • Responsible disclosure policy
    • Terms of service: Commercial
    • Terms of service: Consumer
    • Usage policy
    Gerenciamento de contexto

    Compactação

    Compactação de contexto no servidor para gerenciar conversas longas que se aproximam dos limites da janela de contexto.

    Was this page helpful?

    • Modelos suportados
    • Como a compactação funciona
    • Uso básico
    • Parâmetros
    • Configuração de acionamento
    • Instruções de resumo personalizado
    • Pausando após compactação
    • Trabalhando com blocos de compactação
    • Passando blocos de compactação de volta
    • Streaming
    • Cache de prompt
    • Entendendo o uso
    • Combinando com outros recursos
    • Ferramentas de servidor
    • Contagem de tokens
    • Exemplos
    • Limitações atuais
    • Próximos passos

    A compactação no servidor é a estratégia recomendada para gerenciar contexto em conversas de longa duração e fluxos de trabalho com agentes. Ela gerencia o contexto automaticamente com trabalho de integração mínimo.

    A compactação estende o comprimento efetivo do contexto para conversas e tarefas de longa duração, resumindo automaticamente o contexto mais antigo quando se aproxima do limite da janela de contexto. Isso é ideal para:

    • Conversas baseadas em chat, multi-turno, onde você quer que os usuários usem um chat por um longo período de tempo
    • Prompts orientados a tarefas que requerem muito trabalho de acompanhamento (frequentemente uso de ferramentas) que pode exceder a janela de contexto de 200K

    A compactação está atualmente em beta. Inclua o cabeçalho beta compact-2026-01-12 em suas solicitações de API para usar este recurso.

    This feature is eligible for Zero Data Retention (ZDR). When your organization has a ZDR arrangement, data sent through this feature is not stored after the API response is returned.

    Modelos suportados

    A compactação é suportada nos seguintes modelos:

    • Claude Opus 4.6 (claude-opus-4-6)

    Como a compactação funciona

    Quando a compactação está ativada, Claude resume automaticamente sua conversa quando se aproxima do limite de tokens configurado. A API:

    1. Detecta quando os tokens de entrada excedem seu limite de acionamento especificado.
    2. Gera um resumo da conversa atual.
    3. Cria um bloco compaction contendo o resumo.
    4. Continua a resposta com o contexto compactado.

    Em solicitações subsequentes, anexe a resposta às suas mensagens. A API automaticamente remove todos os blocos de mensagem anteriores ao bloco compaction, continuando a conversa a partir do resumo.

    Diagrama de fluxo mostrando o processo de compactação: quando os tokens de entrada excedem o limite de acionamento, Claude gera um resumo em um bloco de compactação e continua a resposta com o contexto compactado

    Uso básico

    Ative a compactação adicionando a estratégia compact_20260112 a context_management.edits em sua solicitação da API Messages.

    Parâmetros

    ParâmetroTipoPadrãoDescrição
    typestringObrigatórioDeve ser "compact_20260112"
    triggerobject150.000 tokensQuando acionar a compactação. Deve ser pelo menos 50.000 tokens.
    pause_after_compactionbooleanfalseSe deve pausar após gerar o resumo de compactação
    instructionsstringnullPrompt de resumo personalizado. Substitui completamente o prompt padrão quando fornecido.

    Configuração de acionamento

    Configure quando a compactação é acionada usando o parâmetro trigger:

    Instruções de resumo personalizado

    Por padrão, a compactação usa o seguinte prompt de resumo:

    You have written a partial transcript for the initial task above. Please write a summary of the transcript. The purpose of this summary is to provide continuity so you can continue to make progress towards solving the task in a future context, where the raw history above may not be accessible and will be replaced with this summary. Write down anything that would be helpful, including the state, next steps, learnings etc. You must wrap your summary in a <summary></summary> block.

    Você pode fornecer instruções personalizadas através do parâmetro instructions para substituir este prompt completamente. Instruções personalizadas não complementam o padrão; elas o substituem completamente:

    Pausando após compactação

    Use pause_after_compaction para pausar a API após gerar o resumo de compactação. Isso permite que você adicione blocos de conteúdo adicionais (como preservar mensagens recentes ou mensagens específicas orientadas por instruções) antes da API continuar com a resposta.

    Quando ativado, a API retorna uma mensagem com a razão de parada compaction após gerar o bloco de compactação:

    Aplicando um orçamento total de tokens

    Quando um modelo trabalha em tarefas longas com muitas iterações de uso de ferramentas, o consumo total de tokens pode crescer significativamente. Você pode combinar pause_after_compaction com um contador de compactação para estimar o uso cumulativo e encerrar graciosamente a tarefa uma vez que um orçamento é atingido:

    Python
    TRIGGER_THRESHOLD = 100_000
    TOTAL_TOKEN_BUDGET = 3_000_000
    n_compactions = 0
    
    response = client.beta.messages.create(
        betas=["compact-2026-01-12"],
        model="claude-opus-4-6",
        max_tokens=4096,
        messages=messages,
        context_management={
            "edits": [
                {
                    "type": "compact_20260112",
                    "trigger": {"type": "input_tokens", "value": TRIGGER_THRESHOLD},
                    "pause_after_compaction": True,
                }
            ]
        },
    )
    
    if response.stop_reason == "compaction":
        n_compactions += 1
        messages.append({"role": "assistant", "content": response.content})
    
        # Estimate total tokens consumed; prompt wrap-up if over budget
        if n_compactions * TRIGGER_THRESHOLD >= TOTAL_TOKEN_BUDGET:
            messages.append(
                {
                    "role": "user",
                    "content": "Please wrap up your current work and summarize the final state.",
                }
            )

    Trabalhando com blocos de compactação

    Quando a compactação é acionada, a API retorna um bloco compaction no início da resposta do assistente.

    Uma conversa de longa duração pode resultar em múltiplas compactações. O último bloco de compactação reflete o estado final do prompt, substituindo o conteúdo anterior a ele pelo resumo gerado.

    {
      "content": [
        {
          "type": "compaction",
          "content": "Summary of the conversation: The user requested help building a web scraper..."
        },
        {
          "type": "text",
          "text": "Based on our conversation so far..."
        }
      ]
    }

    Passando blocos de compactação de volta

    Você deve passar o bloco compaction de volta para a API em solicitações subsequentes para continuar a conversa com o prompt encurtado. A abordagem mais simples é anexar todo o conteúdo da resposta às suas mensagens:

    Quando a API recebe um bloco compaction, todos os blocos de conteúdo anteriores a ele são ignorados. Você pode:

    • Manter as mensagens originais em sua lista e deixar a API lidar com a remoção do conteúdo compactado
    • Remover manualmente as mensagens compactadas e incluir apenas o bloco de compactação em diante

    Streaming

    Ao fazer streaming de respostas com compactação ativada, você receberá um evento content_block_start quando a compactação começar. O bloco de compactação faz streaming de forma diferente dos blocos de texto. Você receberá um evento content_block_start, seguido por um único content_block_delta com o conteúdo de resumo completo (sem streaming intermediário), e então um evento content_block_stop.

    Cache de prompt

    A compactação funciona bem com cache de prompt. Você pode adicionar um ponto de interrupção cache_control em blocos de compactação para cachear o conteúdo resumido. O conteúdo compactado original é ignorado.

    {
        "role": "assistant",
        "content": [
            {
                "type": "compaction",
                "content": "[summary text]",
                "cache_control": {"type": "ephemeral"}
            },
            {
                "type": "text",
                "text": "Based on our conversation..."
            }
        ]
    }

    Maximizando acertos de cache com prompts de sistema

    Quando a compactação ocorre, o resumo se torna novo conteúdo que precisa ser escrito no cache. Sem pontos de interrupção de cache adicionais, isso também invalidaria qualquer prompt de sistema em cache, exigindo que seja re-cacheado junto com o resumo de compactação.

    Para maximizar as taxas de acerto de cache, adicione um ponto de interrupção cache_control no final do seu prompt de sistema. Isso mantém o prompt de sistema em cache separadamente da conversa, então quando a compactação ocorre:

    • O cache do prompt de sistema permanece válido e é lido do cache
    • Apenas o resumo de compactação precisa ser escrito como uma nova entrada de cache

    Esta abordagem é particularmente benéfica para prompts de sistema longos, pois permanecem em cache mesmo através de múltiplos eventos de compactação ao longo de uma conversa.

    Entendendo o uso

    A compactação requer uma etapa de amostragem adicional, que contribui para limites de taxa e faturamento. A API retorna informações de uso detalhadas na resposta:

    {
      "usage": {
        "input_tokens": 45000,
        "output_tokens": 1234,
        "iterations": [
          {
            "type": "compaction",
            "input_tokens": 180000,
            "output_tokens": 3500
          },
          {
            "type": "message",
            "input_tokens": 23000,
            "output_tokens": 1000
          }
        ]
      }
    }

    O array iterations mostra o uso para cada iteração de amostragem. Quando a compactação ocorre, você verá uma iteração compaction seguida pela iteração principal message. As contagens de tokens da iteração final refletem o tamanho efetivo do contexto após a compactação.

    Os input_tokens e output_tokens de nível superior não incluem o uso da iteração de compactação—eles refletem a soma de todas as iterações não-compactação. Para calcular o total de tokens consumidos e faturados para uma solicitação, some todos os valores no array usage.iterations.

    Se você anteriormente confiava em usage.input_tokens e usage.output_tokens para rastreamento de custos ou auditoria, você precisará atualizar sua lógica de rastreamento para agregar através de usage.iterations quando a compactação está ativada. O array iterations é preenchido apenas quando uma nova compactação é acionada durante a solicitação. Re-aplicar um bloco compaction anterior não incorre em custo de compactação adicional, e os campos de uso de nível superior permanecem precisos nesse caso.

    Combinando com outros recursos

    Ferramentas de servidor

    Ao usar ferramentas de servidor (como busca na web), o acionador de compactação é verificado no início de cada iteração de amostragem. A compactação pode ocorrer múltiplas vezes dentro de uma única solicitação dependendo do seu limite de acionamento e da quantidade de saída gerada.

    Contagem de tokens

    O endpoint de contagem de tokens (/v1/messages/count_tokens) aplica blocos compaction existentes em seu prompt, mas não aciona novas compactações. Use-o para verificar sua contagem efetiva de tokens após compactações anteriores:

    Exemplos

    Aqui está um exemplo completo de uma conversa de longa duração com compactação:

    Aqui está um exemplo que usa pause_after_compaction para preservar as últimas duas mensagens (um turno de usuário + um turno de assistente) verbatim em vez de resumi-las:

    Limitações atuais

    • Mesmo modelo para resumo: O modelo especificado em sua solicitação é usado para resumo. Não há opção de usar um modelo diferente (por exemplo, mais barato) para o resumo.

    Próximos passos

    Livro de receitas de compactação

    Explore exemplos práticos e implementações no livro de receitas.

    Janelas de contexto

    Saiba mais sobre tamanhos de janela de contexto e estratégias de gerenciamento.

    curl https://api.anthropic.com/v1/messages \
         --header "x-api-key: $ANTHROPIC_API_KEY" \
         --header "anthropic-version: 2023-06-01" \
         --header "anthropic-beta: compact-2026-01-12" \
         --header "content-type: application/json" \
         --data \
    '{
        "model": "claude-opus-4-6",
        "max_tokens": 4096,
        "messages": [
            {
                "role": "user",
                "content": "Help me build a website"
            }
        ],
        "context_management": {
            "edits": [
                {
                    "type": "compact_20260112"
                }
            ]
        }
    }'
    response = client.beta.messages.create(
        betas=["compact-2026-01-12"],
        model="claude-opus-4-6",
        max_tokens=4096,
        messages=messages,
        context_management={
            "edits": [
                {
                    "type": "compact_20260112",
                    "trigger": {"type": "input_tokens", "value": 150000},
                }
            ]
        },
    )
    response = client.beta.messages.create(
        betas=["compact-2026-01-12"],
        model="claude-opus-4-6",
        max_tokens=4096,
        messages=messages,
        context_management={
            "edits": [
                {
                    "type": "compact_20260112",
                    "instructions": "Focus on preserving code snippets, variable names, and technical decisions.",
                }
            ]
        },
    )
    response = client.beta.messages.create(
        betas=["compact-2026-01-12"],
        model="claude-opus-4-6",
        max_tokens=4096,
        messages=messages,
        context_management={
            "edits": [{"type": "compact_20260112", "pause_after_compaction": True}]
        },
    )
    
    # Check if compaction triggered a pause
    if response.stop_reason == "compaction":
        # Response contains only the compaction block
        messages.append({"role": "assistant", "content": response.content})
    
        # Continue the request
        response = client.beta.messages.create(
            betas=["compact-2026-01-12"],
            model="claude-opus-4-6",
            max_tokens=4096,
            messages=messages,
            context_management={"edits": [{"type": "compact_20260112"}]},
        )
    # After receiving a response with a compaction block
    messages.append({"role": "assistant", "content": response.content})
    
    # Continue the conversation
    messages.append({"role": "user", "content": "Now add error handling"})
    
    response = client.beta.messages.create(
        betas=["compact-2026-01-12"],
        model="claude-opus-4-6",
        max_tokens=4096,
        messages=messages,
        context_management={"edits": [{"type": "compact_20260112"}]},
    )
    import anthropic
    
    client = anthropic.Anthropic()
    
    with client.beta.messages.stream(
        betas=["compact-2026-01-12"],
        model="claude-opus-4-6",
        max_tokens=4096,
        messages=messages,
        context_management={"edits": [{"type": "compact_20260112"}]},
    ) as stream:
        for event in stream:
            if event.type == "content_block_start":
                if event.content_block.type == "compaction":
                    print("Compaction started...")
                elif event.content_block.type == "text":
                    print("Text response started...")
    
            elif event.type == "content_block_delta":
                if event.delta.type == "compaction_delta":
                    print(f"Compaction complete: {len(event.delta.content)} chars")
                elif event.delta.type == "text_delta":
                    print(event.delta.text, end="", flush=True)
    
        # Get the final accumulated message
        message = stream.get_final_message()
        messages.append({"role": "assistant", "content": message.content})
    response = client.beta.messages.create(
        betas=["compact-2026-01-12"],
        model="claude-opus-4-6",
        max_tokens=4096,
        system=[
            {
                "type": "text",
                "text": "You are a helpful coding assistant...",
                "cache_control": {
                    "type": "ephemeral"
                },  # Cache the system prompt separately
            }
        ],
        messages=messages,
        context_management={"edits": [{"type": "compact_20260112"}]},
    )
    count_response = client.beta.messages.count_tokens(
        betas=["compact-2026-01-12"],
        model="claude-opus-4-6",
        messages=messages,
        context_management={"edits": [{"type": "compact_20260112"}]},
    )
    
    print(f"Current tokens: {count_response.input_tokens}")
    print(f"Original tokens: {count_response.context_management.original_input_tokens}")
    import anthropic
    
    client = anthropic.Anthropic()
    
    messages: list[dict] = []
    
    
    def chat(user_message: str) -> str:
        messages.append({"role": "user", "content": user_message})
    
        response = client.beta.messages.create(
            betas=["compact-2026-01-12"],
            model="claude-opus-4-6",
            max_tokens=4096,
            messages=messages,
            context_management={
                "edits": [
                    {
                        "type": "compact_20260112",
                        "trigger": {"type": "input_tokens", "value": 100000},
                    }
                ]
            },
        )
    
        # Append response (compaction blocks are automatically included)
        messages.append({"role": "assistant", "content": response.content})
    
        # Return the text content
        return next(block.text for block in response.content if block.type == "text")
    
    
    # Run a long conversation
    print(chat("Help me build a Python web scraper"))
    print(chat("Add support for JavaScript-rendered pages"))
    print(chat("Now add rate limiting and error handling"))
    # ... continue as long as needed
    import anthropic
    from typing import Any
    
    client = anthropic.Anthropic()
    
    messages: list[dict[str, Any]] = []
    
    
    def chat(user_message: str) -> str:
        messages.append({"role": "user", "content": user_message})
    
        response = client.beta.messages.create(
            betas=["compact-2026-01-12"],
            model="claude-opus-4-6",
            max_tokens=4096,
            messages=messages,
            context_management={
                "edits": [
                    {
                        "type": "compact_20260112",
                        "trigger": {"type": "input_tokens", "value": 100000},
                        "pause_after_compaction": True,
                    }
                ]
            },
        )
    
        # Check if compaction occurred and paused
        if response.stop_reason == "compaction":
            # Get the compaction block from the response
            compaction_block = response.content[0]
    
            # Preserve the last 2 messages (1 user + 1 assistant turn)
            # by including them after the compaction block
            preserved_messages = messages[-2:] if len(messages) >= 2 else messages
    
            # Build new message list: compaction + preserved messages
            new_assistant_content = [compaction_block]
            messages_after_compaction = [
                {"role": "assistant", "content": new_assistant_content}
            ] + preserved_messages
    
            # Continue the request with the compacted context + preserved messages
            response = client.beta.messages.create(
                betas=["compact-2026-01-12"],
                model="claude-opus-4-6",
                max_tokens=4096,
                messages=messages_after_compaction,
                context_management={"edits": [{"type": "compact_20260112"}]},
            )
    
            # Update our message list to reflect the compaction
            messages.clear()
            messages.extend(messages_after_compaction)
    
        # Append the final response
        messages.append({"role": "assistant", "content": response.content})
    
        # Return the text content
        return next(block.text for block in response.content if block.type == "text")
    
    
    # Run a long conversation
    print(chat("Help me build a Python web scraper"))
    print(chat("Add support for JavaScript-rendered pages"))
    print(chat("Now add rate limiting and error handling"))
    # ... continue as long as needed
    Edição de contexto

    Explore outras estratégias para gerenciar contexto de conversa, como limpeza de resultado de ferramenta e limpeza de bloco de pensamento.