Desenvolvimento com IA e Programação: Crie Apps

Os erros de rede do Claude Code ("Can't reach the API server", "Connection refused", SSL certificate verification failed, fetch failed) significam que a requisição nunca chegou ao servidor da Anthropic — diferente de autenticação (401/403), servidor (529/500) e taxa (429). Antes da v2.1.227, os mesmos erros apareciam como "Unable to connect to API (ECONNREFUSED)". Este guia explica o que cada mensagem atual significa, o encerramento na configuração inicial com "Unable to connect to Anthropic services", o aviso "Streaming response ended before any complete data was received" quando um proxy altera a resposta, a configuração de proxy (HTTPS_PROXY), a CA corporativa em NODE_EXTRA_CA_CERTS (com segurança), os domínios a liberar e o fluxo de diagnóstico começando por curl.

O "API Error: 529 Overloaded" e o "500 Internal server error" do Claude Code são eventos do lado do servidor: a API da Anthropic está temporariamente sobrecarregada ou com erro interno. Não são culpa sua nem esgotamento de cota, e o Claude Code já tenta de novo até 10 vezes com backoff exponencial. A solução é esperar, trocar de modelo com /model e verificar o status.claude.com — e como distinguir de 429, usage limit e 400.

A mensagem "You've hit your session limit · resets 3:45pm" do Claude Code não é um erro, e sim como funcionam os limites de uso da assinatura. A referência oficial lista quatro variantes: session (a janela rolante de 5 horas), weekly (a janela semanal) e Opus e Sonnet (tetos de uma só família de modelos); como os limites de sessão e semanal valem para todos os modelos, trocar de modelo não devolve o acesso. Explicamos o que cada mensagem significa e como o texto mudou desde o antigo "Claude usage limit reached", o que mais consome a cota e o que fazer ao bater no teto: trocar de modelo com /model diante de um teto de Opus/Sonnet, esperar o reset (automático a partir da v2.1.234), usar créditos de uso com /usage-credits ou migrar para a API pay-as-you-go. Inclui como ver quanto resta com /usage e as mensagens parecidas que não são o seu limite.

O Claude Code informa "Prompt is too long" quando a entrada total, incluindo histórico, arquivos e resultados de ferramentas, ultrapassa o limite de contexto. Este artigo diferencia compactar um histórico longo, reduzir uma primeira entrada excessiva e resolver a causa de um erro de compactação, como falha de autenticação. As definições MCP são carregadas sob demanda por padrão; a disponibilidade de 1M depende do modelo, da conexão e do plano. Também explica contagem de tokens e motivos de parada no uso direto da API.

Quando um servidor MCP não conecta no Claude Code, confira juntos o status, o método de conexão e os detalhes de Issue. failed pode indicar falha de inicialização stdio, falha de comunicação HTTP ou rejeição de um cabeçalho fixo de autenticação. O artigo explica Connection closed, variáveis de ambiente e referências indefinidas, configuração e aprovação do projeto, inicialização do npx no Windows, logs de depuração e testes após reconectar. Também esclarece por que zero ferramentas não é necessariamente um erro e por que iniciar de forma independente não garante uma conexão MCP bem-sucedida.

Rodando sessões longas no Claude Code, às vezes "court" (ou "call") e tags <invoke> cruas vazam como texto e o comando nunca é executado. Não é o seu ambiente: é uma falha do lado do modelo (Opus 4.8 / 4.7) que corrompe o token de controle da chamada de ferramenta. O harness a rejeita em modo fail-closed, então não há risco de comando errado — mas o bloco quebrado "encadeia" no histórico. Veja as causas, os equívocos comuns, as correções para usuário e desenvolvedor, e por que sair para uma sessão nova (/clear) é a melhor jogada.

Retreinar uma IA gigante do zero é caro demais, mas você quer ajustá-la só para você; o LoRA (Low-Rank Adaptation) realiza esse desejo congelando o modelo original e treinando apenas uma pequena peça adicional (um adaptador), reduzindo os parâmetros treináveis a menos de 1% do modelo original. O LoRA torna o fine-tuning drasticamente mais barato e rápido, e é enormemente popular na geração de imagens, como no Stable Diffusion, como um pequeno arquivo que adiciona um personagem ou estilo. Este artigo explica com uma analogia de remendo. O LoRA é o carro-chefe do fine-tuning eficiente em parâmetros (PEFT): deixar os enormes pesos originais congelados, inserir uma pequena matriz adicional em cada camada e treinar apenas isso (W = W0 + BA, onde W0 fica congelado e BA é a pequena parte adicionada). Ele se baseia na hipótese de que adaptar uma IA não exige grandes mudanças (um rank baixo basta), que os experimentos do artigo original corroboraram (embora haja estudos em que ele fica abaixo do treinamento completo em matemática e programação). Benefícios: parâmetros treináveis abaixo de 1% do original (cerca de 10.000 vezes menos com o GPT-3 175B no artigo original), menos memória de GPU (no mesmo caso, de 1,2 TB para 350 GB durante o treinamento), treinamento mais rápido e barato, sem latência de inferência depois que o adaptador é mesclado, e menos perda das capacidades do modelo original. Sua maior força são os adaptadores intercambiáveis: mantenha uma base comum e troque pequenos arquivos LoRA por caso de uso (suporte, tom da empresa, um personagem específico) instantaneamente. Muita gente encontra o LoRA pela primeira vez na geração de imagens, onde LoRAs do Stable Diffusion que aprenderam um personagem, estilo ou tema são amplamente compartilhados. O QLoRA combina a quantização, treinando o LoRA sobre uma base 4-bit: permitiu o fine-tuning, em uma única GPU de 48 GB, de um modelo de 65B que, treinado por completo em 16 bits, exigiria mais de 780 GB, e de um modelo de 33B em uma GPU de consumo de 24 GB, com desempenho equivalente ao dos métodos de 16 bits nas comparações do artigo (o próprio artigo diz que não verificou se ele se iguala ao treinamento completo em 33B e 65B). Diferentemente do fine-tuning completo (treinar todos os pesos), o LoRA difere nos pesos treinados, no custo, no resultado e no melhor uso; para a maior parte do trabalho, o LoRA basta. Mantenha a base, tempere pouco. Os números vêm das condições experimentais dos artigos originais e outros, como orientação.

Um enorme modelo de 70B rodando em um único PC caseiro, em vez de um rack de GPUs de data center (com a CPU e a RAM assumindo a parte que não cabe numa GPU de consumidor), é possível graças à quantização, que reduz a precisão numérica dos pesos do modelo para encolher drasticamente tamanho e memória. Enquanto a destilação transfere conhecimento para um modelo separado e menor, a quantização deixa o mesmo modelo mais leve. Este artigo explica isso com uma analogia de compressão de fotos. A quantização substitui pesos armazenados como decimais FP16/FP32 por inteiros INT8 (8 bits) ou INT4 (4 bits), cortando bytes por peso (FP32=4, INT8=1, INT4=0,5); como comprimir uma foto RAW para JPEG, você sacrifica um pouco de precisão por uma grande redução, e a surpresa é o quão pouco abre mão. Em memória, 4-bit usa cerca de um quarto do FP16: um modelo de 70B cai de ~140GB para ~35GB, e um de 8B em 4-bit fica em ~4.5-5GB, cabendo em uma GPU intermediária de 8GB de VRAM para uso local (a democratização dos LLMs). Em precisão, INT8 é praticamente sem perdas e INT4, segundo relatos, degrada abaixo de 4% em perguntas e respostas gerais e senso comum, mas a perda é mais perceptível em matemática, geração de código e raciocínio difícil (aparece como um pequeno aumento na perplexidade), então escolha a precisão em bits pela tarefa. Principais métodos: GPTQ (pioneiro do 4-bit preciso), AWQ (protege os ~1% pesos mais importantes; se supera o GPTQ depende da avaliação), GGUF (formato llama.cpp/Ollama, Q2_K-Q8_0, híbrido CPU+GPU, para uso local) e QLoRA (base de 4-bit mais LoRA para fine-tuning em GPU de consumidor). Difere da destilação (mudar para um modelo separado menor) e do fine-tuning (adicionar conhecimento de tarefa), e as três costumam ser combinadas (quantizar um modelo destilado; fazer fine-tuning sobre uma base quantizada). Para começar, rode um modelo GGUF com o Ollama em um comando, escolha Q4/Q8 pela VRAM e evite INT4 para código ou matemática exata. A maioria dos grandes modelos já vem quantizada, então basta baixar e usar. Mantenha a inteligência, tire apenas o peso. Os números são citados de materiais públicos, indicativos.

Uma IA enorme e de alto desempenho é inteligente, mas pesada e cara; a destilação de modelos (destilação de conhecimento) resolve isso transferindo o conhecimento de um grande modelo professor para um pequeno modelo aluno, mantendo um desempenho próximo ao do professor com um tamanho muito menor e mais velocidade. Este artigo explica o tema com uma analogia professor-aluno. A chave são os soft labels: o treinamento comum só ensina "a resposta é gato" (hard label), enquanto a destilação passa toda a distribuição de probabilidade do professor, como "90% gato, 8% cachorro, 2% raposa", cujo grau de hesitação carrega informações ricas; um parâmetro temperature suaviza as probabilidades para revelar relações sutis (exemplo real: o recurso de 2024 da API da OpenAI para treinar modelos menores com saídas de modelos maiores). Benefícios: rápido e barato, muito mais compacto com desempenho próximo ao do professor (TinyBERT: 7,5x menor, mais de 96,8%), roda na edge e é forte para especialização. Duas abordagens: white-box (acesso total a pesos e representações internas, transferência mais profunda; para seus modelos ou modelos OSS) e black-box (só as saídas/respostas da API visíveis; usar a API de outra empresa como professor pode violar os termos). Difere da quantização (comprimir a precisão dos pesos do mesmo modelo) e do fine-tuning (continuar treinando um modelo existente para uma tarefa) — a destilação move o conhecimento para um modelo pequeno separado, e as três são combináveis. A realidade jurídica/ToS foi um grande tema em 2026: a técnica é legítima, mas OpenAI, Anthropic e xAI incluem cláusulas de destilação anticompetitiva que proíbem usar saídas para criar modelos concorrentes, então destilar um concorrente a partir de uma API restrita pode violar os termos. A disputa OpenAI v. DeepSeek (a OpenAI alegou que contas ligadas à DeepSeek burlaram restrições para obter saídas para destilação, enquanto os termos da DeepSeek supostamente permitem destilar suas saídas) mostra que a avaliação depende de quais termos de API se aplicam, e o Claude Fable 5/Mythos 5 desvia solicitações sinalizadas como destilação para um modelo Opus menos capaz. Dicas: use seus modelos ou modelos OSS licenciados como professor, verifique as cláusulas antidestilação antes de usar uma API comercial e avalie se o uso configura desenvolvimento de um modelo concorrente. Inteligência do modelo grande, operação do pequeno — mas quem você escolhe como professor muda o resultado técnica e juridicamente. Os números são citados de materiais públicos, em caráter orientativo.

Em "Como construir um sistema multiagente" dissemos para instrumentar cada handoff antes de adicionar agentes; a tecnologia que sustenta essa instrumentação em produção é a observabilidade de IA. Ela torna visível o que LLMs e agentes realmente fazem em produção (qual modelo com qual prompt, quais ferramentas e buscas, o que foi retornado, quanto tempo e quanto custou) para que você possa rastrear até a causa. A diferença decisiva em relação ao monitoramento comum: a IA pode retornar 200 OK em 50ms e ainda alucinar com confiança, então a maioria das falhas de IA são falhas de qualidade (alucinação, recuperação fraca, respostas inseguras, tarefas incompletas, uso ruim de ferramentas, regressões após mudar o prompt), não falhas de infraestrutura. A observabilidade se apoia em três pilares: traces (uma requisição como árvore de spans mostrando chamadas de LLM, ferramentas, recuperação, cadeias de raciocínio; a estrela da observação de IA), métricas (latência, custo, tokens, taxa de erro, throughput) e logs (detalhe por evento). O padrão da indústria, as convenções GenAI do OpenTelemetry, captura prompts, respostas, uso de tokens e chamadas de ferramentas/agentes em um esquema neutro alimentável no Datadog/Grafana. A distinção mais confundida é observabilidade vs avaliação (evals): a observabilidade mostra o que aconteceu (fácil de medir, mas não diz se a resposta está correta), enquanto as evals medem se a resposta é boa (precisão, groundedness, segurança) e exigem avaliação explícita. Como custo e latência são fáceis de medir mas a qualidade da resposta não, as ferramentas de 2026 combinam exibição de traces com pontuação de saídas e alertas de degradação. As métricas se dividem em operacionais (custo, latência, tokens, taxa de erro) e de qualidade (alucinação, groundedness/fidelidade que é a mais crítica para RAG, segurança, conclusão da tarefa), com detecção de alucinação via LLM-as-a-judge, similaridade semântica e scores de groundedness. Principais ferramentas: LangSmith (LangChain), Langfuse (open-source self-host), Arize Phoenix (depuração de RAG), MLflow (ciclo de vida), AgentOps (agentes) e OpenTelemetry (o padrão). Comece capturando traces (compatível com OpenTelemetry), visualize métricas operacionais e depois conecte as evals antes de subir para produção. Para sistemas multiagente a observação é essencial, pois as falhas se escondem em cadeias de múltiplos passos visíveis apenas em um trace da sessão completa. Observar mais avaliar é o que torna a IA de nível de produção. Figuras e características são citadas de materiais públicos, direcionais.

A continuação prática de "O que é um sistema multi-agente?". A regra central: construir primeiro com um único agente e adicionar agentes de forma mínima só ao bater num limite (um estudo do Google Research viu todas as configurações multi-agente renderem 39–70% pior numa tarefa estritamente sequencial, e a Anthropic relata que sistemas multi-agente usam cerca de 15 vezes mais tokens que um chat). A forma básica é o padrão supervisor: subagentes no Claude Agent SDK, agents as tools no OpenAI Agents SDK. Além dos 5 passos (decompor, definir workers, projetar o supervisor, transferências, medir), traz código mínimo para os dois SDKs segundo a documentação oficial (um supervisor mais um pesquisador e um revisor), como restringir as ferramentas de cada papel, limites em três camadas (maxTurns, max_turns, gasto), quando usar handoffs, boas e más divisões de papéis e falhas reais da Anthropic (50 subagentes para uma consulta simples, pesquisa duplicada) com soluções.

Agora que os agentes de IA se tornaram comuns, o próximo desafio é como fazê-los colaborar entre si. Se o MCP conecta um agente às suas ferramentas, o A2A (Agent2Agent) conecta um agente a outro agente — um padrão aberto para que IAs construídas com fornecedores e frameworks diferentes se descubram, se comuniquem e cooperem por meio de uma convenção comum. O Google o lançou em abril de 2025, doou-o à Linux Foundation em junho daquele ano, e ele chegou à v1.0 em 2026. Este guia para iniciantes cobre o que é o A2A (a analogia da etiqueta de uma parceria de negócios), por que é necessário (agentes especializados revezam o trabalho — um agente de planejamento, um de reserva de hotel, um de pagamento), como se diferencia do MCP (o MCP é vertical, agente ↔ ferramentas; o A2A é horizontal, agente ↔ agente; empilhar os dois é a configuração padrão de duas camadas), como funciona (um Agent Card — um JSON "cartão de visita" em /.well-known/agent-card.json — é usado para descobrir capacidades, depois uma Task carrega a solicitação por estados como working, input-required e completed, e um Artifact retorna o resultado, tudo sobre HTTP, Server-Sent Events e JSON-RPC 2.0, com os agentes mantendo seus detalhes internos ocultos), e qual é a situação atual e a implementação (em abril de 2026, 150+ organizações apoiadoras, 22.000+ estrelas no GitHub, SDKs em cinco linguagens — Python, JavaScript, Java, Go, .NET — com Microsoft, Salesforce, SAP e ServiceNow envolvidos). O mnemônico: conectar a ferramentas = MCP, conectar a pares = A2A.