O Claude Agent SDK é o Claude Code como biblioteca. Ele permite que você crie programaticamente os mesmos agentes que alimentam o Claude Code e, em seguida, os execute como código. Transforme tarefas repetitivas em fluxos de trabalho automatizados e publique-os no Replit. Neste tutorial, você constrói um agente que organiza uma caixa de entrada do Todoist — buscando tarefas, aplicando etiquetas e ordenando-as em projetos — e depois o publica para ser executado em um agendamento.Documentation Index
Fetch the complete documentation index at: https://docs.replit.com/llms.txt
Use this file to discover all available pages before exploring further.
O que você vai aprender
- Como o Claude Agent SDK funciona e quando usá-lo
- Primitivos principais: agentes, ferramentas, servidores MCP, Skills e permissões
- Como construir um agente de automação de tarefas no Replit usando Integrações
- Como publicar seu agente em um agendamento com Implantações Agendadas
Pré-requisitos
- Uma conta no Replit (plano Core ou Pro recomendado para Implantações)
- Uma chave de API da Anthropic
- Uma conta no Todoist (ou outro serviço que você deseja automatizar)
Como o Claude Agent SDK funciona
Um agente é um loop: você envia um prompt, o agente escolhe as ferramentas a executar, observa os resultados e repete até que a tarefa seja concluída. Você fornece o prompt. O SDK gerencia o loop. Mas o SDK vai além. Ele permite que você construa arquiteturas multiagente onde um agente orquestrador delega tarefas a sub-agentes especializados, cada um com suas próprias ferramentas e janelas de contexto.Primitivos principais
| Primitivo | O que faz |
|---|---|
| Loop de consulta | A base: prompt, escolher ferramentas, executar, observar, repetir |
| Agentes | Configurações especializadas com suas próprias ferramentas e instruções |
| Ferramentas | Ações que os agentes podem tomar — executar comandos, chamar APIs, editar arquivos |
| Servidores MCP | Processos externos que expõem coleções de ferramentas (pesados em contexto, carregados antecipadamente) |
| Skills | Arquivos de instrução em Markdown que ensinam os agentes como fazer as coisas (eficientes em contexto, carregados sob demanda) |
| Permissões | Controles granulares sobre o que cada agente pode acessar e executar |
Skills vs. servidores MCP
Estas são as duas principais formas de estender seus agentes: Skills são arquivos Markdown com instruções que seu agente segue. Apenas uma breve descrição é carregada até ser invocada, mantendo a janela de contexto enxuta. Use Skills para:- Fluxos de trabalho e convenções (“como implantar”, “checklist de revisão de código”)
- Materiais de referência (padrões de API, guias de estilo)
- Prompts reutilizáveis acionados por nome
- Conectar a serviços externos (Notion, Linear, bancos de dados)
- Ações que precisam de acesso à API (criar tarefas, consultar dados)
- Ferramentas que fazem coisas, não apenas instruem
Skills definem como seu agente deve funcionar. Servidores MCP definem o que seu agente pode acessar. Ambos funcionam para agentes de codificação (como o Replit Agent) e agentes que você constrói com o SDK.
Quando usar o SDK vs. a API
| Caso de uso | Escolha |
|---|---|
| Automatizar tarefas de múltiplas etapas | Claude Agent SDK |
| Fluxos de trabalho multiagente | Claude Agent SDK |
| Aplicativos de chat simples | API da Anthropic |
| Tarefas de turno único | API da Anthropic |
Construir um agente organizador do Todoist
Este guia usa um template do Replit que estrutura um projeto Claude Agent SDK com a estrutura correta — diretórios de agentes, ferramentas, servidores MCP, Skills e permissões já no lugar.Passo 1: Remixar o template
Abrir o template
Abra o template Claude Agent SDK no Replit e selecione Remix para criar sua própria cópia.
Nomear seu projeto
Dê um nome descritivo (por exemplo, “Meu Agente Todoist”) e selecione Usar template.
Revisar a estrutura do projeto
Depois que o ambiente carregar, abra a barra lateral de arquivos. Ative Mostrar arquivos ocultos se necessário para ver a estrutura completa:
.agents/skills/— Skills que ensinam o Replit Agent como construir apps Claude Agent SDKsrc/agents/— Definições de agentessrc/mcpServers/— Configurações de servidores MCPsrc/permissions/— Definições de permissõessrc/skills/— Skills para seus agentes (arquivos Markdown)src/tools/— Definições de ferramentas personalizadas
Passo 2: Conectar o Todoist via Replit Integrations
Antes de fazer prompts para o Agent, conecte o serviço com o qual seu agente precisa interagir.- Acesse replit.com/integrations na sua conta do Replit.
- Encontre o Todoist e conecte sua conta.
- Autorize o Replit a acessar seus dados do Todoist.
As Replit Integrations gerenciam o OAuth e a autenticação por você. Seu agente pode acessar a API do Todoist sem gerenciar tokens diretamente. Isso é mais simples do que configurar um servidor MCP separado que requer seu próprio fluxo OAuth.
Passo 3: Fazer prompt para o Agent construir seu agente
Coloque o Replit Agent no Modo de Planejamento para melhores resultados — ele revisa o plano antes de construir, dando a você a chance de verificar a abordagem.Os dois últimos parágrafos deste prompt foram adicionados após a depuração. Ser específico sobre como autenticar (Replit Integrations, não MCP OAuth) e qual deve ser o estado final (caixa de entrada completamente limpa) economiza tempo de iteração.
Passo 4: Revisar o plano e construir
Quando o Agent apresentar seu plano, verifique se ele inclui:- Ferramentas personalizadas para a API do Todoist (não o servidor MCP do Todoist)
- Um agente organizador que busca tarefas, etiquetas e projetos
- Permissões adequadas com escopo para as ferramentas que seu agente precisa
- Um ponto de entrada que aciona o fluxo de trabalho
Passo 5: Adicionar sua chave de API da Anthropic
O Claude Agent SDK requer uma chave de API da Anthropic para chamar o Claude.- Abra o painel de Secrets no Project Editor.
- Adicione um segredo chamado
ANTHROPIC_API_KEYcom o valor da sua chave de API.
Se você salvou sua chave de API da Anthropic no cofre do Replit em Configurações, ela fica disponível automaticamente em todos os seus projetos.
Passo 6: Testar e depurar
Execute o agente e verifique se ele processa sua caixa de entrada do Todoist corretamente. Problemas comuns a observar:- “Caixa de entrada está vazia” quando não está — O formato de resposta da API para detectar tarefas da caixa de entrada pode precisar de ajuste. Verifique se o agente filtra tarefas pelo projeto da caixa de entrada, não por uma propriedade diferente.
- Tarefas recebem etiquetas mas não se movem para projetos — Seja explícito no seu prompt de que o agente deve buscar projetos disponíveis e atribuir cada tarefa a um.
- Erros de autenticação — Verifique se a integração do Todoist está conectada no Replit Integrations e que o código do seu agente a usa (não um fluxo OAuth separado).
Publicar seu agente
Depois que seu agente funcionar corretamente, publique-o para ser executado automaticamente.Escolher Implantação Agendada
Selecione Implantação Agendada para automação baseada em tempo. Digite o agendamento desejado (por exemplo, “Todos os dias às 17h PST”).
Verificar a configuração
Confirme que o comando de execução aponta para seu arquivo de ponto de entrada principal e que seu segredo
ANTHROPIC_API_KEY está incluído nos segredos de implantação.Estender seu agente
Uma vez que o básico funcione, você pode construir agentes mais sofisticados no Replit:- Adicionar memória persistente — Use o Replit Database para armazenar estado entre execuções
- Armazenar arquivos — Use o App Storage para dados baseados em arquivos
- Conectar mais serviços — Adicione mais Integrações (Slack, Linear, GitHub, Notion) para fluxos de trabalho com múltiplos serviços
- Usar Skills — Adicione arquivos de Skill em Markdown para dar aos seus agentes conhecimento e instruções especializados
Próximos passos
- Explore a documentação do Claude Agent SDK para a referência completa da API
- Saiba mais sobre Agentes e Automações para construir chatbots e fluxos de trabalho orientados a eventos no Replit
- Leia sobre Implantações Agendadas e Implantações de VM Reservadas para opções de implantação
- Confira o template Claude Agent SDK para começar a construir