Construindo um Agente de IA Personalizado com o SDK da Anthropic
A primeira vez que eu entendi o que "agente" realmente significava — não a versão de marketing, não o termo da moda na landing page de toda startup — eu estava há três horas mergulhado na documentação do Agent SDK da Anthropic, às 23h de uma terça-feira. Meu café já tinha esfriado. Eu tinha dezessete abas abertas no navegador. Minha IDE tinha um ambiente Python meio montado que ainda não estava cooperando.
E eu ficava pensando: isso aqui é realmente diferente.
Eu estava cético ao começar. Já tinha visto demos demais de "agentes de IA" que eram chatbots glorificados com um wrapper de ferramenta por cima. Impressionante numa demo controlada. Inútil em produção. Mas a arquitetura que a Anthropic construiu aqui — a forma como gerencia o loop de controle, lida com o contexto da conversa automaticamente e dá aos desenvolvedores acesso ao mesmo conjunto de ferramentas nativas que o próprio Claude Code utiliza — não era aquilo. Era algo significativamente diferente.
Passei a semana seguinte construindo um agente de IA pessoal que vou chamar de Luna. Ela se integra com Slack, Gmail, Notion, Chartmogul e App Store Connect. Tem um sistema de memória em três camadas. Executa resumos matinais programados e envia notificações push com itens de ação para o meu celular antes de eu abrir o laptop. É lenta — consultas complexas levam de 1 a 2 minutos — mas é minuciosa de um jeito que nenhuma resposta rápida de chatbot consegue igualar.
Este post cobre tudo que aprendi. Incluindo o problema de custo que genuinamente me preocupou, o erro arquitetural que cometi no início e que me custou quatro dias de retrabalho, e por que eu acho que o Anthropic Agent SDK é a coisa mais significativa que a Anthropic lançou para desenvolvedores desde o próprio Claude.
Antes de entrarmos em como construir isso, quero deixar algo registrado aqui: o maior erro que a maioria dos desenvolvedores comete ao construir agentes não é técnico. É um erro de design. Vou explicar exatamente qual é — e por que ele desperdiça semanas — assim que tivermos a base no lugar.
O Que um Agente Realmente É (Tirando o Termo da Moda)
Toda empresa afirma ter agentes agora. A maioria está sendo bem generosa com a definição. Um agente real tem exatamente três componentes. Entendê-los com precisão é o que separa agentes funcionais de chatbots caros.
Componente um: um LLM. Claude, GPT-4, o que você estiver usando. O LLM é o motor de raciocínio. Ele lê o contexto, decide o que fazer em seguida e gera texto. Só isso. Ele não consegue executar nada sozinho. Não consegue chamar APIs. Não consegue ler arquivos. Ele pensa. Nada mais.
Componente dois: ferramentas. Funções que o LLM pode invocar. Uma ferramenta pode ser "ler esta thread do Gmail", "consultar este banco de dados do Notion" ou "executar este comando bash". O LLM não executa essas funções — ele as solicita em um formato estruturado, seu sistema as executa e os resultados retornam ao LLM como novo contexto.
Componente três: o loop. Depois que o LLM chama uma ferramenta e recebe os resultados, ele avalia esses resultados e decide o que fazer em seguida. Outra chamada de ferramenta? Uma consulta complementar? Uma resposta final? Esse loop continua até a tarefa ser concluída. É isso que faz algo ser um agente em vez de um chatbot. Sem o loop, você tem um chamador de ferramentas de uma única vez. Com o loop, você tem algo que consegue raciocinar ao longo de dezenas de etapas.
Cometi o erro logo no início de equiparar "mais ferramentas" com "agente mais inteligente". É exatamente o oposto. A inteligência está no loop. Um loop bem estruturado com cinco ferramentas focadas supera um loop caótico com cinquenta. Sempre. Eu reconstruí a configuração de ferramentas da Luna duas vezes antes de internalizar isso.
Essa distinção importa para o que vem a seguir — porque o Anthropic Agent SDK é fundamentalmente um gerenciador de loop. Tudo que ele faz serve ao loop: torná-lo confiável, eficiente e mais fácil de construir sem escrever centenas de linhas de código boilerplate.
O Que o SDK Realmente Faz Que Nada Mais Faz Tão Bem
Antes deste SDK existir, construir o loop significava escrever boilerplate manualmente: gerenciamento de histórico de conversa, parsing de chamadas de ferramentas, formatação de resultados, handlers de streaming, lógica de retry. Nada disso é complicado individualmente. Combinado, são várias centenas de linhas de código que cada desenvolvedor de agentes escrevia de um jeito ligeiramente diferente, o que tornava as bases de código de agentes difíceis de manter ou estender.
O SDK condensa tudo isso em gerenciamento baseado em sessões. Você inicializa uma sessão com um ID, o SDK rastreia a conversa e o Claude recebe o contexto correto automaticamente a cada turno. Quando testei pela primeira vez, esperava fragilidade — gerenciamento de estado "automático" em ferramentas para desenvolvedores geralmente significa que funciona até misteriosamente parar de funcionar. Mas depois de rodar sessões de várias horas com a Luna executando dezenas de chamadas de ferramentas sequenciais, não encontrei um problema de consistência de contexto.
O recurso de auto-compactação me convenceu de vez. Quando uma conversa cresce o suficiente para se aproximar do limite de contexto do Claude, o SDK automaticamente resume partes mais antigas da conversa e as comprime. Sem erros. Sem truncamento. Sem intervenção manual. Para a Luna, onde uma única sessão de workflow pode envolver a leitura de vinte emails, a consulta a três bancos de dados e a extração de métricas de negócio — isso não é opcional. Sem esse recurso, tarefas complexas falhariam no meio da execução ao atingir o limite. Com ele, o agente continua raciocinando sem interrupção.
Mas aqui está o que eu não antecipei: o SDK dá ao seu agente acesso ao conjunto real de ferramentas nativas do Claude Code. Não uma versão simplificada. As mesmas ferramentas.
As Ferramentas Nativas: Mais Poderosas do Que a Documentação Sugere
As ferramentas nativas do Claude Code são de nível de produção: execução de bash, leitura e escrita de arquivos, grep e glob para correspondência de padrões, busca web otimizada e web scraping. Quando você usa o Anthropic Agent SDK, seu agente obtém acesso a essas mesmas ferramentas por padrão.
Deixe-me ser específico sobre o que isso significa: seu agente pode executar comandos shell, ler e escrever arquivos no sistema de arquivos, buscar informações atuais na web e fazer scraping de conteúdo de qualquer URL pública. Isso não é funcionalidade de brinquedo. É o mesmo conjunto de ferramentas que o Claude Code usa quando ajuda desenvolvedores a escrever software de produção.
Para a Luna, isso eliminou três integrações personalizadas que eu estava planejando construir. Só a capacidade de web scraping substituiu 200 linhas de código personalizado que eu havia escrito para um projeto anterior. Deletei esse código em menos de 24 horas depois de configurar o SDK.
Aqui é onde preciso sinalizar a ressalva — porque levei um dia inteiro para aprender direito. Execução de bash em um agente é uma fronteira de confiança. Um agente com acesso irrestrito ao bash pode fazer qualquer coisa que sua conta de usuário pode fazer: deletar arquivos, fazer requisições de rede de saída, instalar pacotes globalmente, modificar configurações do sistema. Meu primeiro protótipo da Luna, em uma sessão de teste, decidiu instalar uma biblioteca Python faltante via pip install globalmente porque precisava daquela biblioteca para completar uma tarefa que eu havia dado a ela. Ela não estava errada sobre a abordagem funcionar. Mas um agente automatizado rodando no meu laptop não deveria fazer mudanças globais de pacotes sem permissão explícita.
Esse é o erro de design que mencionei na abertura — e ele se aplica muito além do acesso ao bash. A maioria dos desenvolvedores dá ao agente permissões máximas porque é mais simples de configurar. Depois ficam surpresos quando o agente faz coisas inesperadas. Defina o escopo das suas ferramentas exatamente para o que o agente precisa para realizar suas tarefas definidas. Nada mais. Essa decisão deve acontecer antes de você escrever uma única linha de código de implementação.
O Sistema de Skills: Como Você Escala Sem Quebrar Tudo
Conforme um agente acumula capacidades, ele esbarra em um problema fundamental de escalabilidade: mais ferramentas no contexto significa maior custo de tokens e raciocínio mais lento. Um agente ciente de cinquenta ferramentas é mais caro por requisição do que um que conhece cinco — mesmo que ele só use três delas.
O sistema de skills resolve isso de forma limpa. Uma skill é uma capacidade modular definida como uma pasta contendo um arquivo de metadados e instruções em markdown. Os metadados descrevem o que a skill faz em linguagem simples. O agente lê as descrições das skills para determinar quais são relevantes para a tarefa atual e então carrega apenas essas. Isso é divulgação progressiva — o agente revela capacidades para si mesmo seletivamente, com base no contexto da tarefa, em vez de carregar tudo de uma vez.
Para a Luna, tenho oito skills configuradas: Gmail, Slack, Notion, Chartmogul, App Store Connect, notificações push, gerenciamento de arquivos e pesquisa web. Em uma sessão típica de resumo matinal, três skills são ativadas. As outras cinco permanecem dormentes. Antes de mudar para essa arquitetura, cada sessão carregava todos os oito contextos de skills. Depois da mudança, a latência das requisições caiu de 30 a 40% e meu uso mensal de tokens diminuiu visivelmente.
O arquivo de metadados da skill é simples, mas importante de acertar:
# Gmail Skill
## Description
Search, read, and analyze Gmail messages. Use when the user needs to check email,
find specific messages, or review communication threads.
## When to activate
- User asks about emails or messages
- Task requires checking inbox for updates
- User mentions checking communication or correspondence
## Capabilities
- Search Gmail with query syntax
- Read full email threads
- Extract sender, subject, date, and body content
- Identify urgency signals in messages
A descrição é o que o agente lê para decidir a relevância. Escreva-a da perspectiva do agente, não do desenvolvedor. Se a descrição não comunicar claramente quando usar a skill, o agente vai ativá-la demais ou ignorá-la quando necessário.
Aqui é onde o sistema de skills fica particularmente poderoso: ele se conecta diretamente à arquitetura de memória. A combinação de skills enxutas e sob demanda com uma camada de memória persistente é o que faz um agente pessoal parecer genuinamente personalizado, em vez de genérico e resetado a cada sessão.
Construindo Seu Primeiro Agente: A Implementação Real
Vou apresentar a estrutura central. Está simplificada, mas arquiteturalmente precisa — suficiente para você entender o que está construindo antes de começar.
import anthropic
from anthropic import Anthropic
client = Anthropic()
# Define your tools as structured schemas
tools = [
{
"name": "search_gmail",
"description": "Search Gmail for emails matching a query. Returns sender, subject, date, and body preview.",
"input_schema": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Gmail search query (supports standard Gmail operators)"
},
"max_results": {
"type": "integer",
"description": "Maximum number of results to return. Default: 10"
}
},
"required": ["query"]
}
},
{
"name": "get_slack_messages",
"description": "Retrieve recent messages from a specified Slack channel.",
"input_schema": {
"type": "object",
"properties": {
"channel": {
"type": "string",
"description": "Slack channel name or ID"
},
"hours": {
"type": "integer",
"description": "How many hours back to retrieve messages"
}
},
"required": ["channel"]
}
}
]
def run_agent_loop(session_id: str, user_message: str, conversation_history: list):
"""Core agent loop: think → tool call → result → repeat until done."""
messages = conversation_history + [{"role": "user", "content": user_message}]
while True:
response = client.messages.create(
model="claude-opus-4-6",
max_tokens=4096,
tools=tools,
messages=messages
)
# Agent has reached a final answer
if response.stop_reason == "end_turn":
final_text = next(
(block.text for block in response.content if hasattr(block, "text")),
""
)
return final_text, messages
# Agent wants to call one or more tools
if response.stop_reason == "tool_use":
tool_results = []
for block in response.content:
if block.type == "tool_use":
# Execute the requested tool
result = execute_tool(block.name, block.input)
tool_results.append({
"type": "tool_result",
"tool_use_id": block.id,
"content": str(result)
})
# Append agent's response and tool results, continue loop
messages.append({"role": "assistant", "content": response.content})
messages.append({"role": "user", "content": tool_results})
A função execute_tool é onde ficam suas integrações reais. Chamadas à API do Gmail. Consultas ao Notion. Extração de métricas do Chartmogul. O agente não sabe nem se importa com o funcionamento interno dessas integrações — ele só vê os resultados.
Uma dica profissional que vale destacar: retorne dados estruturados e amigáveis para o agente nas suas ferramentas, não respostas brutas de API. Se sua ferramenta de Gmail retorna "Encontrados 3 emails urgentes: (1) De: [email protected], Assunto: Problema de Pagamento, Data: Hoje 9:14, Prévia: 'Não recebemos a fatura...'" — o agente raciocina sobre isso imediatamente. Se retorna JSON bruto com 40 campos que o agente precisa parsear, você está queimando tokens com parsing que a ferramenta deveria resolver. Suas ferramentas devem fazer o trabalho pesado para que o agente possa focar no raciocínio.
Certo — se você chegou até aqui, já entende a arquitetura central melhor do que a maioria dos desenvolvedores que começam a construir agentes. A próxima parte é onde fica genuinamente poderoso.
Memória Que Realmente Funciona: A Arquitetura de Três Camadas
Agentes padrão têm memória de peixe dourado. Cada sessão começa do zero. O agente não sabe que você prefere checklists do Notion em vez de listas com marcadores. Não se lembra que você sempre quer mensagens urgentes de clientes em destaque primeiro. Não conhece a convenção de nomenclatura que você usa para arquivos de projeto.
Para tarefas pontuais, tudo bem. Para um assistente pessoal que deveria lidar com seu fluxo de trabalho matinal, é inadmissível.
A arquitetura de três camadas que construí para a Luna:
Memória de sessão é o contexto da conversa atual — gerenciado automaticamente pelo SDK. Nada para construir aqui. Simplesmente funciona.
Memória persistente é a camada interessante. Ela armazena fatos que o agente decide que valem a pena manter: suas preferências, padrões recorrentes, correções ao seu próprio comportamento. "Mejba prefere resumos diários formatados como listas de ação priorizadas, não resumos narrativos." "Sempre verifique o canal do App Store Connect no Slack antes de sinalizar problemas da App Store — geralmente tem contexto lá." "O relatório padrão do Chartmogul deve incluir MRR, taxa de churn e contagem de novos clientes."
O comportamento chave aqui: o agente salva essas informações proativamente. Não espera você dizer "lembre disso". Ele identifica informações que valem a pena manter durante interações normais e as grava na memória com uma nota sobre o motivo. Depois de duas semanas com a Luna, ela tinha noventa e três entradas de memória persistente. Minhas interações parecem personalizadas porque ela realmente aprendeu meus padrões.
Memória de arquivo lida com material de referência em volume — documentação de projetos, transcrições de conversas passadas, arquivos de referência grandes demais para carregar no contexto diretamente. Recuperada por busca semântica: a Luna consulta o arquivo com uma descrição do que precisa, e os trechos relevantes retornam. Nunca é carregado por inteiro.
Para o backend de armazenamento, avaliei Firebase, Supabase e Convex. Escolhi o Convex por um motivo específico: sincronização em tempo real. Quando a Luna executa uma ação que aparece no meu iPhone — uma notificação push, um resumo matinal — o fluxo de dados é: ação do agente → Convex → serviço de notificação → celular. Com backends baseados em polling, há atrasos incômodos. Com as assinaturas em tempo real do Convex, é instantâneo. O Convex também lida com cron jobs nativamente, que é o que alimenta o fluxo de trabalho matinal programado da Luna.
Deploy: A Decisão Que a Maioria dos Tutoriais Ignora
Onde seu agente realmente vive? Essa pergunta tem mais peso arquitetural do que parece à primeira vista.
Deploy local dá acesso completo à sua máquina. Para integração com iMessage — que não tem API oficial e só pode ser acessado via AppleScript no macOS — execução local é a única opção. A contrapartida: seu agente só roda quando seu laptop está ligado e conectado. Fluxos de trabalho programados falham no momento em que a tampa fecha.
Um VPS roda 24/7 e lida com qualquer integração acessível na nuvem de forma limpa: Gmail, Slack, Notion, Chartmogul, App Store Connect. Mas um VPS não pode rodar AppleScript. Não consegue acessar iMessage ou outras ferramentas exclusivas do Mac.
A Luna usa uma arquitetura dividida. Um VPS lida com fluxos de trabalho programados e todas as integrações de plataformas na nuvem. A execução local lida com tudo que é específico do Mac. O Convex sincroniza o estado entre os dois ambientes em tempo real, então da perspectiva do usuário parece um agente contínuo, independentemente de qual máquina está executando a tarefa atual.
A parte não resolvida — e quero ser honesto sobre isso — é a autenticação para deploy multi-usuário. Armazenar chaves de API para uso pessoal é direto: variáveis de ambiente, criptografadas em repouso, pronto. Tornar essas chaves disponíveis com segurança para usuários de um produto que você está distribuindo é um problema genuinamente difícil. A abordagem ingênua (credenciais em um banco de dados compartilhado) cria exposição de segurança. A abordagem correta (OAuth por usuário com isolamento adequado de credenciais) adiciona semanas de trabalho de engenharia que a maioria dos tutoriais de agentes não menciona porque não estão construindo produtos, estão construindo demos.
Qualquer pessoa planejando lançar um produto de agente deveria reservar de 2 a 3 vezes mais tempo para a arquitetura de autenticação do que inicialmente estima.
A Realidade de Custos Que Ninguém Quer Calcular
Nos preços atuais da API da Anthropic, um agente pessoal ativo usando Claude Opus 4.6 com múltiplas sessões diárias e fluxos de trabalho complexos com múltiplas ferramentas custa aproximadamente $200 a $400 por mês em custos de API. Isso antes dos custos de VPS, banco de dados e taxas de APIs de terceiros.
Compare com uma assinatura Claude Pro a $20/mês. Para um consumidor que está obtendo resultados apenas ligeiramente melhores de um agente personalizado do que de uma assinatura Claude Pro, a conta não fecha. Não fecha de jeito nenhum.
Isso não significa que produtos de agentes são inviáveis. Significa que atualmente são produtos B2B — casos em que o custo do agente é pequeno comparado ao valor que ele gera. Prestei consultoria para um agente de auditoria de conformidade HIPAA que custa de $50 a $100 por relatório em chamadas de API, mas identifica falhas de conformidade que custariam de $10.000 a $50.000 em tempo de engenharia para identificar manualmente. Essa conta fecha. Um agente de suporte ao cliente que lida autonomamente com 80% dos tickets de nível 1, reduzindo o custo de pessoal em $15.000/mês — essa conta fecha.
Para uso pessoal com os planos de assinatura da Anthropic: a cota de tokens cobre um uso razoável de agente pessoal. A Luna, rodando meus fluxos de trabalho diários, fica bem dentro dos limites da assinatura. O problema surge apenas se você quiser oferecer seu agente como produto, já que os benefícios da assinatura não são transferíveis para seus usuários. No momento em que você quer atender usuários externos, está na cobrança por API.
Opinião honesta: construí a Luna para uso pessoal, subsidiada pela minha assinatura. A experiência é genuinamente excelente. Se eu quisesse produtizar a Luna e cobrar consumidores $15/mês pelo acesso, a economia unitária ainda não funciona. Vou revisitar isso em 18 meses conforme a eficiência dos modelos continua melhorando.
Produtos de agentes para consumidores exigem ou LLMs locais (ainda intensivos em recursos e não capazes o suficiente para tarefas complexas multiplataforma) ou paciência para as curvas de preço caírem mais. Ambos estão chegando. Nenhum dos dois é uma estratégia de lançamento viável hoje.
O Que Realmente Muda Quando Você Constrói Isso Direito
Sou deliberadamente cuidadoso com alegações de produtividade porque a maioria é inflada. Então vou dar números específicos do meu próprio fluxo de trabalho.
Antes da Luna: 45 a 60 minutos toda manhã revisando o Slack, varrendo o Gmail, puxando métricas do Chartmogul e verificando notificações do App Store Connect. O tempo não era gasto em nenhuma plataforma específica — era gasto na troca de contexto entre todas elas. Cada troca carrega sobrecarga cognitiva: reentrar no contexto mental daquela plataforma, descobrir o que precisa de atenção, decidir o que pode esperar.
Depois da Luna: 8 a 12 minutos. O resumo matinal da Luna chega como uma notificação push antes de eu abrir o laptop. Dois itens precisam de atenção imediata. Cinco precisam de resposta no mesmo dia. Todo o resto está catalogado e disponível se eu precisar. Abro meu laptop sabendo exatamente onde investir minha primeira hora.
São 35 a 50 minutos recuperados diariamente. Em um mês de trabalho, aproximadamente 15 horas. Uso essas horas construindo coisas.
O tempo de resposta de 1 a 2 minutos da Luna para consultas complexas é a verdadeira contrapartida — e quero deixar claro que é uma contrapartida genuína, não um inconveniente menor. Para perguntas factuais rápidas, o tempo de resposta é frustrante. Mas para as tarefas que a Luna realmente lida, a profundidade justifica. Quando peço para ela identificar comunicações urgentes em cinco plataformas, ela genuinamente verifica todas as cinco, aplica lógica de relevância e sintetiza o resultado. Um agente mais rápido mas mais raso exigiria que eu verificasse suas conclusões, o que anula o propósito.
O padrão que vale internalizar: construa agentes rápidos para tarefas de alta frequência e baixa complexidade. Construa agentes minuciosos para tarefas de baixa frequência e alta complexidade. A Luna é otimizada para o último caso. Tentar torná-la rápida a tornaria rasa, e raso anula o propósito.
O Que Vem a Seguir Para Esta Arquitetura
Sub-agentes são a próxima iteração que estou ativamente projetando. A arquitetura atual da Luna é um agente único com múltiplas ferramentas. A próxima versão roda agentes especialistas — um focado puramente em email e comunicação, outro em métricas de negócio, outro em gerenciamento de projetos — coordenados por um agente orquestrador principal que delega trabalho e sintetiza resultados.
Isso espelha como equipes eficazes funcionam. Especialistas para domínios específicos. Um coordenador que é dono da síntese e sabe qual especialista consultar. Nenhuma pessoa tentando ser especialista em tudo simultaneamente. O mesmo princípio escala de forma limpa para agentes.
Streaming é a melhoria de experiência que mais me empolga para implementar. Agora, a Luna espera até ter uma resposta completa antes de retornar qualquer coisa. Streaming mostraria seu raciocínio em tempo real — você veria chamadas de ferramentas acontecendo, resultados intermediários se acumulando, o processo de decisão se desenrolando. Para tarefas de 2 minutos, assistir um agente trabalhando ativamente é dramaticamente melhor do que observar um spinner de progresso.
Controle direto do computador fecha a última grande lacuna. Agora, qualquer plataforma sem API está fora do alcance da Luna. Com controle do computador, essa restrição desaparece — o agente interage com qualquer interface, não apenas as que expõem acesso programático.
Aqui é onde te deixo — e este é um desafio genuíno, não um recurso retórico:
Pense em um fluxo de trabalho na sua rotina diária atual que exige três ou mais etapas manuais em diferentes plataformas. Não um fluxo de trabalho hipotético futuro. Algo que você faz esta semana. Talvez seja a rotina de preparação antes da sua daily de segunda-feira. Talvez seja um processo de relatório semanal que envolve puxar dados de duas ferramentas e formatá-los para uma terceira. Talvez seja algo específico da sua indústria.
Esse é o seu primeiro agente. Não uma grande visão. Não uma jogada de plataforma. Um fluxo de trabalho delimitado e específico com entradas acessíveis por API e uma definição clara de "concluído".
Construa isso. Faça funcionar. Meça quanto tempo economiza. Depois expanda.
O Anthropic Agent SDK está pronto. A arquitetura que descrevi — o loop, o sistema de skills, a memória de três camadas, o deploy dividido — pode ser construída por um único desenvolvedor em duas a três semanas focadas. A infraestrutura existe. As ferramentas são reais.
Qual é o fluxo de trabalho que você vai construir primeiro?
Vamos Trabalhar Juntos
Quer construir sistemas de IA, automatizar fluxos de trabalho ou escalar sua infraestrutura de tecnologia? Adoraria ajudar.
- Fiverr (builds e integrações personalizadas): fiverr.com/s/EgxYmWD
- Portfólio: mejba.me
- Ramlit Limited (soluções empresariais): ramlit.com
- ColorPark (design e branding): colorpark.io
- xCyberSecurity (serviços de segurança): xcybersecurity.io
