Como é a estrutura de custos das chamadas de API em várias rodadas por agentes?

Nota do autor: Partindo de uma tarefa de desenvolvimento de software executada por um agente em 30 minutos, este artigo detalha os custos de entradas comuns, gravações e leituras de cache, saídas e interações com ferramentas ao longo de várias chamadas do agente. Também compara a cobrança pelo uso de cache de três provedores e mostra, com um exemplo de 12 chamadas, em que condições o cache realmente reduz os custos.

Em 9 de novembro de 2026, o Google Cloud lançou dois sistemas TPU de oitava geração: TPU 8tx e TPU 8i Max. A empresa também abriu o código do TPU Sync, usado para transferir KV Cache. A “parede da memória na era dos agentes” voltou a ser assunto, e muitos desenvolvedores naturalmente se perguntam: com o KV Cache subjacente cada vez mais rápido, a conta da API do meu agente também vai ficar mais barata?

Principal benefício: ao terminar de ler, você terá uma fórmula completa para calcular os custos de um agente, uma comparação da cobrança pelo uso de cache de três provedores e uma lista de otimizações de custos que já pode colocar em prática.

Custos de API em chamadas de várias etapas de um Agent: visão geral

Como é uma tarefa de 30 minutos com várias chamadas de um Agent

Imagine que um Agent de desenvolvimento de software recebe uma solicitação: corrigir falhas nos testes de um módulo. Primeiro, ele lê a estrutura do projeto e o código-fonte relevante, elabora um plano de alterações, usa ferramentas para editar arquivos e executar testes, aguarda os resultados e, em seguida, continua o raciocínio com base nos erros. Em 30 minutos, esse ciclo de “raciocínio — ferramenta — espera — raciocínio” pode se repetir mais de dez vezes.

O problema é que, essencialmente, as APIs de Modelos de Linguagem Grandes não têm estado. Em cada solicitação, o Agent precisa enviar novamente ao modelo o comando do sistema, as definições das ferramentas, o contexto do projeto e as conversas e saídas das ferramentas anteriores. A 12ª solicitação costuma incluir quase todo o histórico das 11 rodadas anteriores. É daí que vem a “recomputação do contexto”.

Quais são os componentes do custo de chamadas de API em múltiplas etapas de um Agent

Ao dividir uma tarefa de Agent, vemos que o custo inclui pelo menos cinco componentes. Os quatro primeiros são custos de tokens do modelo; o quinto ocorre fora do modelo, mas muitas vezes passa despercebido.

Com base nisso, podemos escrever a fórmula do custo de uma tarefa:

Custo total da tarefa = Σ (entrada comum × tarifa de entrada + gravação no cache × tarifa de gravação + leitura do cache × tarifa de leitura + saída × tarifa de saída) + custos de ferramentas e execução externa

O símbolo Σ na fórmula representa a soma de cada chamada ao modelo feita durante a tarefa. Isso significa que o número de chamadas funciona como um multiplicador: quanto mais interações com ferramentas, mais chamadas ao modelo e mais vezes o prefixo fixo é cobrado. As chamadas de ferramentas não geram apenas o custo dos próprios serviços: elas também dividem uma etapa de raciocínio em várias chamadas, cada uma delas precisando incluir o contexto novamente.

Diferenças entre KV Cache, Prompt Cache e compressão de contexto em chamadas Agent com várias etapas

Ao falar sobre custos de Agent, é fácil confundir esses três conceitos. Eles atuam em camadas diferentes e têm impactos bem distintos na fatura.

Vale observar que a documentação oficial da OpenAI explica que o Prompt Cache armazena, na prática, tensores KV, e não o texto original dos Tokens. Por isso, o Prompt Caching pode ser entendido como a disponibilização e a tarifação do reaproveitamento de estados KV da camada inferior. Os dois conceitos têm relação, mas, para o usuário, o que fica visível são apenas as regras de cobrança.

Já a compressão de contexto é outra coisa. Ela muda o que as próximas solicitações “carregam”, e não a forma como o conteúdo é reutilizado. Quanto mais agressiva a compressão, menos Tokens são usados, mas maior é o risco de o Agent esquecer detalhes importantes.

Por que as otimizações de baixo nível em chamadas Agent com várias etapas não reduzem necessariamente a fatura

O TPU 8i Max anunciado pelo Google dobra a largura de banda da HBM e a SRAM no chip. Em testes internos na plataforma Ironwood, o TPU Sync reduziu em mais de 90% a latência de transferência do KV Cache. Já o Agent Compute Engine pausa as sessões quando o Agent fica ocioso e transfere a memória de trabalho para fora do chip. Essas otimizações melhoram o aproveitamento dos recursos do provedor e a latência de inferência — como o TTFT —, o que pode resultar em respostas mais rápidas para o usuário.

Mas o preço da API é definido comercialmente pelo provedor, e a fatura do usuário continua sendo calculada por Token. O aumento da eficiência do hardware pode influenciar os preços no longo prazo, mas essa redução não é automática nem proporcional. Além disso, em 2026-11-10, o TPU 8tx e o TPU 8i Max ainda estavam marcados como Coming soon, sem preços divulgados. Para quem desenvolve, o que dá para controlar imediatamente é a estrutura dos próprios Tokens, não o hardware do provedor.

Custo de chamadas de API em várias etapas por agentes: comparação da cobrança por cache entre três provedores

Os três principais provedores oferecem mecanismos de cache, mas diferem bastante na forma de acionamento, no TTL e nos critérios de cobrança. A tabela abaixo foi compilada com base na documentação oficial de cada provedor. Consulte as informações do modelo e da interface correspondentes para confirmar os detalhes.

Como exemplo, considere os preços oficiais do Claude Sonnet 5.5: a entrada normal custa US$ 2,00 por milhão de tokens; a gravação em cache por 5 minutos custa US$ 2,50; por 1 hora, US$ 4,00; e a leitura do cache, US$ 0,10. A leitura do cache custa apenas 5% do valor da entrada normal, o que explica a grande redução de custos quando há prefixos repetidos.

Vale lembrar que a OpenAI informa claramente que o cache não é garantido em todas as chamadas. Além disso, o cache explícito do Gemini não oferece “armazenamento gratuito”: o tempo de armazenamento também é cobrado. O cache é um desconto condicionado, não uma redução de preço aplicada automaticamente.

🎯 Recomendação técnica: os recursos de cache, as regras de cobrança e os campos de resposta variam entre os modelos de diferentes provedores. Um gateway unificado não garante automaticamente os mesmos descontos de cache para todos os modelos. Recomendamos testar os modelos candidatos com o mesmo código compatível com OpenAI, usando a APIYI apiyi.com, e conferir os campos usage retornados e a fatura.

Cálculo real do custo de cache em várias chamadas de um Agent: exemplo com 12 chamadas

Vamos retomar a tarefa de desenvolvimento de 30 minutos apresentada antes e usar os preços oficiais do Claude Sonnet 5.5 para montar um exemplo. As premissas são:

• A tarefa faz 12 chamadas ao modelo, cada uma com 22,000 tokens de entrada;
• Desses, 20,000 tokens são compostos por comando do sistema, definições de ferramentas e contexto do projeto repetidos;
• Cada chamada acrescenta 2,000 tokens;
• É usado um cache de 1 hora, e as solicitações seguintes reutilizam o conteúdo com sucesso.

Sem cache: 12 × 22,000 × $2 / 1,000,000 = $0.528.

Com cache de 1 hora: a gravação inicial de 20,000 tokens custa $0.080; os 2,000 tokens da entrada comum inicial custam $0.004; as 11 leituras seguintes do cache custam $0.022; e as 11 entradas adicionais custam $0.044. O total é $0.150, uma economia de aproximadamente 71.6% nas entradas.

Este exemplo considera apenas os tokens de entrada e não inclui tokens de saída, chamadas de ferramentas nem custos de serviços externos. O histórico de um Agent real também cresce a cada rodada, mas a conclusão continua a mesma: o contexto repetido é o custo que mais tende a se multiplicar nas chamadas sucessivas de um Agent.

Como a expiração do cache, as mudanças no prefixo e o TTL afetam o custo de um Agent

O exemplo acima representa uma situação ideal. A seguir, usamos os mesmos preços para analisar três desvios comuns. (Os cenários ilustrativos abaixo foram calculados neste artigo com base nos preços oficiais.)

Alguns pontos que podem ajudar diretamente na tomada de decisão:

• O TTL precisa cobrir o tempo de espera pelas ferramentas: gravar no cache de 5 minutos custa menos, mas, se a execução de um teste ou a confirmação manual ultrapassar esse tempo, o cache expira e precisa ser gravado novamente. A economia diminui bastante.
• Manter o prefixo estável é mais importante do que o TTL: colocar um timestamp ou ID aleatório no início do comando impede que as chamadas seguintes encontrem o cache. Nos modos em que há cobrança adicional pela gravação, o cache pode acabar deixando a conta mais cara.
• Um TTL mais longo não é necessariamente melhor: a gravação com TTL de 1 hora custa 1.6 vez o valor da gravação com TTL de 5 minutos. Só vale a pena quando o intervalo entre chamadas pode realmente passar de 5 minutos.

Como reduzir os custos de API em chamadas de Agent com várias rodadas

Exemplo mínimo: registrar os acertos de cache em cada chamada

O primeiro passo para otimizar os custos é “enxergá-los”. O código abaixo faz uma solicitação pela interface compatível com a OpenAI e imprime os campos relacionados ao cache em usage:

import openai

client = openai.OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1"  # Interface compatível com a OpenAI da APIYI
)

resp = client.chat.completions.create(
    model="your-model-name",  # Substitua pelo modelo que deseja testar
    messages=[
        {"role": "system", "content": "固定的系统提示词与工具说明……"},
        {"role": "user", "content": "本轮新增的任务内容"}
    ]
)
usage = resp.usage
details = getattr(usage, "prompt_tokens_details", None)
print("输入:", usage.prompt_tokens, "输出:", usage.completion_tokens,
      "缓存命中:", getattr(details, "cached_tokens", None))

import openai
from dataclasses import dataclass, field

client = openai.OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1"
)

# Prefixo fixo: instruções do sistema, definições de ferramentas e contexto compartilhado do projeto. Mantenha-o no início e exatamente igual, byte a byte.
STABLE_PREFIX = [
    {"role": "system", "content": "你是代码修复 Agent。工具定义与项目规范如下……"},
]

@dataclass
class TaskCost:
    # Preços unitários: dólares por milhão de tokens. Preencha com os preços oficiais do modelo usado.
    input_price: float
    cache_read_price: float
    output_price: float
    records: list = field(default_factory=list)

    def add(self, usage):
        details = getattr(usage, "prompt_tokens_details", None)
        cached = getattr(details, "cached_tokens", 0) or 0
        uncached = usage.prompt_tokens - cached
        cost = (uncached * self.input_price
                + cached * self.cache_read_price
                + usage.completion_tokens * self.output_price) / 1_000_000
        self.records.append({"cached": cached, "uncached": uncached,
                             "output": usage.completion_tokens, "cost": cost})

    def summary(self):
        total_in = sum(r["cached"] + r["uncached"] for r in self.records)
        hit = sum(r["cached"] for r in self.records) / max(total_in, 1)
        return {"calls": len(self.records), "cache_hit_rate": round(hit, 3),
                "total_cost": round(sum(r["cost"] for r in self.records), 4)}

def run_turn(history, new_msg, tracker, model="your-model-name"):
    # Apenas acrescente a nova mensagem, sem reorganizar o histórico; deixe informações dinâmicas, como registros de data e hora, no final.
    history.append({"role": "user", "content": new_msg})
    resp = client.chat.completions.create(
        model=model, messages=STABLE_PREFIX + history)
    tracker.add(resp.usage)
    history.append({"role": "assistant",
                    "content": resp.choices[0].message.content})
    return resp

tracker = TaskCost(input_price=2.0, cache_read_price=0.1, output_price=0.0)
history = []
run_turn(history, "测试 test_auth 失败，报错如下……", tracker)
print(tracker.summary())

Atenção: a estimativa acima considera apenas o desconto de leitura. Se o modelo usado cobrar separadamente pela gravação no cache, inclua esse custo com base nos campos retornados. Os nomes e significados dos campos de usage podem variar entre modelos; use os dados retornados na prática como referência.

🚀 Comece rápido: recomendamos testar primeiro o script de rastreamento acima na APIYI, em apiyi.com, usando a cota gratuita de testes. Assim, você obtém a taxa de acerto do cache e o custo por tarefa do mesmo trabalho em diferentes modelos e pode decidir qual modelo e qual TTL usar em produção.

Cinco ações para otimizar os custos de chamadas múltiplas de um agente

1. Mantenha estável o prefixo do comando: coloque as instruções do sistema, as definições de ferramentas e os materiais de referência compartilhados no início. Deixe os carimbos de data e hora e as informações dinâmicas do usuário para o final. Além disso, evite alterar sem necessidade a ordem e os campos das definições das ferramentas.
2. Escolha o TTL adequado: use um TTL curto em tarefas com chamadas frequentes e intervalos pequenos. Para agentes com longos períodos de teste, compilação ou aprovação humana, avalie se a sobretaxa de gravação de um TTL mais longo pode ser compensada pelas regravações evitadas.
3. Controle o contexto do histórico: apenas acrescente conteúdo, sem reordená-lo, para não invalidar o prefixo em cache. Resuma as saídas extensas das ferramentas e preserve as conclusões principais, o estado da tarefa e as evidências necessárias.
4. Reduza chamadas desnecessárias ao modelo: agrupe em uma única chamada as ferramentas que podem ser executadas em lote. Deixe as etapas determinísticas a cargo do código, em vez de pedir ao modelo que as avalie, reduzindo assim o número de interações desde o início.
5. Monitore métricas reais: registre por tarefa os tokens de entrada comuns, as gravações e leituras em cache, os tokens de saída, a taxa de acerto do cache, o TTFT e o custo total. Avalie o custo por tarefa, não por solicitação individual.

Análise do impacto das chamadas múltiplas de agentes nos custos de API

Impacto para desenvolvedores

• O modelo de custos precisa passar de “por solicitação” para “por tarefa”: o custo de um agente depende de toda a cadeia de chamadas. Considerar apenas o preço unitário pode levar a uma grande subestimativa da fatura real.
• A engenharia de comandos também precisa considerar a estrutura de cobrança: a estabilidade do prefixo determina diretamente se o cache pode ser aproveitado. Por isso, projetar a estrutura dos comandos passa a fazer parte da engenharia de custos.
• A escolha entre vários modelos exige testes práticos: os descontos de cache, o TTL e as sobretaxas de gravação variam de um modelo para outro. O custo da mesma tarefa pode mudar bastante ao trocar de modelo.

Impacto para o setor

• A concorrência em infraestrutura se concentra nas cargas de trabalho de agentes: o foco do Google em largura de banda de memória, transferência de KV Cache e pausa e retomada de agentes mostra que interações múltiplas e contextos longos já se tornaram formatos de carga de trabalho predominantes.
• Os benefícios para os usuários aparecem primeiro na latência: as otimizações de baixo nível melhoram primeiro o TTFT e a taxa de transferência. Uma possível redução no preço dos tokens depende da estratégia de preços do provedor; por isso, desenvolvedores não devem incluí-la antecipadamente no orçamento.

Perguntas frequentes

Principais pontos sobre os custos de APIs em chamadas em várias etapas de agentes

• A unidade de custo é a tarefa: a conta do agente soma toda a cadeia de chamadas, não apenas uma solicitação.
• O contexto repetido é o principal fator de custo: no exemplo com 12 chamadas, o cache de 1 hora reduz os custos de entrada em cerca de 71,6%.
• O cache oferece descontos condicionais: se o prefixo for instável ou o TTL for curto demais, a economia diminui e os custos podem até aumentar.
• Cada provedor tem critérios de cobrança diferentes: confirme as taxas de gravação, os descontos de leitura e os custos de armazenamento para cada modelo.
• Otimização de hardware não significa redução na conta: otimizações de KV em baixo nível melhoram primeiro a latência; o preço depende das tarifas do provedor.
• Meça antes de otimizar: use a interface unificada da APIYI, em apiyi.com, para medir na prática a taxa de acertos do cache e o custo por tarefa de cada modelo.

Resumo

O custo de APIs em chamadas de agentes com várias etapas depende de três fatores: o recálculo de contextos repetidos, os acertos do cache e as idas e voltas das ferramentas. Nenhum deles pode ser ignorado:

1. O recálculo de contextos repetidos define a base do custo: quanto mais chamadas, mais conteúdo repetido;
2. Os acertos do cache determinam o desconto aplicado às partes repetidas; a estabilidade do prefixo e o TTL são fundamentais;
3. As idas e voltas das ferramentas geram custos externos e também aumentam o número de chamadas ao modelo.

Os investimentos do Google em KV Cache e na barreira de memória, no nível da infraestrutura, tornam a execução dos agentes mais rápida. Mas o que os desenvolvedores podem controlar desde já é a estrutura dos próprios Tokens. Recomendamos começar por cinco frentes: estabilizar o prefixo, definir um TTL adequado, resumir o histórico, reduzir o número de chamadas e monitorar os custos por tarefa. Depois, use dados reais com a APIYI, em apiyi.com, para verificar o efeito de cada otimização.

📚 Referências

1. Google Cloud Blog – Introducing TPU 8tx and TPU 8i Max: anúncio do lançamento dos novos sistemas TPU de oitava geração
2. Link: cloud.google.com/blog/topics/ai-infrastructure/tpu-8tx-and-tpu-8i-max

3. Saiba mais sobre o gargalo de memória dos agentes e o contexto do KV Cache.

4. Google Cloud Blog – Introducing TPU Sync: biblioteca de código aberto para transferência de KV Cache e pesos

5. Link: cloud.google.com/blog/topics/ai-infrastructure/introducing-tpu-sync-fast-kv-cache-and-weight-transfer-on-tpu

6. Saiba mais sobre as otimizações de transferência de KV Cache em baixo nível e os critérios dos testes.

7. Documentação da API da OpenAI – Prompt Caching: mecanismo de cache e práticas recomendadas

8. Link: platform.openai.com/docs/guides/prompt-caching

9. Saiba mais sobre as regras de cache de prefixo, o tempo de retenção e as recomendações de monitoramento.

10. Documentação da Anthropic – Prompt Caching: TTL do cache e informações de cobrança

11. Link: docs.anthropic.com/en/docs/build-with-claude/prompt-caching

12. Saiba mais sobre os preços de gravação e leitura do cache de 5 minutos e de 1 hora.

13. Google AI for Developers – Context Caching: cache implícito e explícito do Gemini

14. Link: ai.google.dev/gemini-api/docs/caching
15. Saiba mais sobre o TTL do cache explícito e as taxas de armazenamento.

Autor: equipe técnica da APIYI
Contato técnico: acesse a página inicial da APIYI em apiyi.com para falar conosco. Para mais informações sobre integração, consulte a central de documentação em docs.apiyi.com.

Artigos relacionados

• Veja o consumo de tokens do Codex em cada rodada nos logs de chamadas da APIYI: calcule o custo de conversas longas em 5 passos: Se o uso da janela de contexto não aparece no campo de entrada do Codex, acesse /status; este artigo mostra como calcular, em 5 passos, os tokens e o custo por rodada usando os logs de invocação da APIYI e traz uma tabela para decidir entre compactar ou iniciar uma nova conversa.
• Claude taxa de acerto do cache caiu para 0? 3 passos com diagnostics para descobrir qual parte mudou: Se a taxa de acerto do cache de comandos do Claude caiu para 0 ou a fatura não baixa, use diagnostics em três passos para achar a bifurcação do prefixo, usage para confirmar o acerto real e explique a autoverificação e os custos no serviço proxy de API do APIYI.
• Quanto custa o GPT-6.1 Terra? Preços oficiais e cobrança da API em detalhes: 4 itens de cobrança + 3 exemplos de cálculo: Análise dos preços oficiais do GPT-6.1 Terra: cobrança por entrada, saída, leitura e gravação em cache, faixa de contexto longo de 272K, 50% de desconto no Batch/Flex e preço dobrado no Fast, com o custo por milhão de tokens calculado em 3 cenários reais.
• Após a precificação de pico e fora de pico da API DeepSeek e a cobrança de ferramentas: 5 passos para recalcular o custo de chamadas do aplicativo: Depois que a API DeepSeek introduziu preços de pico e fora de pico e cobrança por ferramentas, use 5 etapas para detalhar tokens, períodos, cache e chamadas de ferramentas e recalcular o custo real de invocação do aplicativo.
• OpenAI adiciona Prompt Cache de 12 horas: 5 critérios de decisão para economizar com o cache da API do GPT-6: Explique o impacto do Prompt Cache de 12 horas da OpenAI nos custos da API do GPT-6, usando a fórmula de retorno e 5 critérios para indicar em quais cenários ativar o cache economiza dinheiro e em quais os ganhos são limitados.
• Como fazer a compressão automática do contexto do agente: 3 momentos de acionamento e uma estratégia de resumo em 5 etapas: Explicação sistemática dos 3 momentos que acionam a compactação automática do contexto de agentes, das estratégias de retenção de informações em resumos e de código executável para controlar o consumo de tokens em conversas longas sem perder informações essenciais da tarefa.