Claude Opus 5.5 Executa Tarefas de 18 Horas: Como Projetar APIs para Agentes de Longa Duração

Cada timeout na sua stack pressupõe um cliente que eventualmente desiste. Uma aba do navegador é fechada. Um job de CI atinge seu limite de tempo. Uma pessoa vai embora. Os padrões que você herdou do seu load balancer, do seu gateway e da sua biblioteca HTTP foram calibrados para um chamador cuja paciência é medida em segundos.

Experimente o Apidog hoje

A Anthropic afirma que o Claude Opus 5.5 permanece na tarefa por 18 horas ou mais.

Isso não é uma afirmação sobre uma única requisição HTTP muito longa. É uma afirmação sobre coerência: o modelo trabalha um único objetivo ao longo de uma sessão muito mais longa do que qualquer coisa que sua API já tenha servido. Quando uma dessas sessões aponta para os seus endpoints, ela sobrevive aos seus tokens de acesso, à sua janela de idempotência, ao seu ciclo de deploy e à maior parte dos seus orçamentos de retry. E, diferentemente de um humano, ela não vai perceber que deveria parar.

Este é um problema de design de API, não um problema de modelo. Eis o que quebra, e o que mudar.

O que a Anthropic realmente publicou

Os números do fornecedor para o novo modelo, para que possamos argumentar a partir da mesma planilha:

Propriedade	Claude Opus 5.5
ID do modelo na API	claude-opus-5-5
Entrada / saída	$4 / $20 por milhão de tokens
Leitura de entrada em cache	$0,20 por milhão (escrita de cache $5)
Janela de contexto	1M
Saída máxima	128k
Modo rápido	$8 / $40 por milhão
Custo de execução vs Opus 5	40% menos
Velocidade de saída vs Opus 5	30% mais rápida
Duração sustentada na tarefa	18+ horas
Disponibilidade	Claude Platform, AWS, GCP, Azure

Benchmarks do mesmo anúncio: Terminal-Bench 4.0 66,4%, OSWorld 2.0 81,8%, AutomationBench 40,0%, FrontierCode v1.1 54,4%, CursorBench 4.0 57,8%, Humanity's Last Exam 67,7% com ferramentas, Chartography 89,0%, GDPval-AA v2.1 com 1846 Elo, e 85% menos tentativas bem-sucedidas de contornar limites.

O número de 18 horas é o que recai sobre a sua infraestrutura. Pontuações de benchmark mudam qual modelo você escolhe. Duração sustentada muda o que a sua API precisa suportar.

Seis pressupostos que deixam de valer

Pressuposto	Por que costumava valer	O que um agente de 18 horas faz com ele
Uma chamada termina ou falha dentro de um timeout	Os chamadores eram interativos	O trabalho é mais longo do que qualquer idle timeout que você possa definir com segurança
Repetir é barato porque a janela é curta	As duplicatas chegavam com segundos de diferença	As duplicatas chegam com horas de diferença, depois que sua janela de deduplicação fechou
A credencial do início é válida no final	As sessões eram mais curtas que o TTL do token	Os tokens rotacionam duas ou três vezes dentro de uma única tarefa
Um stream é uma conexão	Os streams duravam uma resposta	A conexão vai cair, e o trabalho não caiu
O cliente lembra o que estava fazendo	O estado vivia em um único processo	O agente compacta o contexto, reinicia e precisa que você o lembre
O cliente consegue perceber que está progredindo	Um humano observava um spinner	Sem progresso, o agente ou reinicia o job ou espera para sempre

Cada um tem uma correção entediante, bem compreendida e geralmente ignorada porque nada forçava a questão. Algo está forçando a questão agora.

Retorne handles, não trabalho

A mudança de maior valor: qualquer operação que possa exceder alguns segundos retorna um recurso de job imediatamente, em vez de manter a conexão.

POST /v1/reports HTTP/1.1
Host: api.example.com
Idempotency-Key: 01J9Z4KCQ7M3XN2YB8V6H0
Content-Type: application/json

{"dataset": "orders_2026_q3", "format": "parquet"}

HTTP/1.1 202 Accepted
Location: /v1/jobs/job_01J9Z4KD
Retry-After: 5
Content-Type: application/json

{
  "id": "job_01J9Z4KD",
  "status": "queued",
  "created_at": "2026-09-23T04:12:09Z",
  "api_version": "2026-08-01"
}

Em seguida, o recurso de status carrega tudo o que o agente precisa para decidir o que fazer a seguir:

{
  "id": "job_01J9Z4KD",
  "status": "running",
  "progress": { "completed": 41200, "total": 180000, "unit": "rows" },
  "started_at": "2026-09-23T04:12:11Z",
  "updated_at": "2026-09-23T05:47:02Z",
  "expires_at": "2026-09-24T04:12:09Z",
  "retry_after_seconds": 15,
  "result_url": null,
  "error": null
}

Quatro campos fazem o trabalho de verdade. progress com uma unit explícita permite que o modelo raciocine sobre se esperar é racional, em vez de adivinhar a partir do tempo decorrido. retry_after_seconds coloca a cadência de polling sob controle do servidor, o que importa quando o chamador não tem instinto para educação. expires_at informa ao agente por quanto tempo o handle é válido, para que ele possa fazer checkpoint antes de perdê-lo. api_version fixa o job ao contrato sob o qual ele foi criado, a única coisa entre o seu deploy das 15h e uma execução que começou ao amanhecer.

Webhooks são o melhor sinal de conclusão quando você pode oferecê-los, e o polling é o fallback quando o agente não tem um endereço chamável. Nosso walkthrough de polling versus webhooks para chamadas de agente de longa duração cobre o tradeoff. O que muda em um horizonte de 18 horas é que você precisa dos dois, porque um webhook entregue na terceira hora a um agente que desde então compactou seu contexto alcança um chamador que não lembra mais de ter pedido.

Faça a idempotência sobreviver à tarefa

A maioria das implementações de idempotência armazena a chave por um dia ou menos, e isso sempre foi suficiente. Um agente que repete uma chamada de provisionamento falha no final de uma execução longa cai fora da janela de deduplicação original, e nesse momento sua API alegremente faz o trabalho duas vezes.

Três mudanças custam muito pouco:

1. Publique a janela. Retorne a expiração na resposta para que o chamador possa raciocinar sobre ela, em vez de documentá-la uma vez e torcer.
2. Diga quando você reproduziu. Um cabeçalho Idempotency-Replayed: true transforma um no-op silencioso em algo sobre o qual o agente pode agir.
3. Rejeite incompatibilidades em alto e bom som. Mesma chave, corpo diferente significa que o chamador perdeu o rastro do próprio estado. Retorne 409 com a impressão digital da requisição original em vez de servir um resultado obsoleto.

HTTP/1.1 200 OK
Idempotency-Replayed: true
Idempotency-Expires: 2026-09-24T04:12:09Z

Onde a operação é genuinamente perigosa, prefira uma chave natural fornecida pelo cliente a uma opaca. Um transfer_id derivado do fato de negócio sobrevive à compactação de memória de um agente de uma forma que um UUID aleatório que ele gerou onze horas atrás não sobrevive. Nosso guia sobre idempotência em agentes traz os modos de falha.

Presuma que a credencial expira no meio da tarefa

Uma execução de 18 horas sobrevive a quase todo token de acesso de curta duração. Essa é a postura de segurança correta, mas apenas se sua API tornar a distinção legível.

Retorne 401 com um desafio WWW-Authenticate: Bearer [REDACTED]="invalid_token" quando o token expirou, e reserve 403 para um principal que não tem permissão. Os agentes tratam esses dois de forma muito diferente: um significa renovar e continuar, o outro significa parar e reportar. Colapsá-los em uma falha genérica é como você consegue um agente que queima quatro horas repetindo algo que nunca terá permissão de fazer.

Vincule jobs ao principal, não à instância do token. Um job iniciado sob um token que desde então rotacionou deve permanecer legível pela mesma identidade, ou cada renovação de credencial deixa trabalho em andamento órfão.

Trate um stream como retomável, não como uma conexão

Streams longos caem. Presuma isso, e projete a reconexão em vez da conexão.

Para server-sent events, isso significa dar a cada evento um id monotônico, honrar o cabeçalho de requisição Last-Event-ID na reconexão, e emitir um comentário de keepalive em um intervalo menor que o idle timeout mais restritivo entre você e o cliente. Nomeie as chaves de configuração na sua própria documentação, porque o leitor precisa ir lá alterá-las: idle_timeout.timeout_seconds em um load balancer da AWS, proxy_read_timeout no nginx, timeout em um serviço do Cloud Run. O ponto não é um valor específico. É que o valor existe, é menor que o trabalho, e ninguém olhou para ele desde que o serviço foi criado. Nosso guia de streaming SSE cobre o formato de transmissão; a parte específica de agentes é a retomada.

Cabeçalhos de rate limit importam mais do que o normal também. RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset permitem que um modelo regule seu próprio ritmo ao longo de uma execução longa, e um Retry-After em cada 429 elimina as adivinhações. Um agente que recebe um número o respeita. Um agente que não recebe nada inventa um backoff, e a invenção dele não será melhor que a sua.

O lado do custo é uma decisão de design

Olhe novamente para a linha de preços. A entrada custa $4 por milhão de tokens e uma leitura em cache custa $0,20, uma diferença de vinte vezes na parte do payload que um agente reenvia com mais frequência, e em uma janela de contexto de 1M os números absolutos ficam grandes rápido. Escritas de cache a $5 significam que a primeira passada custa um pouco mais que uma leitura simples, então o cache só compensa quando o prefixo é genuinamente reutilizado. Ao longo de dezoito horas, é.

É aqui que a superfície da sua API se torna um insumo de custo na fatura de outra pessoa. Se sua especificação OpenAPI, suas definições de ferramentas ou seu catálogo de erros ficam na frente do contexto de um agente, a estabilidade em bytes é uma funcionalidade. Serialize de forma determinística. Mantenha a ordenação de chaves estável. Versione as definições de ferramentas em vez de editá-las no lugar. Uma reordenação cosmética da sua especificação invalida um prefixo em cache e refatura tudo ao preço cheio de entrada, e o cliente que paga por isso nunca saberá que foi culpa sua.

A escala não é hipotética. A OpenAI divulgou que seu pesquisador mediano gasta mais de $600 por dia com agentes de programação, com o percentil 90 acima de $7.000 por dia. É isso que o trabalho agêntico contínuo custa quando ninguém otimiza para ele, e parte do motivo pelo qual três lançamentos de modelos em dois dias todos lideraram com custo por tarefa em vez de custo por token. A aritmética de quando o cache se paga está na nossa análise de custo de caching do Opus 5.5.

Teste o caminho longo antes que um agente o encontre

Nada disso é verificável clicando em enviar uma vez e lendo um 200. As falhas vivem na nona hora.

No Apidog, modele todo o ciclo de vida como um cenário de teste em vez de uma única requisição: verifique que a chamada de criação retorna 202 com um Location e um Retry-After, faça loop no endpoint de status até um estado terminal, e verifique que progress.completed nunca retrocede. Essa última verificação pega mais bugs reais do que qualquer checagem de código de status, porque progresso não monotônico é o que convence um agente a começar de novo.

Depois quebre isso deliberadamente com um mock server. Sirva um job que permanece running por vinte polls e então falha. Sirva um 429 sem Retry-After e observe o que seu cliente faz. Sirva um 401 no meio do caminho para confirmar que o caminho de renovação funciona enquanto um job está em andamento. O teste de SSE do Apidog mantém uma conexão de streaming aberta e verifica eventos individuais, a única forma prática de checar que a retomada com Last-Event-ID retorna o cursor correto em vez de reproduzir do zero. Conecte o cenário ao CI para que uma futura mudança de timeout faça um teste falhar em vez da execução noturna de um cliente. O Apidog é gratuito para começar, e o cenário que você constrói uma vez cobre todos os endpoints de longa duração que você possui.

A checklist curta

• Operações longas retornam 202 com um handle de job, nunca uma conexão mantida
• Respostas de status carregam progresso, uma unidade, um intervalo de poll escolhido pelo servidor e uma expiração
• Jobs fixam a versão da API com a qual foram criados
• Janelas de idempotência são publicadas, repetições são rotuladas, reutilização de chave com corpo alterado retorna 409
• 401 para tokens expirados é distinguível de 403 para tokens negados
• Jobs pertencem a um principal, não a uma instância de token
• Streams carregam ids de evento, honram Last-Event-ID e enviam keepalives dentro do idle timeout mais curto do caminho
• Todo 429 carrega Retry-After, e cabeçalhos de rate limit estão sempre presentes
• Especificações e definições de ferramentas serializam de forma estável em bytes para que caches do lado do cliente permaneçam quentes

O Opus 5.5 não inventou nenhum desses requisitos. Ele removeu a última desculpa para ignorá-los, porque o cliente que costumava desistir antes de encontrar as rachaduras agora trabalha direto através delas por dezoito horas.