> ## 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.

# Construir um Agente

> Construa e publique agentes de IA autônomos usando o Claude Agent SDK e o Replit, com um exemplo passo a passo de automação do Todoist.

export const AiPrompt = ({children}) => {
  return <CodeBlock className="relative block font-sans whitespace-pre-wrap break-words">
      <div className="pr-7">
        {children}
      </div>
    </CodeBlock>;
};

export const YouTubeEmbed = ({videoId, title = "YouTube video", startAt}) => {
  if (!videoId) {
    return null;
  }
  let url = "https://www.youtube.com/embed/" + videoId;
  if (startAt) {
    url = url + "?start=" + startAt;
  }
  return <Frame>
      <iframe src={url} title={title} allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowFullScreen></iframe>
    </Frame>;
};

O [Claude Agent SDK](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/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.

<YouTubeEmbed videoId="jNpH_hOFvg4" title="Construir e publicar um app Claude Agent SDK 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.

## 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](/references/integrations/overview)
* Como publicar seu agente em um agendamento com [Implantações Agendadas](/references/publishing/scheduled-deployments)

## Pré-requisitos

* Uma conta no [Replit](https://replit.com) (plano Core ou Pro recomendado para Implantações)
* Uma [chave de API da Anthropic](https://console.anthropic.com/)
* Uma conta no [Todoist](https://todoist.com) (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.

<Tip>
  Arquiteturas multiagente mantêm cada agente focado. Sub-agentes recebem apenas as ferramentas e o contexto de que precisam, o que evita inchaço de contexto e melhora o desempenho.
</Tip>

### 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

**Servidores MCP** são processos que expõem ferramentas. Todas as descrições de ferramentas são carregadas antecipadamente, tornando-os pesados em contexto. Use servidores MCP para:

* 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

<Info>
  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.
</Info>

### 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

<Steps>
  <Step title="Abrir o template">
    Abra o [template Claude Agent SDK](https://replit.com/@matt/Claude-Agent-SDK) no Replit e selecione **Remix** para criar sua própria cópia.
  </Step>

  <Step title="Nomear seu projeto">
    Dê um nome descritivo (por exemplo, "Meu Agente Todoist") e selecione **Usar template**.
  </Step>

  <Step title="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 SDK
    * `src/agents/` — Definições de agentes
    * `src/mcpServers/` — Configurações de servidores MCP
    * `src/permissions/` — Definições de permissões
    * `src/skills/` — Skills para seus agentes (arquivos Markdown)
    * `src/tools/` — Definições de ferramentas personalizadas
  </Step>
</Steps>

<Tip>
  O template inclui uma Skill que ensina o Replit Agent como construir apps Claude Agent SDK. Isso significa que o Agent já entende o framework quando você faz um prompt para ele.
</Tip>

### 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.

1. Acesse **replit.com/integrations** na sua conta do Replit.
2. Encontre o **Todoist** e conecte sua conta.
3. Autorize o Replit a acessar seus dados do Todoist.

<Info>
  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.
</Info>

### 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.

<AiPrompt>
  Use the Claude Agent SDK skill. Build an agent that looks at my Todoist inbox and organizes my tasks by applying relevant labels or supporting information.

  You should create tools that allow the agent to interact with Todoist using the SDK.

  The result should be an agent that, when triggered, loads all tasks and available projects, polishes them, then organizes them appropriately.

  Be sure to use the Replit Todoist integration for all authentication. Use custom tools with the Todoist REST API rather than the Todoist MCP server, since the MCP server requires OAuth which doesn't work in this context.

  The agent should also fetch a list of projects and assign a relevant project to each item in my inbox, clearing the inbox completely.
</AiPrompt>

<Note>
  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.
</Note>

### Passo 4: Revisar o plano e construir

Quando o Agent apresentar seu plano, verifique se ele inclui:

1. **Ferramentas personalizadas** para a API do Todoist (não o servidor MCP do Todoist)
2. **Um agente organizador** que busca tarefas, etiquetas e projetos
3. **Permissões adequadas** com escopo para as ferramentas que seu agente precisa
4. **Um ponto de entrada** que aciona o fluxo de trabalho

Quando satisfeito, aprove o plano, coloque o Agent em **alta autonomia** e deixe-o construir.

### Passo 5: Adicionar sua chave de API da Anthropic

O Claude Agent SDK requer uma chave de API da Anthropic para chamar o Claude.

1. Abra o painel de **Secrets** no Project Editor.
2. Adicione um segredo chamado `ANTHROPIC_API_KEY` com o valor da sua chave de API.

<Info>
  Se você salvou sua chave de API da Anthropic no [cofre do Replit em Configurações](https://replit.com/settings), ela fica disponível automaticamente em todos os seus projetos.
</Info>

### 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).

<Tip>
  Depurar faz parte de construir com IA. Quando algo não funciona, observe a saída, identifique *o que* o agente fez de forma diferente do esperado e forneça um prompt mais específico. Cada correção ensina o que incluir na próxima vez.
</Tip>

## Publicar seu agente

Depois que seu agente funcionar corretamente, publique-o para ser executado automaticamente.

<Steps>
  <Step title="Abrir a aba Publicar">
    No Project Editor, selecione a aba **Publicar**.
  </Step>

  <Step title="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").
  </Step>

  <Step title="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.
  </Step>

  <Step title="Publicar">
    Selecione **Publicar**. Seu agente está agora ativo e é executado conforme o agendamento.
  </Step>
</Steps>

Para agentes que precisam responder a eventos (webhooks, mensagens recebidas), use uma [Implantação de VM Reservada](/references/publishing/reserved-vm-deployments) em vez disso.

## 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](/references/data-and-storage/sql-database) para armazenar estado entre execuções
* **Armazenar arquivos** — Use o [App Storage](/references/data-and-storage/object-storage) para dados baseados em arquivos
* **Conectar mais serviços** — Adicione mais [Integrações](/references/integrations/overview) (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](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/sdk) para a referência completa da API
* Saiba mais sobre [Agentes e Automações](/references/agent/automations) para construir chatbots e fluxos de trabalho orientados a eventos no Replit
* Leia sobre [Implantações Agendadas](/references/publishing/scheduled-deployments) e [Implantações de VM Reservadas](/references/publishing/reserved-vm-deployments) para opções de implantação
* Confira o [template Claude Agent SDK](https://replit.com/@matt/Claude-Agent-SDK) para começar a construir