API Claude

Prévia do material em texto

APOSTILA DE ESTUDO
API do Claude, SDKs e Ferramentas de Código
Transição para Desenvolvimento
Trilha de Formação em Inteligência Artificial com Claude (Anthropic)
Material de apoio para aulas, laboratórios e atividades em grupo
Sumário
1. Introdução
2. Como Funciona a API da Anthropic
3. O Console Anthropic (Claude Platform)
4. API Keys — Criação, Uso e Segurança
5. Modelos Disponíveis e Precificação
6. A SDK Oficial (Python e TypeScript/Node.js)
7. Structured Outputs — Respostas em JSON
8. Tool Use (Function Calling)
9. Atividades em Grupo
10. Checklist de Fixação e Exercícios
11. Glossário
12. Referências Oficiais
1. Introdução
Nas semanas anteriores da trilha, o foco esteve em usar o Claude como assistente — por meio do claude.ai,
do aplicativo ou de outras interfaces prontas. A partir de agora, a jornada muda de direção: você deixa de
ser apenas usuário do Claude e passa a ser desenvolvedor sobre o Claude.
Isso significa aprender a se comunicar com o modelo diretamente por código, por meio da API da Anthropic.
Essa é a mesma tecnologia que sustenta o Claude.ai, o Claude Code, o Claude para Excel e praticamente
todos os produtos oficiais — a diferença é que, a partir de agora, você está no controle: você decide o
prompt, o modelo, o formato da resposta e o que o Claude pode ou não fazer.
Objetivo desta semana
Sair da experiência de chat e entender a API da Anthropic como uma ferramenta de
desenvolvimento: autenticação, custos, e as duas capacidades que tornam o Claude útil dentro de
sistemas — respostas estruturadas (JSON) e uso de ferramentas (Tool Use).
1.1 O que você vai aprender
• Como funciona a API da Anthropic: o Console (Claude Platform), as API Keys e o modelo de
precificação por tokens.
• Como instalar e usar a SDK oficial da Anthropic em Python ou em TypeScript/Node.js.
• O que são Structured Outputs (respostas em JSON) e como forçar o Claude a responder em um
formato previsível.
• O que é Tool Use (Function Calling) e como ele permite que o Claude execute ações e consulte
sistemas externos.
1.2 Pré-requisitos
• Conta ativa no Console da Anthropic (console.anthropic.com / platform.claude.com).
• Python 3.9+ ou Node.js 18+ instalado na máquina.
• Noções básicas de programação (variáveis, funções, listas/dicionários ou objetos JSON).
• Um editor de código (VS Code é o mais usado no mercado).
2. Como Funciona a API da Anthropic
A API da Anthropic é uma API REST hospedada em https://api.anthropic.com. Toda a comunicação
acontece por meio de requisições HTTP para o endpoint principal de mensagens (Messages API), enviando
um JSON com o modelo desejado, o histórico da conversa e parâmetros como o número máximo de tokens
de saída.
Diferente do chat, onde você digita e recebe texto na tela, na API cada chamada é uma transação isolada e
sem memória: o Claude não guarda o que foi dito antes, a menos que você reenvie o histórico da conversa
a cada nova chamada. Isso é fundamental para entender como aplicações são construídas sobre o modelo.
Ponto-chave
A API é "stateless" (sem estado). Cabe à sua aplicação armazenar e reenviar o histórico de
mensagens a cada requisição — o modelo não lembra de nada por conta própria.
2.1 O Console Anthropic (Claude Platform)
O Console — atualmente também chamado de Claude Platform — é o painel web onde toda a gestão de
acesso à API acontece. É nele que a equipe irá:
• Criar e organizar Workspaces (espaços de trabalho, úteis para separar projetos ou times).
• Gerar e revogar API Keys.
• Acompanhar o consumo de tokens e o custo em tempo real (dashboard de uso).
• Configurar limites de gasto (spend limits) e métodos de pagamento.
• Testar prompts diretamente pelo navegador, sem escrever código (Workbench).
Endereço de acesso: console.anthropic.com (as páginas de documentação técnica ficam em
docs.claude.com e platform.claude.com).
2.2 API Keys — Criação, Uso e Segurança
Uma API Key é a credencial que identifica sua aplicação (ou seu grupo) perante a Anthropic. Ela
normalmente tem o formato sk-ant-api03-... e deve ser tratada como uma senha: qualquer pessoa que a
possua pode gastar créditos em seu nome.
Boas práticas de segurança
• Nunca cole a chave diretamente no código-fonte. Use variáveis de ambiente (ex.:
ANTHROPIC_API_KEY).
• Nunca faça commit da chave em repositórios Git — utilize arquivos .env e adicione .env ao .gitignore.
• Crie chaves diferentes para cada finalidade (desenvolvimento, produção, testes em grupo) para poder
revogar uma sem afetar as outras.
• Defina limites de gasto no Console para evitar surpresas na fatura durante os testes.
• Revogue imediatamente qualquer chave que tenha sido exposta acidentalmente.
2.3 Modelos Disponíveis e Precificação
A Anthropic organiza seus modelos em famílias, cada uma pensada para um equilíbrio diferente entre
capacidade, velocidade e custo. Como o ritmo de lançamentos é acelerado, o nome do modelo mais
recente muda com frequência — por isso, prefira usar o alias mais atual (ex.: claude-sonnet-5) em vez de
decorar uma versão fixa.
Família Perfil Quando usar
Opus Modelo mais capaz da geração atual Raciocínio complexo, tarefas longas e
ambíguas, agentes autônomos
Sonnet Equilíbrio entre inteligência, velocidade
e custo
Uso geral — é o ponto de partida
recomendado pela própria Anthropic
Haiku Modelo mais rápido e mais barato Alto volume, baixa latência,
classificação e tarefas simples
A cobrança da API é feita por tokens (fragmentos de texto, aproximadamente 4 caracteres em inglês),
contados separadamente para entrada (input) e saída (output) — o output costuma custar mais que o input.
Outros pontos importantes sobre custo:
• Modelos maiores (Opus) custam mais por token que modelos menores (Haiku).
• A Batch API processa requisições de forma assíncrona com desconto sobre o preço padrão — ideal
para grandes volumes sem urgência.
• O Prompt Caching permite reaproveitar partes fixas e longas do prompt (como instruções de sistema)
a um custo reduzido em chamadas repetidas.
Atenção
Os valores exatos por milhão de tokens mudam conforme o modelo e são atualizados
periodicamente pela Anthropic. Consulte sempre a página oficial de preços
(platform.claude.com/docs) antes de orçar um projeto ou definir limites de gasto do grupo.
3. A SDK Oficial (Python e TypeScript/Node.js)
Embora seja possível chamar a API com requisições HTTP puras, a Anthropic mantém SDKs oficiais que já
cuidam de autenticação, formatação de requisições, streaming e tratamento de erros. Isso reduz
drasticamente a quantidade de código repetitivo (boilerplate).
3.1 Instalação
Em Python, o pacote se chama anthropic:
pip install anthropic
Em Node.js/TypeScript, o pacote se chama@anthropic-ai/sdk:
npm install @anthropic-ai/sdk
3.2 Autenticação
Por padrão, a SDK procura automaticamente a variável de ambiente ANTHROPIC_API_KEY — por isso não é
necessário (nem recomendado) passar a chave diretamente no código:
# Linux / macOS
export ANTHROPIC_API_KEY="sk-ant-sua-chave-aqui"
# Windows (PowerShell)
setx ANTHROPIC_API_KEY "sk-ant-sua-chave-aqui"
3.3 Primeira chamada — Python
import anthropic
client = anthropic.Anthropic() # lê a chave da variável de ambiente
resposta = client.messages.create(
model="claude-sonnet-5",
max_tokens=1024,
messages=[
{"role": "user", "content": "Explique o que é uma API em uma frase."}
],
)
for bloco in resposta.content:
if bloco.type == "text":
print(bloco.text)
3.4 Primeira chamada — TypeScript / Node.js
import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic(); // lê ANTHROPIC_API_KEY do ambiente
const resposta = await client.messages.create({
model: "claude-sonnet-5",
max_tokens: 1024,
messages: [
{ role: "user", content: "Explique o que é uma API em uma frase." }
],
});
for (const bloco of resposta.content) {
if (bloco.type === "text") console.log(bloco.text);
}
3.5 Anatomia da requisição
Parâmetro Função
model Identifica qual modelo será usado (ex.: claude-sonnet-5, claude-opus-4-8,
claude-haiku-4-5).
max_tokens Limitemáximo de tokens que o Claude pode gerar na resposta.
messages Lista com o histórico da conversa (role: "user" ou "assistant").
system (Opcional) instruções gerais de comportamento, separadas do histórico de
conversa.
tools (Opcional) lista de ferramentas que o Claude pode chamar — ver Seção 8.
4. Structured Outputs — Respostas em JSON
Por padrão, o Claude responde em linguagem natural — ótimo para conversar, mas problemático quando o
objetivo é integrar a resposta a um sistema que espera um formato previsível, como JSON. "Structured
Outputs" é o nome dado ao conjunto de técnicas que garantem que a resposta do Claude siga exatamente
um esquema (schema) definido por você.
4.1 Por que isso importa
• Elimina a necessidade de fazer parsing frágil de texto livre (regex, tentativa e erro).
• Garante que campos obrigatórios sempre estejam presentes, com o tipo de dado correto.
• Facilita a integração do Claude com bancos de dados, APIs internas e front-ends.
4.2 A técnica mais usada: forçar uma "tool"
Na prática, a forma mais comum e amplamente compatível de obter JSON garantido é definir uma
ferramenta (tool) cujo input_schema descreve exatamente os campos desejados, e então forçar o Claude a
chamá-la usando tool_choice. O Claude nunca "executa" essa ferramenta de verdade — ele apenas
preenche os argumentos no formato do schema, que sua aplicação lê diretamente.
import anthropic
client = anthropic.Anthropic()
schema_extracao = {
"name": "extrair_dados_cliente",
"description": "Extrai dados estruturados de um comentário de cliente.",
"input_schema": {
"type": "object",
"properties": {
"sentimento": {
"type": "string",
"enum": ["positivo", "neutro", "negativo"]
},
"resumo": {"type": "string"},
"urgente": {"type": "boolean"}
},
"required": ["sentimento", "resumo", "urgente"]
}
}
resposta = client.messages.create(
model="claude-sonnet-5",
max_tokens=500,
tools=[schema_extracao],
tool_choice={"type": "tool", "name": "extrair_dados_cliente"},
messages=[{
"role": "user",
"content": "O produto chegou quebrado e o suporte não responde há 3 dias!"
}],
)
dados_json = resposta.content[0].input
print(dados_json)
# {'sentimento': 'negativo', 'resumo': '...', 'urgente': True}
Boa prática
Mantenha o schema o mais simples possível: nomes de campos claros, poucos campos aninhados e
um enum sempre que o valor tiver opções fixas. Isso reduz erros e custo de tokens.
A Anthropic também disponibiliza um recurso mais recente chamado JSON outputs / strict tool use, que
valida o schema com garantias ainda mais fortes diretamente na API (por meio de um parâmetro de
formato de saída e da flag strict em uma tool). Como esse recurso pode exigir cabeçalhos de API específicos
(beta) e nem sempre está disponível em todos os modelos, a técnica de "forçar uma tool" mostrada acima
continua sendo a base mais estável para aprender o conceito — vale a pena consultar a documentação
oficial para saber se o recurso beta já está disponível no modelo que você está usando.
5. Tool Use (Function Calling)
Tool Use — também chamado de Function Calling — é o mecanismo que permite ao Claude ir além de
gerar texto: ele pode decidir chamar uma função da sua aplicação para obter informação externa (o clima
de hoje, um preço no banco de dados) ou executar uma ação (criar uma tarefa, enviar um e-mail).
5.1 O contrato entre aplicação e modelo
É importante entender que o Claude nunca executa código sozinho. O fluxo é sempre:
13. Você define as ferramentas disponíveis (nome, descrição e schema de entrada).
14. O Claude analisa a mensagem do usuário e decide se — e qual — ferramenta deveria ser chamada.
15. O Claude retorna um bloco tool_use com o nome da ferramenta e os argumentos preenchidos.
16. Sua aplicação executa a função de verdade (é o seu código, não o Claude, que roda a lógica).
17. O resultado é devolvido ao Claude em um bloco tool_result, e a conversa continua.
5.2 Exemplo — ferramenta de clima
tools = [{
"name": "obter_clima",
"description": "Retorna a temperatura atual de uma cidade.",
"input_schema": {
"type": "object",
"properties": {
"cidade": {"type": "string", "description": "Nome da cidade, ex: Recife"}
},
"required": ["cidade"]
}
}]
resposta = client.messages.create(
model="claude-sonnet-5",
max_tokens=500,
tools=tools,
messages=[{"role": "user", "content": "Qual é o clima em Recife hoje?"}],
)
if resposta.stop_reason == "tool_use":
chamada = next(b for b in resposta.content if b.type == "tool_use")
print(chamada.name, chamada.input) # obter_clima {'cidade': 'Recife'}
# Aqui você chamaria sua função real de clima com chamada.input['cidade']
5.3 Tool Use x Structured Outputs — qual a diferença?
Conceito Pergunta que resolve Quem executa
Structured Outputs "Como faço o Claude responder num
formato fixo?"
Ninguém— é apenas o
formato da resposta em
texto/JSON.
Tool Use "Como faço o Claude acionar uma ação ou
buscar dado externo?"
Sua aplicação executa a
função de verdade.
Na prática, os dois conceitos se complementam: usar uma tool com tool_choice forçado (Seção 4.2) é, na
verdade, uma aplicação de Tool Use para obter Structured Output — por isso os dois temas aparecem
juntos nesta apostila.
6. Atividades em Grupo
Formato sugerido
Divida a turma em grupos de 3 a 4 pessoas. Cada grupo deve concluir as duas atividades abaixo e
apresentar o resultado (print da chave criada — sem expor o valor completo — e o JSON retornado
pelo script) ao final da aula.
6.1 Atividade 1 — Criar uma API Key compartilhada no Console
18. Acesse console.anthropic.com com a conta do grupo (ou de um representante).
19. Crie (ou selecione) um Workspace exclusivo para o grupo, com um nome identificável (ex.: turma3-
grupoA).
20. Na seção de API Keys, clique em criar nova chave e dê um nome descritivo (ex.: lab-semana3-grupoA).
21. Copie a chave imediatamente — ela só é exibida uma vez — e guarde-a em um cofre de segredos ou
gerenciador de senhas do grupo, nunca em um documento de texto compartilhado publicamente.
22. Configure um limite de gasto (spend limit) baixo, apenas para o exercício, evitando consumo
excessivo de créditos.
23. Compartilhe a chave apenas com os integrantes do grupo, por um canal seguro (nunca em grupos
públicos ou repositórios).
6.2 Atividade 2 — Script que envia uma mensagem e recebe JSON
Objetivo: construir um pequeno script, em Python ou em Node.js, que envie uma mensagem ao modelo
Claude atual (claude-sonnet-5) e obrigue a resposta a vir em formato JSON, usando a técnica de Tool Use
apresentada na Seção 4.2.
Especificação sugerida
• Entrada: uma frase digitada pelo usuário (ex.: uma avaliação de produto ou uma dúvida de suporte).
• Saída esperada em JSON: categoria do assunto, um resumo em uma frase, e um campo booleano
indicando se precisa de atenção humana.
Roteiro do script (Python)
import os, json
import anthropic
client = anthropic.Anthropic()
ferramenta = {
"name": "classificar_mensagem",
"description": "Classifica uma mensagem de usuário.",
"input_schema": {
"type": "object",
"properties": {
"categoria": {"type": "string", "enum": ["suporte", "vendas", "elogio", "outro"]},
"resumo": {"type": "string"},
"precisa_atencao_humana": {"type": "boolean"}
},
"required": ["categoria", "resumo", "precisa_atencao_humana"]
}
}
mensagem_usuario = input("Digite uma mensagem para classificar: ")
resposta = client.messages.create(
model="claude-sonnet-5",
max_tokens=500,
tools=[ferramenta],
tool_choice={"type": "tool", "name": "classificar_mensagem"},
messages=[{"role": "user", "content": mensagem_usuario}],
)
resultado = resposta.content[0].input
print(json.dumps(resultado, indent=2, ensure_ascii=False))
Roteiro do script (Node.js)
import Anthropic from "@anthropic-ai/sdk";
import readline from "node:readline/promises";
const client = new Anthropic();
const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
const ferramenta = {
name: "classificar_mensagem",
description: "Classifica uma mensagem de usuário.",
input_schema: {
type: "object",properties: {
categoria: { type: "string", enum: ["suporte", "vendas", "elogio", "outro"] },
resumo: { type: "string" },
precisa_atencao_humana: { type: "boolean" },
},
required: ["categoria", "resumo", "precisa_atencao_humana"],
},
};
const mensagemUsuario = await rl.question("Digite uma mensagem para classificar: ");
rl.close();
const resposta = await client.messages.create({
model: "claude-sonnet-5",
max_tokens: 500,
tools: [ferramenta],
tool_choice: { type: "tool", name: "classificar_mensagem" },
messages: [{ role: "user", content: mensagemUsuario }],
});
const resultado = resposta.content[0].input;
console.log(JSON.stringify(resultado, null, 2));
Critérios de entrega
• O script roda sem erros e lê a chave a partir de variável de ambiente (não hardcoded).
• A resposta impressa é um JSON válido, seguindo exatamente o schema definido.
• O grupo testa pelo menos 3 mensagens de entrada diferentes e observa se a classificação faz sentido.
• Bônus: tratar erros de API (ex.: chave inválida, limite excedido) com try/except (Python) ou try/catch
(Node.js).
7. Checklist de Fixação e Exercícios
Antes de avançar para a próxima semana, confirme que o grupo consegue responder "sim" para os itens
abaixo:
• Sei explicar a diferença entre usar o Claude pelo chat (claude.ai) e usar o Claude pela API.
• Sei onde criar e onde revogar uma API Key no Console.
• Entendo por que a API é "stateless" e como isso afeta o histórico de conversas.
• Consigo instalar a SDK oficial (Python ou Node.js) e fazer uma chamada simples.
• Sei explicar, com minhas palavras, o que é Structured Output e por que ele é útil.
• Sei explicar, com minhas palavras, o que é Tool Use e por que o Claude nunca executa código sozinho.
7.1 Perguntas para discussão em grupo
24. Em que situações reais (fora da sala de aula) faria sentido usar Tool Use em vez de apenas pedir para
o Claude responder em texto?
25. Por que forçar um formato JSON pode reduzir bugs em um sistema de produção?
26. Quais riscos existem em compartilhar uma única API Key entre várias pessoas do grupo? Como mitigá-
los?
8. Glossário
Termo Significado
Token Unidade de texto usada para medir e cobrar o processamento (aprox. 4
caracteres em inglês).
API Key Credencial secreta usada para autenticar chamadas à API.
Workspace Espaço de trabalho no Console para organizar projetos, chaves e billing.
SDK Software Development Kit — biblioteca oficial que facilita chamadas à API
em uma linguagem específica.
Structured Output Técnica para garantir que a resposta do modelo siga um formato/esquema
definido (ex.: JSON).
Tool Use / Function Calling Mecanismo pelo qual o modelo solicita a execução de uma função definida
pelo desenvolvedor.
Schema (input_schema) Definição formal (em JSON Schema) dos campos e tipos que uma
ferramenta espera receber.
Stateless Característica de uma API que não guarda memória entre chamadas.
Batch API Modalidade assíncrona de envio de requisições em lote, com desconto no
preço.
9. Referências Oficiais
Consulte sempre a documentação oficial para números de preço, nomes de modelo e limites atualizados, já
que esses detalhes mudam com frequência:
• Documentação da API: docs.claude.com e platform.claude.com/docs
• Console / Claude Platform: console.anthropic.com
• Referência de Tool Use: platform.claude.com/docs/en/agents-and-tools/tool-use/overview
• Referência de Structured Outputs: platform.claude.com/docs/en/build-with-claude/structured-
outputs
• Pacote Python: pypi.org/project/anthropic
• Pacote Node.js: npmjs.com/package/@anthropic-ai/sdk
Fim da apostila — Semana 3