Como Usar a API Claude Opus 4.7

Lena está aqui. Revisei a documentação oficial e os materiais de migração após o lançamento de 16 de abril, esperando que a maior parte fosse familiar. Na maior parte é. Mas há mudanças estruturais suficientes — três mudanças quebrantes na API, um novo sistema de esforço, um tokenizador que altera a contagem de tokens — que tratar isso como uma simples troca de ID de modelo seria um erro.

Aqui está o que descobri quando trabalhei com isso.

O que a API Claude Opus 4.7 Inclui

ID do modelo, janela de contexto, limites de saída e ferramentas

O básico primeiro, porque vale a pena deixar claro.

ID do modelo: claude-opus-4-7. De acordo com visão geral oficial de modelos da Anthropic, ele suporta uma janela de contexto de tokens 1M com preço padrão da API, sem prêmio de contexto longo, e 128k tokens de saída máximo na API síncrona Messages. Na API de Lots de Mensagens, o Opus 4.7 pode chegar a até 300k tokens de saída usando o cabeçalho beta output-300k-2026-03-24.

O conjunto completo de ferramentas é mantido do Opus 4.6: bash, execução de código, uso do computador, editor de texto, busca web, web fetch, conector MCP e ferramentas de memória estão todos disponíveis desde o primeiro dia. O suporte ao Vision está presente em toda a área — e atualizado de forma significativa, sobre o qual voltarei.

Disponível na Claude API, Amazon Bedrock, Google Cloud Vertex AI e Microsoft Foundry — e lançando no GitHub Copilot para usuários do Copilot Pro+, Business e Enterprise. Preços: $5 por milhão de tokens de entrada, $25 por milhão de tokens de saída — inalterados em relação ao Opus 4.6.

O que há de novo vs Opus 4.6

Três coisas são realmente novas na superfície da API:

Pensamento adaptativo como único modo de pensamento. O antigo padrão {"type": "enabled", "budget_tokens": N} desapareceu. Enviá-lo agora retorna um erro 400. O Opus 4.7 usa {"type": "adaptive"} — o modelo decide dinamicamente quanto raciocinar com base na complexidade da tarefa. O pensamento adaptativo está fora de efeito por padrão; você deve habilitá-lo explicitamente se quiser que o modelo pense de qualquer forma.

O nível de esforço xhigh****. Isso fica entre high e max, e é o novo ponto de partida recomendado para casos de uso de programação e agentes. O padrão da API é high; você define xhigh explicitamente através de output_config. Vou mostrar a estrutura abaixo.

Orçamentos de tarefas (beta). Um novo mecanismo que fornece ao modelo um alvo de token consultivo para um loop agentivo inteiro — pensamentos, chamadas de ferramentas, resultados das ferramentas e saída final combinados. O modelo vê uma contagem regressiva em andamento e a usa para priorizar o trabalho e finalizar de forma organizada à medida que o orçamento se esgota.

Também removido: ​parâmetros de amostragem não padrão​. Configurar temperature, top_p ou top_k para qualquer valor não padrão agora retorna um erro 400. Se você estava usando temperature=0 para determinismo, observe que ele nunca garantiu saídas idênticas de qualquer forma — o guia de migração recomenda omitir esses parâmetros completamente.

Configuração mínima da API Claude Opus 4.7

Estrutura da primeira requisição

A requisição mínima funcional para Opus 4.7 é assim:

import anthropic

client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=4096,
    messages=[
        {"role": "user", "content": "Explain the tradeoffs between BFS and DFS for a graph with cycles."}
    ]
)

print(message.content[0].text)

Isso roda sem o pensamento habilitado. O modelo responderá diretamente. Para a maioria das tarefas, este é o ponto de partida adequado — adicione complexidade apenas quando houver razão para isso.

Escolhendo níveis adaptativos de pensamento e esforço

Quando você deseja que o modelo raciocine antes de responder, adicione a configuração de pensamento e defina o esforço explicitamente:

message = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=16384,
    thinking={"type": "adaptive"},
    output_config={"effort": "xhigh"},
    messages=[
        {"role": "user", "content": "Review this pull request for security vulnerabilities..."}
    ]
)

Algumas coisas importantes sobre níveis de esforço, baseadas na documentação oficial de esforço da Anthropic:

• high é o padrão da API. Use para raciocínios complexos, análises detalhadas ou problemas de codificação difíceis onde a qualidade é prioridade.
• xhigh é o novo nível — recomendado para tarefas de codificação e agentivas. O Claude Code aumentou seu padrão para xhigh em todos os planos.
• max oferece o raciocínio mais profundo sem limite de tokens. Aplica-se apenas à sessão atual (a menos que definido via variável de ambiente) e não persiste.
• low e medium trocam precisão por velocidade e custo. Úteis para classificação ou roteamento em grande volume onde diferenças marginais de qualidade não justificam o gasto.

Um detalhe que revisei duas vezes: ​Opus 4.7 respeita níveis de esforço de forma mais rigorosa que o Opus 4.6​, especialmente em low e medium. Se você observar raciocínio superficial em uma tarefa complexa, a ação correta é aumentar o esforço — não adicionar scaffolding de prompt ao redor. Os documentos são explícitos sobre isso.

Quando estiver operando em xhigh ou max, defina ​max_tokens​​ para pelo menos 64k para dar ao modelo espaço para pensar e agir através de subagentes e chamadas de ferramentas. Começar em 64k e ajustar a partir daí é a recomendação da própria Anthropic.

Recursos Que Importam para Agentes de Longa Duração

Visão em Alta Resolução, Esforço Máximo e Fluxos de Trabalho com Ferramentas

A atualização de visão é o ganho de capacidade mais concreto para desenvolvedores de agentes. Como documentado na análise de benchmark do Vellum AI sobre o Opus 4.7, o OSWorld-Verified (uso de computador) subiu de 72,7% no Opus 4.6 para 78,0% — um ganho de 5 pontos que, combinado com a atualização de resolução, altera de forma significativa a economia da automação de interface.

O Opus 4.7 é ​o primeiro modelo Claude com suporte a imagens de alta resolução​: a resolução máxima aumentou de 1.568 pixels (~1,15MP) para 2.576 pixels (~3,75MP) no lado longo. Isso é mais do que o triplo do orçamento de pixels. Para agentes de uso de computador que leem interfaces densas, fluxos de trabalho baseados em capturas de tela ou pipelines de compreensão de documentos, essa é uma mudança significativa. De forma crítica, as coordenadas agora mapeiam 1:1 com os pixels reais da imagem — a matemática de fator de escala que antes era necessária para extrair coordenadas desapareceu.

Visão em uma solicitação:

message = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {"type": "url", "url": "https://example.com/diagram.png"}
                },
                {"type": "text", "text": "List every service shown and the connections between them."}
            ]
        }
    ]
)

Se a resolução extra não for necessária para uma tarefa específica, reduza a escala das imagens antes de enviar — imagens de alta resolução produzem mais tokens, e para cargas de trabalho sensíveis a custos isso se acumula.

Para loops agentivos com uso intenso de ferramentas, aumentar o esforço aumenta a frequência e a profundidade das chamadas de ferramentas. A relação é direta: menor esforço → menos chamadas de ferramentas e cadeias de raciocínio mais rasas; maior esforço → interação com ferramentas mais detalhada. Isso também pode ser ajustado por prompts, mas o parâmetro de esforço é a alavanca mais clara.

Controles de Custo e Latência para Uso em Produção

Orçamentos de tarefas são o novo mecanismo para controlar gastos em loops agentivos longos. Ative-os com o cabeçalho beta:

response = client.beta.messages.create(
    model="claude-opus-4-7",
    max_tokens=128000,
    output_config={
        "effort": "high",
        "task_budget": {"type": "tokens", "total": 128000}
    },
    messages=[
        {"role": "user", "content": "Review the codebase and propose a refactor plan."}
    ],
    betas=["task-budgets-2026-03-13"]
)

O modelo vê a contagem regressiva e a utiliza para priorizar e finalizar de forma elegante. Sem um orçamento de tarefa, o comportamento padrão é "gastar conforme necessário" — em uma tarefa agentiva complexa em xhigh, isso pode significar significativamente mais tokens de saída do que você esperaria de uma solicitação de uma única rodada.

Para cargas de trabalho assíncronas — execuções de avaliação, resumos noturnos, análises em lote — o Batch API oferece um desconto de 50% e elimina a pressão de limite de taxa do tráfego em tempo real. O cache de prompts continua disponível e pode reduzir os custos de entradas repetidas em até 90% para cargas de trabalho com prompts de sistema estáveis ou grandes prefixos estáticos.

Erros de Migração a Evitar

Assumir que Prompts do 4.6 Transferem Sem Alterações

Este é o que continuo vendo surgir.

Opus 4.7 segue as instruções mais literalmente do que o Opus 4.6. Ele não lê mais nas entrelinhas nem generaliza silenciosamente de um caso para outro. Formulações suaves — "tente", "se possível", "aproximadamente" — agora têm mais peso real. Prompts que dependiam da flexibilidade interpretativa do 4.6 podem, às vezes, se comportar de maneira diferente, e nem sempre da forma que você esperaria.

As três mudanças de API incompatíveis exigem atualizações de código, não apenas edições de prompt:

1. Substitua thinking: {type: "enabled", budget_tokens: N} por thinking: {type: "adaptive"}
2. Remova temperature, top_p, top_k das solicitações inteiramente
3. Audite max_tokens — o novo tokenizador mapeia o mesmo texto para até 1,35× mais tokens, portanto, os limites existentes podem cortar respostas que antes cabiam

Sobre o tom: Opus 4.7 é mais direto e opinativo do que o 4.6 — menos emoji, menos frases direcionadas à validação. Se seu produto depende de uma voz específica calibrada para o estilo mais caloroso do 4.6, reavalie seus prompts de estilo em relação à nova linha de base antes de promover para produção.

O anúncio de lançamento do Opus 4.7 da Anthropic linka diretamente para a lista completa de migração, e usuários do Claude Code podem executar /claude-api migrate para automatizar a troca de ID do modelo e as mudanças de parâmetros incompatíveis em todo o código.

Tratando Contexto Longo Como Memória Persistente

Parei aqui quando li isso nos documentos, porque é fácil confundir os dois.

Uma janela de contexto de 1 milhão de tokens não é memória persistente. Isso significa que você pode colocar 1 milhão de tokens em uma única solicitação. Quando essa solicitação termina — quando a sessão fecha, quando o agente falha, quando uma nova conversa começa — esse contexto desaparece. A próxima solicitação começa do zero.

O Opus 4.7 inclui memória baseada em sistema de arquivos aprimorada: o modelo lê e escreve em arquivos de notas ao longo de múltiplas sessões, com comportamento claramente mais confiável para agentes que usam esse padrão. Mas isso é uma ferramenta que você configura. Não acontece automaticamente a partir de uma janela de contexto longa.

A distinção importa para qualquer pessoa que esteja construindo agentes que devem "lembrar" coisas entre execuções. A janela de 1 milhão de tokens ajuda dentro de uma sessão. Memória entre sessões requer arquitetura explícita.

O Que a API Ainda Não Resolve

Reutilização de Capacidade e Histórico de Reparos Validados

Esta é a parte que acho mais difícil de encaixar de forma organizada em um guia de API, mas acredito que vale a pena mencionar.

Quando o Opus 4.7 detecta uma falha lógica durante a fase de planejamento — que os materiais de lançamento descrevem como uma capacidade genuína — esse raciocínio acontece dentro da sessão. O fato de ter detectado a falha, e como a corrigiu, não persiste automaticamente como um padrão reutilizável na próxima execução. Na próxima vez que a mesma classe de problema aparecer, o modelo raciocina do zero.

De acordo com um artigo de pesquisa sobre a confiabilidade de agentes de IA publicado no início de 2026, a maioria dos modelos é avaliada com base na precisão média, e não na consistência entre execuções — o que significa que um modelo pode ter bom desempenho em benchmarks, mas ainda falhar de forma imprevisível na mesma classe de tarefa em momentos diferentes. O Opus 4.7 melhora em relação à linha de base do Opus 4.6. Isso é real. Mas correção dentro da sessão e herança de capacidade entre sessões são problemas diferentes, e a API resolve o primeiro, não o segundo.

Para desenvolvedores que executam agentes em produção, isso significa que o trabalho de engenharia para construir sistemas confiáveis — suportes de avaliação, documentação de reparo, monitoramento — ainda permanece fora do próprio modelo. A API oferece um modelo mais capaz. O que você faz com essa capacidade ao longo do tempo ainda depende da sua arquitetura.

FAQ

P: Qual é o ID correto do modelo para Opus 4.7?

R: claude-opus-4-7. Esta é a identificação estável para chamadas de API no Claude API, Amazon Bedrock, Google Cloud Vertex AI e Microsoft Foundry.

P: O pensamento adaptativo está ativado por padrão?

R: Não. O pensamento adaptativo está desligado por padrão no Opus 4.7. Você deve definir thinking: {"type": "adaptive"} explicitamente para habilitá-lo. Solicitações sem o campo thinking são executadas sem raciocínio.

P: O que acontece se eu enviar ​temperature​​​ ou ​budget_tokens​?

R: Ambos retornam um erro 400 no Opus 4.7. Remova temperature, top_p e top_k de todas as solicitações. Substitua budget_tokens por output_config: {"effort": "..."} e thinking: {"type": "adaptive"}.

P: Quando devo usar xhigh vs high effort?

R: Use xhigh como ponto de partida para tarefas de codificação e agentes — agora é o padrão no Claude Code em todos os planos. Use high para a maioria das tarefas sensíveis à inteligência. Reduza para medium ou low quando latência ou custo forem mais importantes do que profundidade de raciocínio. Se você observar saída superficial em uma tarefa complexa em um nível mais baixo, aumente o esforço em vez de adicionar suporte ao prompt.

P: A janela de contexto de 1M significa que o agente lembra coisas entre sessões?

A: Não. A janela de contexto se aplica dentro de uma única solicitação. Quando uma sessão termina, esse contexto se perde. A memória multi-sessão requer ferramentas explícitas — memória baseada em arquivos, armazenamentos externos ou arquitetura similar.

Postagens Anteriores

• 👉 Se você quer entender por que as atualizações de modelo não reduzem realmente o custo do sistema: Claude Opus 4.7 vs Reliability: Por que modelos melhores não corrigem sistemas de agentes
• 👉 Se você está tentando entender onde o custo real se esconde além da precificação por token: Harness Engineering: A Camada Oculta por Trás do Custo e da Confiabilidade dos Agentes
• 👉 Se você está avaliando quando o Opus realmente vale o prêmio sobre o Sonnet: Claude Managed Agents: Quando Você Realmente Deve Usar Opus vs Sonnet
• 👉 Se você está construindo sistemas de agentes e precisa controlar comportamento + gasto juntos: Agent Superpowers: Restrições de Comportamento como Camada de Controle de Custos
• 👉 Se você está pensando em expandir o uso de agentes além de fluxos de trabalho únicos: Melhores Servidores MCP para Claude Code: Casos Reais de Uso em Produção