Como construir um chatbot de IA com a API Claude em 2026

Construir um chatbot costumava significar lidar com classificadores de intenção, árvores de diálogo e uma infinidade de casos de borda. Com uma API moderna de modelos de linguagem, o modelo assume a parte mais difícil — compreender e responder — e sua tarefa é apenas conectar os componentes. Com a API Claude, é possível ter um chatbot genuinamente capaz funcionando em bem menos de uma hora.

Este guia aborda os conceitos e o código necessários: configuração, manutenção de uma conversa, direcionamento do comportamento, transmissão contínua das respostas (streaming) e controle dos custos.

Etapa 1: Configuração inicial

Você precisa de duas coisas: uma chave de API e o SDK.

1. Obtenha uma chave de API — crie uma conta no Console Anthropic e gere uma chave de API. Mantenha-a em segredo: armazene-a em uma variável de ambiente, nunca a insira diretamente no código ou a inclua no controle de versão.
2. Instale o SDK — a Anthropic fornece SDKs oficiais. Para Python:

pip install anthropic

(Também há um SDK para Node.js; os conceitos descritos a seguir são idênticos.)

Etapa 2: Sua primeira mensagem

O cerne da API Claude é a API Messages. Você envia uma lista de mensagens e a Claude retorna a próxima. Aqui está a chamada mais simples possível:

from anthropic import Anthropic

client = Anthropic() # reads the ANTHROPIC_API_KEY environment variable

response = client.messages.create(
 model="claude-sonnet-4-6",
 max_tokens=1024,
 messages=[
 {"role": "user", "content": "Hello! What can you help me with?"}
 ],
)

print(response.content[0].text)

Trata-se de um chatbot funcional — embora muito esquecido. model seleciona qual versão da Claude utilizar, max_tokens limita o comprimento da resposta e messages representa a conversa até o momento.

Etapa 3: Dê-lhe memória

O exemplo acima não possui memória: cada chamada é independente. Para manter uma conversa real, você mantém o histórico e o reenvia a cada nova interação. A própria API é sem estado — ela conhece apenas o que você lhe envia.

O padrão consiste em manter uma messages lista, anexar a cada nova mensagem do usuário e a cada resposta da Claude, e enviar toda essa lista em cada chamada.

from anthropic import Anthropic

client = Anthropic()
messages = []

while True:
 user_input = input("You: ")
 if user_input.lower() == "quit":
 break

 messages.append({"role": "user", "content": user_input})

 response = client.messages.create(
 model="claude-sonnet-4-6",
 max_tokens=1024,
 messages=messages,
 )

 reply = response.content[0].text
 print(f"Claude: {reply}")

 messages.append({"role": "assistant", "content": reply})

Agora ele é um verdadeiro chatbot — lembra-se de tudo o que foi dito anteriormente na conversa, pois esse histórico é enviado a cada nova interação.

Etapa 4: Defina sua personalidade com um prompt do sistema

Um assistente genérico raramente é o que você deseja. O prompt do sistema define o papel, o tom e as regras do bot. É passado como um parâmetro separado system e não como uma mensagem.

SYSTEM_PROMPT = """You are a friendly support assistant for a coffee
subscription service. Be warm, concise, and helpful. If a customer asks
about something you don't know, tell them you'll connect them to a human
agent. Never discuss competitors."""

response = client.messages.create(
 model="claude-sonnet-4-6",
 max_tokens=1024,
 system=SYSTEM_PROMPT,
 messages=messages,
)

O prompt do sistema é sua principal ferramenta para moldar o comportamento — invista tempo nele. Seja específico quanto ao papel, ao tom, ao que o bot deve fazer quando estiver inseguro e a quaisquer limites rígidos.

Etapa 5: Transmitir a resposta em fluxo (streaming)

Nos exemplos acima, você aguarda toda a resposta antes que qualquer coisa apareça. Interfaces reais de chat transmitem em fluxo — o texto chega palavra por palavra. O SDK torna isso simples:

with client.messages.stream(
 model="claude-sonnet-4-6",
 max_tokens=1024,
 system=SYSTEM_PROMPT,
 messages=messages,
) as stream:
 for text in stream.text_stream:
 print(text, end="", flush=True)

O streaming não torna a geração mais rápida, mas faz com que o bot pareça dramaticamente mais responsivo, pois o usuário vê a saída imediatamente.

Etapa 6: Reduzir custos com cache de prompts

As chamadas à API são cobradas por tokens, e um chatbot reenvia muitos dos mesmos textos a cada turno — o prompt do sistema e um histórico de conversa que só cresce. O cache de prompts permite marcar partes estáveis do prompt para que a API as reutilize em vez de processá-las novamente, reduzindo substancialmente tanto custo quanto latência.

Você adiciona um marcador de cache ao conteúdo que deseja armazenar em cache — normalmente o prompt do sistema e qualquer contexto fixo e extenso:

response = client.messages.create(
 model="claude-sonnet-4-6",
 max_tokens=1024,
 system=[
 {
 "type": "text",
 "text": SYSTEM_PROMPT,
 "cache_control": {"type": "ephemeral"},
 }
 ],
 messages=messages,
)

Para qualquer chatbot que lide com tráfego real, ative o cache de prompts desde o início — trata-se de uma das otimizações de maior impacto disponíveis, e não há nenhum custo para ativá-lo.

Escolhendo um modelo

Claude está disponível em diversos níveis. Como regra geral:

• Um modelo rápido e equilibrado (como o nível Sonnet) é a escolha padrão ideal para a maioria dos chatbots — qualidade sólida, boa velocidade e custo razoável.
• O modelo mais capaz (o nível Opus) vale a pena quando o bot precisa lidar com raciocínio complexo ou tarefas difíceis.
• Um modelo menor e mais rápido (o nível Haiku) é adequado para chatbots simples e de alto volume, onde velocidade e custo são prioridades máximas.

Comece com o nível equilibrado e só mude para cima ou para baixo após observar o uso real.

Implantação em produção

O código acima representa o núcleo funcional. Para uma implantação real, adicione:

• Uma camada web — envolva a lógica em um endpoint de API e conecte uma interface de chat.
• Limites de histórico — as conversas crescem indefinidamente; limite ou resuma turnos antigos para evitar que os prompts fiquem excessivamente longos.
• Tratamento de erros — trate limites de taxa e falhas transitórias com novas tentativas (retries).
• Conhecimento — para responder com base em seus próprios dados, adicione a geração aumentada por recuperação (retrieval-augmented generation) para que o bot recupere documentos relevantes.
• Segurança — valide entradas e defina limites claros no prompt do sistema.

Trate erros e limites de taxa antes que os usuários os descubram

Um chatbot que funciona em seu laptop ainda pode falhar em produção no exato momento em que o tráfego real atingi-lo. A API da Claude apresenta dois tipos de falha, e cada um exige uma resposta distinta. O primeiro é erros transitórios na API — esses ocorrem como exceções com um código de status HTTP. O segundo é uma recusa, que é uma resposta perfeitamente bem-sucedida, mas que simplesmente recusou a solicitação. Confundir os dois é o erro de confiabilidade mais comum que observamos no código inicial de chatbots.

No lado transitório, dois códigos de status são os mais relevantes:

• 429 (limite de taxa) — você excedeu a cota de solicitações por minuto ou tokens por minuto da sua conta. A resposta inclui um cabeçalho retry-after indicando exatamente quantos segundos você deve aguardar. Respeite-o rigorosamente; esperar menos apenas gerará outro erro 429.
• 529 (sobrecarga) — a API da Anthropic está temporariamente saturada para todos os usuários. Você não pode evitar isso por meio de código, e as solicitações rejeitadas com código 529 não são cobradas. Reduza a frequência das chamadas e tente novamente; nunca force repetidamente um endpoint sobrecarregado.
• 500 (erro do servidor) — uma falha interna rara. Trate-a da mesma forma que o código 529: tente novamente com redução progressiva (backoff).

A boa notícia é que os SDKs oficiais já realizam novas tentativas automaticamente para erros 429 e 5xx, aplicando redução progressiva exponencial (o padrão é duas tentativas). Para um chatbot em produção, aumente esse limite e deixe que o SDK faça o trabalho, em vez de escrever seu próprio loop:

• Aumente max_retries no cliente (um valor entre 4 e 5 é razoável para chatbots voltados ao usuário).
• Capture as exceções tipadas — RateLimitError, OverloadedError, APIError — em vez de comparar strings no texto do erro, o que falha silenciosamente caso a mensagem seja alterada.
• Quando as tentativas forem finalmente esgotadas, mostre ao usuário uma mensagem calma do tipo «Estou um pouco ocupado agora, tente novamente em um instante», em vez de exibir um stack trace.

As recusas constituem um caminho totalmente distinto. Quando uma resposta retorna com stop_reason: "refusal", a solicitação foi bem-sucedida — a Claude recusou-se a responder por motivos de segurança, e, nos modelos atuais, você não é cobrado quando nenhuma saída foi gerada. É fundamental que você não envie novamente exatamente a mesma conversa: a recusa se repetirá. Em vez disso, remova ou reformule a mensagem que a desencadeou, ou reinicie o histórico, e forneça ao usuário uma explicação clara. Como uma recusa é um campo na resposta — e não uma exceção —, qualquer código que inspecione apenas end_turn e tool_use poderá deixá-la passar despercebida, resultando em uma resposta vazia e confusa. Sempre adicione um ramo explícito para tratá-la.

Implemente esses três comportamentos — nova tentativa com redução progressiva, tratamento tipado de exceções e um ramo específico para recusas — e seu chatbot degradará com elegância sob carga, em vez de falhar de forma ruidosa diante das pessoas para as quais ele foi criado.

Perguntas frequentes

Como criar um chatbot com a API Claude?

Instale o SDK da Anthropic, obtenha uma chave de API e chame a API Messages: envie uma lista de mensagens e a Claude retornará uma resposta. Para torná-la conversacional, mantenha o histórico de mensagens em seu aplicativo e reenvie-o a cada turno. Adicione um prompt do sistema para personalidade e use streaming para uma sensação de responsividade.

A API Claude lembra mensagens anteriores?

Não — a API é sem estado (stateless). Ela só conhece o que você envia em uma determinada solicitação. Para dar memória a um chatbot, seu aplicativo deve armazenar o histórico da conversa e incluí-lo na messages lista em todas as chamadas.

O que é um prompt do sistema?

O prompt do sistema é uma instrução separada que define o papel, o tom e as regras do chatbot — por exemplo, "Você é um assistente de suporte conciso; encaminhe ao agente humano quando estiver inseguro." É passado como o parâmetro system e constitui a principal forma de moldar o comportamento do bot.

Quanto custa executar um chatbot Claude?

O custo depende do modelo e da quantidade de tokens processados. Um modelo equilibrado é barato para tráfego típico de chat. Como os chatbots reenviam o prompt do sistema e o histórico em constante crescimento a cada turno, ativar o cache de prompts pode reduzir significativamente os custos — ele reutiliza as partes estáveis do prompt em vez de processá-las novamente.

Qual modelo Claude devo usar para um chatbot?

Para a maioria dos chatbots, comece com um modelo rápido e equilibrado (nível Sonnet) — oferece qualidade sólida com velocidade e custo razoáveis. Use o modelo mais capaz para tarefas complexas de raciocínio e um modelo menor e mais rápido para chatbots simples e de alto volume.

O que significam os erros 429 e 529 da API da Claude?

Um erro 429 indica que você atingiu o limite de taxa da sua conta (solicitações ou tokens por minuto); a resposta inclui um cabeçalho retry-after indicando quanto tempo você deve aguardar. Um erro 529 significa que a API da Anthropic está temporariamente sobrecarregada para todos os usuários — essas solicitações não são cobradas e não podem ser evitadas por meio de código. Ambos exigem redução progressiva exponencial, que os SDKs oficiais aplicam automaticamente por padrão.

Como meu chatbot deve lidar com uma recusa da Claude?

Uma recusa chega como uma resposta normal e bem-sucedida com stop_reason: "refusal", e não como um erro, e você não é cobrado quando nenhuma saída foi produzida. Não tente novamente a solicitação idêntica — ela será recusada novamente. Remova ou reformule a mensagem que a desencadeou (ou reinicie a conversa) e forneça ao usuário uma explicação clara e amigável. Nas versões Opus 4.7 e posteriores, a resposta também inclui um campo stop_details que indica qual política foi acionada.

Preciso escrever minha própria lógica de nova tentativa para a API da Claude?

Normalmente, não. Os SDKs oficiais da Anthropic já realizam novas tentativas automaticamente para erros 429 e 5xx com redução progressiva exponencial, sem necessidade de configuração adicional, com um padrão de duas tentativas. Para um chatbot voltado ao usuário, a configuração mais simples e robusta consiste em aumentar max_retries para cerca de quatro ou cinco no cliente e capturar as exceções tipadas (como RateLimitError e OverloadedError) em vez de implementar manualmente um loop de redução progressiva ou comparar strings de erro.

Conclusão

Criar um chatbot com a API Claude consiste principalmente na integração técnica, não na inteligência artificial. O modelo cuida da compreensão e da geração da resposta; você fornece o laço (loop). Mantenha um messages histórico e reenvie-o para garantir memória, use um system prompt para personalidade, ative o streaming para responsividade e habilite o cache de prompts para controlar custos.

Esse núcleo realmente leva cerca de uma hora para ser implementado. O caminho até a produção envolve a engenharia familiar ao redor dele — uma camada web, gerenciamento de histórico, tratamento de erros e RAG caso o bot precise acessar seus dados. Comece com o loop simples acima, faça-o funcionar e construa progressivamente a partir daí.