Claude Agent SDK: o que é e como ferramentas, Skills e instruções se encaixam

O Claude Agent SDK é o kit de desenvolvimento que a Anthropic oferece para construir agentes de inteligência artificial: programas em que o modelo não se limita a responder, mas executa tarefas de várias etapas usando ferramentas. A estrutura se resume a três peças que se conectam — ferramentas, Skills e instruções — e entender esse encaixe é o que separa construir um agente de construir um chatbot com nome diferente.

A comparação com peças de LEGO

Uso LEGO para explicar isso porque a analogia acerta a parte difícil: as peças são poucas e genéricas, e o que você constrói depende inteiramente de como encaixa.

As ferramentas são as peças. Cada uma dá ao agente uma capacidade concreta: ler um arquivo, consultar uma API, rodar um comando, buscar na web, gravar no banco. Sem ferramentas, o modelo só sabe produzir texto sobre o trabalho. Com ferramentas, ele faz o trabalho.

As Skills são as instruções de montagem. Elas descrevem como executar uma tarefa do seu jeito, no seu contexto, com os seus critérios — e ficam guardadas para serem carregadas automaticamente quando aquela tarefa aparecer. A diferença entre ferramenta e Skill é a diferença entre poder e saber: a ferramenta define o que o agente consegue fazer, a Skill define como fazer bem aqui.

As instruções são o projeto. São o que estabelece o objetivo, os limites, o que nunca deve acontecer e o que exige confirmação antes de prosseguir. É a camada em que você diz não apenas o que construir, mas o que não derrubar no caminho.

A razão de a analogia funcionar é que nenhuma dessas peças é interessante isolada. Ferramenta sem instrução é um agente que age sem critério. Instrução sem ferramenta é um agente que opina sem agir. Skill sem as duas é documentação que ninguém lê.

Um exemplo concreto: análise de site

Peguei um caso real para mostrar o encaixe, porque em abstrato isso tudo soa igual a qualquer outra coisa.

A tarefa é analisar um site e devolver um diagnóstico. Um chatbot, perguntado sobre isso, devolve uma lista genérica de boas práticas — exatamente o tipo de resposta que não ajuda ninguém. Um agente faz outra coisa.

Ele busca as páginas de verdade, usando a ferramenta de acesso à web. Lê o conteúdo e a estrutura de cada uma. Mede o que é mensurável em vez de supor: tempo de carregamento, tamanho das imagens, presença dos metadados, dados estruturados, encadeamento dos títulos. Compara com o critério definido na Skill, que é onde vive o meu padrão de avaliação e não um padrão genérico da internet. E então organiza o achado em etapas, da descoberta ao que fazer a respeito.

Em nenhum momento dessa sequência ele inventou um número. Cada afirmação do relatório final tem uma observação por trás, feita por uma ferramenta, sobre a página real.

O ponto em que ele para e pergunta

A parte do desenho que considero mais importante é também a mais fácil de esquecer: onde o agente interrompe e espera.

Analisar é leitura. Leitura não quebra nada, e o agente pode seguir sozinho. Mas no momento em que a próxima ação tem consequência — alterar um arquivo, publicar uma página, disparar um e-mail, gastar dinheiro — o comportamento correto não é continuar com confiança. É apresentar o que pretende fazer e esperar a aprovação.

Isso não é um freio por desconfiança do modelo. É o que torna a delegação utilizável. Um agente que executa tudo sozinho exige que você revise depois, quando a ação já aconteceu e o custo de desfazer é alto. Um agente que para nos pontos certos permite revisar antes, quando mudar de rumo ainda é barato.

Delegar o trabalho sem delegar a decisão: é essa a linha.

Por que isso muda o tipo de tarefa que vale automatizar

A consequência prática aparece na escolha do que entregar a uma máquina.

Automação tradicional exige que o caminho seja conhecido de antemão: você descreve cada passo, cada condição, cada exceção. Isso funciona bem para processos estáveis e repetitivos, e funciona muito mal para tarefas em que o caminho depende do que se descobre no meio.

Um agente ocupa justamente essa segunda faixa. Ele é adequado quando o objetivo é claro mas o percurso não: investigar por que algo está acontecendo, revisar material contra um critério, levantar informação espalhada em vários lugares, preparar uma proposta de mudança para alguém aprovar. Tarefas em que a próxima ação só é decidível depois de observar o resultado da anterior.

É também por isso que a pergunta certa não é “o que a IA pode fazer”, e sim “qual tarefa minha tem objetivo claro, percurso variável e um ponto natural de aprovação”. Essa é a tarefa que vale virar agente primeiro.

---

Se você quer a camada de baixo antes de construir, escrevi sobre o loop de planejar, agir e observar, que é o mecanismo que o SDK embala, e sobre context engineering, que decide o que entra no modelo a cada etapa. Para o problema de o agente lembrar entre sessões, há memória de agentes. E se a discussão na sua empresa já é qual processo vira agente primeiro, é o tipo de conversa que conduzo em consultoria de inteligência artificial — o contato é o caminho direto.