← Voltar ao curso
Nível 3 — Automação e escala · Módulo 3.7 — Claude API e agentes sob medida

3.7.1 · Quando você precisa da API

4 min de vídeo TODOS

Objetivo: ao final, o consultor decide entre app, Claude Code e API a partir de critérios objetivos, e sabe o que se perde ao sair dos apps.

O que você precisa levar desta aula

  1. A pergunta que decide não é "é complexo?", é "quem usa, e por onde?". Se quem usa é o consultor, é app ou Claude Code; se é o cliente por uma tela que a Wayon controla, é API.
  2. Quatro critérios levam à API: produto entregue ao cliente, volume, integração em sistema existente, controle de custo e latência. Um só já basta.
  3. Saindo dos apps você herda a manutenção: interface, sessão, permissões, conectores, histórico e checkpoints deixam de ser da Anthropic e passam a ser código da Wayon.

A tabela de decisão

Situação Ferramenta Por quê
Trabalho seu com documento, planilha, apresentação Cowork Interface pronta, conectores, sem código
Trabalho seu em repositório, com ferramentas de sistema Claude Code Ferramentas, permissões e verificação prontas
Tarefa recorrente sua, agendada Routine ou headless (3.5) Ainda é Claude Code — não precisa de API
Pipeline de CI que responde a PR GitHub Actions (3.5.5) Idem
Produto que o cliente usa API O usuário final não tem a ferramenta
Milhares de itens, sem ninguém olhando API (ou Batches) Volume e custo por item
Funcionalidade dentro de sistema existente API Integração
Agente com ferramentas de sistema, na sua infra Agent SDK (3.7.7) Claude Code como biblioteca

As linhas 3 e 4 são a armadilha mais cara deste módulo. É comum alguém aprender a API e reescrever em Python uma automação que a routine do módulo 3.5 já fazia — com menos verificação e mais manutenção.

O que você perde ao sair dos apps

Nos apps, vem pronto Na API, é código seu
Interface de conversa Você constrói
Histórico e sessão A API é stateless — você reenvia a conversa inteira a cada chamada
Compactação de contexto Você implementa (ou usa o recurso de compaction, em beta)
Conectores configurados Você conecta, ou usa MCP pela API
Modos de permissão e classificador Você decide o que a ferramenta pode fazer
Checkpoints e /rewind Não existe
Skills, CLAUDE.md, plugins Não se aplicam — são do Claude Code

A segunda linha é a que mais surpreende: a API não lembra de nada. Cada chamada é independente, e "continuar a conversa" significa reenviar todas as mensagens anteriores. É a razão de o prompt caching da aula 3.7.4 existir.

Os quatro critérios de "vale construir um agente?"

Antes de subir do tier de chamada única para workflow ou agente, a documentação sugere quatro perguntas — e basta uma resposta "não" para ficar no tier de baixo:

Critério Pergunta
Complexidade A tarefa é multipasso e difícil de especificar por inteiro de antemão?
Valor O resultado justifica mais custo e mais latência?
Viabilidade O Claude é bom nesse tipo de tarefa?
Custo do erro O erro é detectável e reversível?

O quarto critério é o que mais reprova casos em contexto SAP. Um agente que escreve num sistema de cliente tem custo de erro alto e reversão cara — o que não impede o projeto, mas empurra o desenho para uma proposta que um humano aprova, em vez de uma ação que o agente executa.

Regra Wayon Antes de propor solução com API para um cliente, é obrigatório registrar por que Cowork, Claude Code ou routine não resolvem. Construir com API significa a Wayon assumir manutenção de código em ambiente de cliente — isso tem custo de sustentação e precisa estar na proposta, não só o custo de tokens.

📖 Client SDKs · Automação: routines, headless e CI — módulo 3.5

Quiz — 4 questões

1.O Meridiano quer que o key user descreva o problema num portal do próprio cliente e receba área e prioridade na tela. Qual é a escolha?
  • a)Claude Code em modo headless, disparado pelo portal

    Exigiria expor o Claude Code a partir do portal do cliente e manter o ambiente dele; a API é o caminho direto para produto.

  • b)API — o usuário final é o cliente, e a saída entra numa tela que a Wayon controla

    Correto. "Quem usa, e por onde" é o critério que decide.

  • c)Cowork com um Project compartilhado com o key user

    Exigiria licença e treinamento do usuário final, e a saída não entra na tela do portal.

Ver resposta e por quê
❌a) Exigiria expor o Claude Code a partir do portal do cliente e manter o ambiente dele; a API é o caminho direto para produto.
✅b) Correto. "Quem usa, e por onde" é o critério que decide.
❌c) Exigiria licença e treinamento do usuário final, e a saída não entra na tela do portal.
2.Um consultor reescreve em Python, com a API, uma automação que hoje roda como routine agendada. Qual é a avaliação correta?
  • a)É retrabalho: a routine já resolve, e a versão em Python perde as verificações e ganha manutenção

    Correto. É a armadilha mais comum de quem acabou de aprender a API.

  • b)É um ganho: a API dá controle fino de custo, que a routine não oferece

    Controle de custo só justifica a mudança quando há volume; para a mesma tarefa agendada, o controle não compensa a manutenção.

  • c)É indiferente — as duas superfícies fazem a mesma coisa com o mesmo esforço

    Não é o mesmo esforço: a routine traz ferramentas, permissões e verificação prontas.

Ver resposta e por quê
✅a) Correto. É a armadilha mais comum de quem acabou de aprender a API.
❌b) Controle de custo só justifica a mudança quando há volume; para a mesma tarefa agendada, o controle não compensa a manutenção.
❌c) Não é o mesmo esforço: a routine traz ferramentas, permissões e verificação prontas.
3.Qual afirmação sobre a Claude API está correta?
  • a)A API é stateless: continuar a conversa significa reenviar todas as mensagens anteriores

    Correto, e é a razão de o prompt caching existir.

  • b)A API mantém o histórico da conversa por identificador de sessão

    Não mantém — não existe sessão do lado da API na Messages API.

  • c)A API guarda o contexto por até 30 dias e permite retomar pelo message_id

    Retenção de dados não é memória de conversa; retomar exige reenviar as mensagens.

Ver resposta e por quê
✅a) Correto, e é a razão de o prompt caching existir.
❌b) Não mantém — não existe sessão do lado da API na Messages API.
❌c) Retenção de dados não é memória de conversa; retomar exige reenviar as mensagens.
4.Aplicando os quatro critérios de "vale construir um agente?", qual deles costuma reprovar casos em contexto SAP? ---
  • a)Viabilidade — o Claude tem desempenho fraco em domínio SAP

    Viabilidade raramente é o gargalo; o desempenho em texto de projeto é bom.

  • b)Valor — o ganho de automação em SAP costuma ser pequeno demais

    O ganho costuma ser justamente grande; não é aí que a análise trava.

  • c)Custo do erro — escrever em sistema de cliente é difícil de detectar e caro de reverter

    Correto, e é o que empurra o desenho para "propor e um humano aprova" em vez de "o agente executa".

Ver resposta e por quê
❌a) Viabilidade raramente é o gargalo; o desempenho em texto de projeto é bom.
❌b) O ganho costuma ser justamente grande; não é aí que a análise trava.
✅c) Correto, e é o que empurra o desenho para "propor e um humano aprova" em vez de "o agente executa".