APIs de LLM e Engenharia de Contexto

2.1 Provedores e como escolher um modelo

Há três formas de acessar um LLM em produção:

Os critérios de escolha

1. Qualidade na sua tarefa. Rankings públicos ajudam a fazer a primeira lista, mas o que vale é o resultado nos seus casos reais. Esse é o tema do Módulo 3.
2. Custo por tarefa concluída. Não por token: um modelo barato que precisa de três tentativas pode sair mais caro que um caro que acerta de primeira.
3. Latência. O tempo até o primeiro token importa para chat; o tempo total importa para processamento em segundo plano.
4. Janela de contexto e saída máxima. Quanto texto cabe na entrada e quanto o modelo pode escrever.
5. Recursos da API. Saída estruturada, ferramentas, visão, cache, batch, controle de raciocínio.
6. Dados e conformidade. Retenção de dados, região de processamento, uso para treino, LGPD, contrato.

A família de modelos de um provedor

Os provedores costumam oferecer tamanhos diferentes. Nos labs usamos a família Claude como referência (preços de nov/2026, por milhão de tokens):

2.2 Anatomia de uma requisição

resposta = client.messages.create(
    model="claude-opus-5-5",            # qual modelo
    max_tokens=8000,                    # teto da resposta (inclui raciocínio)
    system="Você é um mentor...",       # quem o modelo é, regras, contexto fixo
    messages=[                          # a conversa até agora
        {"role": "user", "content": "O que é idempotência?"},
        {"role": "assistant", "content": "É quando..."},
        {"role": "user", "content": "Me dá um exemplo em HTTP."},
    ],
    output_config={"effort": "low"},    # quanto raciocinar
)

Os motivos de parada

Toda resposta traz um stop_reason. Seu código deve tratar cada um:

• end_turn: terminou normalmente.
• max_tokens: bateu no limite. A resposta está incompleta.
• tool_use: o modelo quer usar uma ferramenta e espera o resultado.
• refusal: o modelo recusou por política de segurança. Não use o conteúdo.

Histórico: a conversa é uma lista que você mantém

Depois de cada resposta, adicione ao histórico a mensagem do assistente com todos os blocos que vieram (resposta.content), não só o texto. Isso preserva blocos de raciocínio e chamadas de ferramenta que o modelo precisa ver na próxima volta.

Repare que, como o histórico inteiro é reenviado a cada mensagem, o custo de entrada cresce a cada turno. Em conversas longas, isso domina a conta. Por isso existem o cache (aula 2.7) e a compactação de contexto (Módulo 6).

python python/01_chat_terminal.py
# ou
cd typescript && npx tsx 01-chat-terminal.ts

2.3 Prompt engineering e engenharia de contexto

Prompt engineering é escrever bem a instrução. Engenharia de contexto é a disciplina mais ampla de decidir tudo o que entra na janela do modelo: instruções, documentos, histórico, resultados de ferramentas, exemplos. Com modelos de raciocínio, o segundo passou a importar mais que o primeiro: o modelo raramente erra por falta de "truque" no prompt, e sim por falta de informação ou por excesso de ruído.

Os princípios que funcionam

1. Explique como para um colega novo e competente. Ele não conhece seu produto, seus usuários nem suas regras. Diga o objetivo, para quem é o resultado e o que é sucesso.
2. Dê o porquê das regras. "Respostas curtas, porque aparecem numa notificação de celular" funciona melhor que "SEJA BREVE!!!". Com o motivo, o modelo generaliza para casos que você não previu.
3. Separe instruções de dados. Coloque documentos e entradas do usuário entre tags (<email>…</email>). O modelo sabe onde começa e termina cada coisa, e fica mais difícil um texto malicioso se passar por instrução.
4. Documentos longos primeiro, pergunta no fim. Em contextos grandes, a instrução logo depois do material costuma render melhor.
5. Mostre exemplos quando o formato ou o tom for sutil. Dois ou três exemplos variados valem mais que um parágrafo de descrição. Cuidado: o modelo tende a copiar o exemplo de perto.
6. Diga o que fazer, não só o que evitar. "Escreva em parágrafos corridos" é melhor que "não use listas".
7. Permita a incerteza. "Se a informação não estiver no documento, diga que não encontrou" reduz alucinação.
8. Não microgerencie o raciocínio. Com modelos que já raciocinam, receitas do tipo "pense passo a passo assim e assado" podem piorar o resultado. Dê o objetivo e os critérios, ajuste o esforço.

Antes e depois

Resuma esse texto. Seja breve!!! NÃO invente nada.
{texto}

Você resume chamados de suporte para o gerente do turno, que lê os resumos
no celular entre reuniões e decide quais escalar.

<chamado>
{texto}
</chamado>

Escreva um resumo de até 2 frases com: o problema do cliente e o que ele
pede. Se o cliente mencionar prazo, valor em dinheiro ou ameaça de cancelar,
inclua isso, porque é o que define a escalação. Use só o que está no
chamado; se algo estiver ambíguo, diga que está ambíguo.

Engenharia de contexto: menos e melhor

• Cada token compete pela atenção do modelo. Despejar 50 documentos "por garantia" piora a resposta e o custo. Selecione o que é relevante (Módulo 4).
• Resultados de ferramentas também são contexto. Uma ferramenta que devolve 10 mil linhas de JSON polui a janela. Devolva só os campos úteis.
• Histórico envelhece. Em conversas longas, resuma ou descarte partes antigas (Módulo 6).
• O prompt é código. Versione, revise em PR e teste (Módulo 3).

Você é um chef. Responda perguntas de culinária. Seja útil. Não fale de
outros assuntos. Use markdown.

Você é o assistente do app Cozinha Fácil, usado por pessoas que cozinham
em casa, muitas iniciantes, geralmente pelo celular com as mãos ocupadas.

Ajude com receitas, substituição de ingredientes, técnicas e planejamento
de refeições. Prefira ingredientes fáceis de achar em mercados brasileiros.
Quando der uma receita, liste ingredientes com quantidades e depois passos
numerados e curtos, porque o usuário segue lendo enquanto cozinha.

Se a pergunta envolver segurança alimentar (ponto de carne, conservação,
alergias), seja preciso e conservador: um erro aqui pode fazer mal a alguém.

Se pedirem algo fora de culinária, diga gentilmente que você só ajuda com
cozinha e sugira uma pergunta relacionada.

2.4 Saídas estruturadas: dados, não texto

A maior parte das integrações não quer um parágrafo: quer um objeto para salvar no banco, rotear um chamado ou preencher um formulário. Pedir "responda só em JSON" no prompt funciona quase sempre, e "quase sempre" é o pior tipo de bug em produção.

Com saídas estruturadas, você envia um JSON Schema e a API restringe a geração para que a resposta siga esse schema. Os SDKs geram o schema a partir dos tipos que você já usa: Pydantic em Python e Zod em TypeScript.

const Chamado = z.object({
  categoria: z.enum(["cobranca", "bug", "duvida", "cancelamento", "elogio", "outro"]),
  prioridade: z.enum(["baixa", "media", "alta", "critica"])
    .describe("critica = sistema fora do ar ou perda de dinheiro"),
  resumo: z.string().describe("Uma frase, no máximo 20 palavras"),
  pede_reembolso: z.boolean(),
});

const resposta = await client.messages.parse({
  model: "claude-opus-5-5",
  max_tokens: 4000,
  messages: [{ role: "user", content: `<email>${texto}</email>\nExtraia o chamado.` }],
  output_config: { effort: "low", format: zodOutputFormat(Chamado) },
});

const chamado = resposta.parsed_output; // tipado: chamado.prioridade é "baixa" | "media" | ...

Boas práticas de schema

• .describe() / Field(description=…) é prompt. Explique o critério de cada campo, principalmente os subjetivos.
• Use enums para categorias. Texto livre gera "Cobrança", "cobranca", "financeiro"…
• Campos opcionais como null explícito (.nullable(), str | None), para o modelo não inventar valor quando a informação não existe.
• Inclua campos de autoavaliação como confianca ou observacoes. Eles alimentam a revisão humana.
• Valide de novo no seu código. Os SDKs validam o formato com Zod/Pydantic, mas nem toda restrição cabe no schema enviado à API (o SDK pode, por exemplo, passar opções de enum ou limites numéricos para a descrição do campo). E nenhuma restrição de schema garante que o conteúdo está certo: isso é com as suas regras de negócio (projeto do módulo).

python python/02_saida_estruturada.py                          # e-mail irritado
python python/02_saida_estruturada.py dados/email_cliente_2.txt  # elogio + dúvida
# ou
cd typescript && npx tsx 02-saida-estruturada.ts

2.5 Tool calling: o modelo pede, seu código age

Um LLM sozinho não consulta seu banco, não sabe a cotação de hoje e não envia e-mail. Com ferramentas (tools, ou function calling), você descreve funções que ele pode pedir para usar. O ciclo:

O loop se repete até o modelo responder sem pedir ferramenta (stop_reason diferente de tool_use). O modelo nunca executa nada: ele só pede. Quem decide executar, e com quais permissões, é o seu código. Essa é a base de segurança de todo agente.

{
    "name": "calcular_frete",
    "description": "Calcula valor e prazo de frete para um CEP de destino e um peso em kg.",
    "strict": True,   # garante que os argumentos seguem o schema
    "input_schema": {
        "type": "object",
        "properties": {
            "cep": {"type": "string", "description": "CEP de destino, com ou sem hífen"},
            "peso_kg": {"type": "number"},
        },
        "required": ["cep", "peso_kg"],
        "additionalProperties": False,
    },
}

Regras de ouro

• A descrição é um prompt. Diga o que a ferramenta faz, quando usar e o que devolve. Nomes e descrições ruins são a causa nº 1 de ferramenta errada.
• Erros voltam para o modelo como tool_result com is_error: true. Ele pode corrigir o argumento ou explicar o problema ao usuário.
• Vários pedidos na mesma resposta são comuns (chamadas paralelas). Devolva todos os resultados juntos, em uma única mensagem.
• Sempre ponha um teto no loop. Sem limite de rodadas, um modelo confuso pode chamar ferramentas para sempre, e você paga por cada volta.
• Ações com efeito no mundo real (pagar, apagar, enviar) precisam de confirmação humana ou de regras rígidas no seu código. Detalhes nos Módulos 6 e 12.

python python/03_ferramentas.py
python python/03_ferramentas.py "Qual o status do pedido 9999?"
# ou
cd typescript && npx tsx 03-ferramentas.ts

2.6 Streaming: a resposta enquanto ela nasce

Uma resposta de 800 tokens pode levar dezenas de segundos para ficar pronta. Sem streaming, o usuário encara uma tela parada. Com streaming, o texto começa a aparecer em cerca de um segundo. O tempo total é o mesmo; a percepção muda completamente.

const stream = client.messages.stream({ model, max_tokens: 16000, messages });

stream.on("text", (pedaco) => process.stdout.write(pedaco)); // cada pedaço, assim que chega

const final = await stream.finalMessage(); // mensagem completa: usage, stop_reason

Quando usar

• Sempre que uma pessoa estiver esperando a resposta (chat, assistentes, editores).
• Em respostas longas, mesmo sem pessoa esperando: streaming evita que a conexão HTTP estoure o tempo limite.
• Não precisa em jobs de fundo curtos, nem em extração estruturada em que você só usa o objeto final.

Duas métricas para acompanhar

• TTFT (time to first token): o tempo até o primeiro pedaço. Define a sensação de rapidez.
• Tempo total: define quanto tempo a conexão fica aberta e o throughput do sistema.

cd typescript && npx tsx 04-streaming.ts
npx tsx 04-streaming.ts "Escreva um conto de 400 palavras sobre um robô que aprende a cozinhar"

2.7 Cache de prompt, batch e economia de tokens

Cache de prompt

Muitas aplicações reenviam o mesmo início a cada chamada: instruções longas, um manual, o histórico da conversa. Com cache de prompt, o provedor guarda esse prefixo processado por alguns minutos, e as próximas chamadas que começam igual pagam uma fração do preço por ele, além de responderem mais rápido.

SISTEMA = [
    {"type": "text", "text": "Responda usando SOMENTE o manual abaixo."},
    {"type": "text", "text": f"<manual>{manual}</manual>",
     "cache_control": {"type": "ephemeral"}},   # tudo até aqui vai para o cache
]

As regras que fazem o cache funcionar, ou falhar em silêncio:

• É uma comparação de prefixo. Qualquer byte diferente antes do ponto de cache invalida tudo depois dele. Coloque o que é estável primeiro e o que varia (a pergunta) por último.
• Inimigos silenciosos: data e hora no prompt de sistema, IDs de requisição, JSON com chaves em ordem diferente, lista de ferramentas que muda.
• Há um tamanho mínimo (centenas a alguns milhares de tokens, conforme o modelo). Abaixo dele o cache simplesmente não acontece, sem erro.
• Confirme sempre pelo usage: cache_creation_input_tokens (gravou) e cache_read_input_tokens (leu). Se a leitura fica em zero, algo está mudando o prefixo.

Batch: metade do preço para o que pode esperar

A API de lotes recebe milhares de requisições de uma vez, processa em segundo plano (em geral em menos de uma hora, no máximo em 24 h) e cobra 50% menos. É ideal para classificar o acumulado do dia, gerar descrições de catálogo, enriquecer dados e rodar evals.

• Cada requisição leva um custom_id. Os resultados chegam fora de ordem: case sempre pelo ID.
• Algumas requisições podem falhar e outras não. Trate cada resultado individualmente.

Outras formas de economizar tokens

• Modelo certo por tarefa (aula 2.1): de longe a maior alavanca.
• Esforço mínimo que mantém a qualidade. Tokens de raciocínio são cobrados como saída.
• Peça saídas enxutas. Saída custa 5× a entrada. Um JSON com campos curtos é mais barato que um parágrafo.
• Corte o contexto inútil: HTML com marcação, logs inteiros, histórico velho.
• Conte antes de enviar documentos grandes com a API de contagem de tokens.

python python/04_cache.py

python python/05_batch.py
python python/05_batch.py msgbatch_...   # para retomar um lote já enviado

2.8 Erros, retries, timeouts e limites de taxa

Uma API de LLM é um serviço remoto como qualquer outro: cai, fica lenta e limita o uso. Trate-a com as mesmas práticas de sistemas distribuídos.

O que o SDK já faz por você

Os SDKs oficiais repetem automaticamente erros de conexão, 408, 409, 429 e 5xx, com espera exponencial (2 tentativas por padrão). Configure, não reimplemente:

const client = new Anthropic({ maxRetries: 3, timeout: 60_000 }); // ms no SDK TypeScript

// por chamada:
await client.messages.create(params, { timeout: 10_000, maxRetries: 0 });

O que continua sendo seu

• Classificar o erro pelos tipos do SDK (RateLimitError, BadRequestError…), nunca comparando o texto da mensagem.
• Idempotência: se a chamada dispara uma ação (enviar e-mail), garanta que uma repetição não a duplique.
• Degradação elegante: o que o usuário vê se a IA estiver fora? Uma mensagem honesta, uma fila para depois, um modelo reserva.
• Limites de taxa no seu lado: controle a concorrência dos seus jobs (filas, semáforos) para não viver no 429.
• Timeouts realistas: com raciocínio ativo, respostas boas podem levar minutos. Use streaming nas chamadas longas.

cd typescript && npx tsx 05-erros-e-limites.ts

2.9 Vários provedores: gateways e abstrações

Cedo ou tarde surge a pergunta: "e se quisermos trocar de provedor?". Há três abordagens, com custos diferentes:

Para a maioria das aplicações, a terceira opção é a mais saudável. Seu código depende de uma interface do seu domínio, não do formato de nenhum provedor:

// o resto do sistema só conhece isto:
interface ExtratorDeRecibos {
  extrair(texto: string): Promise<{ recibo: Recibo; custoUsd: number }>;
}

// e cada provedor vira um adaptador, usando os recursos nativos do seu SDK:
class ExtratorAnthropic implements ExtratorDeRecibos { /* messages.parse + zod */ }
class ExtratorModeloLocal implements ExtratorDeRecibos { /* servidor local */ }

Projeto do módulo: extrator de recibos

Um sistema que lê notas e cupons fiscais em texto (como os que saem de um OCR), devolve dados estruturados, valida com regras de negócio, pede ao modelo que revise quando a validação falha e gera um relatório de qualidade e custo. É o padrão de quase toda automação séria com LLM: extrair → validar → corrigir → revisar humano quando necessário.

Este projeto existe nas duas trilhas. O objetivo, o critério de pronto e os recibos são os mesmos; muda quem escreve o código. Na trilha com código, você escreve. Na trilha com agentes, o Claude escreve e você decide, confere e aprende como o problema se resolve (veja o P3).

Os recibos de exemplo

• 01-padaria.txt e 02-farmacia.txt: limpos; o segundo tem desconto.
• 03-mercado-foto.txt: simula OCR de foto, com letras trocadas por números (OOO1, 1O/2026), e uma soma que não fecha na própria nota.
• 04-restaurante.txt: tem taxa de serviço (acréscimo).

Por que o mercado importa: padaria, farmácia e restaurante devem passar na validação. No recibo do mercado, a regra de soma deve disparar; o modelo recebe o problema, relê a nota e, seguindo as instruções, mantém os valores impressos com confianca: "baixa", em vez de "ajeitar" os números para a conta fechar. É exatamente o comportamento que você quer num sistema contábil: o caso vai para revisão humana.

cd projeto
npm install
npm test                      # testes das regras de validação e custo (não chamam a API)
npm run extrair               # processa recibos/*.txt
npm run extrair -- --modelo claude-haiku-5-5

/autonomo:novo-projeto extrator-de-recibos

Copie os 4 recibos de curso-ia/codigo/modulo-02/projeto/recibos do repositório
MarciodeCampos/o-arco para a pasta recibos/ deste projeto.

Quero: um programa que leia cada recibo da pasta recibos/ e devolva emitente com CNPJ,
data, itens (quantidade, preço unitário, total), desconto, acréscimo, total e pagamento.
Para: conferir recibos sem digitar nada à mão.
Pronto quando:
  1. Padaria, farmácia e restaurante passam nas regras: CNPJ válido, data válida e não
     futura, quantidade × preço de cada item, e itens − desconto + acréscimo = total.
  2. O recibo do mercado, cuja soma não fecha na própria nota, sai com os valores
     impressos e confiança baixa, para revisão humana. Não ajuste os números.
  3. As regras de conferência têm testes automáticos que rodam sem chamar a API.
  4. Você me mostra o custo por recibo.
Não pode: ler ou mostrar a chave de API (ela já está em ANTHROPIC_API_KEY).
Antes de cada etapa importante, me mostre o que propõe, por quê, as alternativas e o
risco, e espere minha autorização. Narre cada decisão; eu estou aprendendo como se resolve.

recibo               regras   confiança   observações
01-padaria           ok       alta
02-farmacia          ok       alta        desconto de 10% aplicado
03-mercado-foto      ok       alta        total corrigido de 89,11 para 82,11 para fechar a soma
04-restaurante       ok       alta        taxa de serviço de 10%

4 de 4 aprovados · custo médio US$ 0,0031 por recibo

Recursos para aprofundar

• Documentação da API da Anthropic · guias de prompts, saídas estruturadas, ferramentas, cache e batch
• Effective context engineering for AI agents · artigo sobre engenharia de contexto
• Building effective agents · quando usar chamada única, workflow ou agente (ponte para o Módulo 6)
• Zod e Pydantic · as bibliotecas de schema usadas nos labs
• OpenRouter e LiteLLM · para experimentar vários provedores