Como usar Cursor Agent SDK para criar agentes

Este guia é para quem quer criar um agente especializado, por exemplo, para revisar mudanças ou organizar uma tarefa repetitiva. Não é um tutorial sobre instalar o editor Cursor nem sobre construir um agente autônomo sem limites.

Como usar Cursor Agent SDK começa com uma tarefa delimitada

Escolha uma tarefa repetitiva, com entradas e saídas claras. Um agente de revisão pode receber um diff e apontar problemas de estilo ou riscos para a pessoa verificar, sem fazer merge automaticamente.

A documentação oficial do Cursor Agent SDK descreve agentes definidos como código. As instruções podem ficar em Markdown, as ferramentas podem ser implementadas em TypeScript e as avaliações ajudam a medir mudanças de comportamento.

O anúncio oficial apresenta duas opções de implantação: usar a infraestrutura hospedada da Cursor ou executar o agente na sua própria infraestrutura. Isso não significa que os ambientes tenham requisitos idênticos. Confira a documentação antes de decidir onde o agente deve acessar dados.

Antes de criar um agente, defina o limite de ação

Escreva qual é a tarefa, quem inicia o agente e o que ele pode ler. Defina também o que ele pode alterar e quais ações sempre precisam de confirmação humana.

Comece com acesso somente de leitura. Se o agente precisa abrir um pull request ou alterar arquivos, conceda essa permissão depois de testar o fluxo básico.

Não passe credenciais de produção no prompt nem deixe segredos em arquivos de instrução. Armazene credenciais conforme o ambiente de execução e limite cada ferramenta ao que realmente precisa fazer.

Passo 1: escreva instruções curtas em Markdown

Separe o papel do agente das regras do projeto. O papel diz o que ele deve entregar; as regras dizem como interpretar entradas, quais caminhos evitar e quando pedir ajuda.

Um arquivo de instruções pode especificar: objetivo, formato de entrada, formato de saída, critérios de sucesso, limites de acesso e casos que exigem escalonamento. Use exemplos curtos para mostrar a diferença entre uma resposta correta e uma resposta incompleta.

Evite instruções vagas como “revise bem o código”. Prefira “aponte arquivos e linhas afetados, explique o risco e sugira uma correção, sem editar arquivos nem aprovar a mudança”.

Passo 2: crie ferramentas TypeScript com permissões mínimas

Cada ferramenta precisa fazer uma ação pequena e previsível. Por exemplo, uma ferramenta pode consultar o diff de uma mudança e retornar apenas os arquivos alterados, enquanto outra verifica o resultado dos testes.

Valide a entrada antes de executar uma ação. Rejeite caminhos fora do repositório, limite o tamanho dos dados e trate respostas vazias ou erros de serviços externos.

Mantenha leitura e escrita separadas. Uma ferramenta que analisa um pull request não precisa, por padrão, da capacidade de aprová-lo ou publicá-lo.

Passo 3: avalie o agente com casos que podem falhar

O SDK inclui avaliações para medir mudanças no comportamento do agente. Crie exemplos que representem tanto o caminho esperado quanto situações incompletas, como um diff vazio, um teste que falhou ou instruções conflitantes.

Para um revisor de código, verifique se ele identifica um problema real, evita inventar arquivos e distingue uma sugestão de uma falha confirmada. Inclua casos em que o agente deve responder que não tem informação suficiente.

Depois de alterar as instruções ou uma ferramenta, rode os mesmos casos novamente. Compare os resultados antes de concluir que uma versão melhorou. Uma avaliação pequena e repetível é mais útil que confiar na impressão de uma única conversa.

Crédito da imagem: Cursor, demonstração oficial do Agent SDK. A miniatura mostra exemplos de agentes organizados como pastas de projeto.

Assista também à demonstração oficial do Cursor Agent SDK, que apresenta o modelo de agentes definidos como código.

Passo 4: escolha hospedagem com base nos dados e nas permissões

Na opção hospedada, confira quais recursos, dados e ferramentas ficam disponíveis para o agente. Na opção de infraestrutura própria, defina quem mantém o ambiente, onde ficam os logs e como as credenciais são protegidas.

Teste primeiro com dados fictícios. Depois, verifique se os registros de execução contêm prompts, conteúdo de repositório ou dados pessoais que não deveriam ficar acessíveis a outras pessoas.

Para comparar a proposta do SDK com o anúncio completo, veja o lançamento do Cursor Agent SDK. Se quiser dividir tarefas de desenvolvimento em espaços separados, consulte o guia de agentes em Git worktrees.

Passo 5: mantenha uma pessoa responsável pela decisão final

Use o agente para produzir uma análise, uma sugestão ou uma alteração preparada para revisão. A aprovação para fazer merge, publicar ou enviar dados deve continuar com a pessoa responsável, principalmente enquanto o sistema está em avaliação.

Registre quais instruções, ferramentas e casos de avaliação foram usados em cada versão. Assim, quando o resultado mudar, você consegue relacionar a diferença a uma alteração concreta.

Como evitar os erros mais comuns no Cursor Agent SDK

Se o agente inventar uma resposta, adicione um caso de avaliação que exponha essa lacuna e peça que ele indique quando falta informação. Se uma ferramenta receber entrada inesperada, valide e encerre sem executar a ação.

Se os resultados variam, mantenha o mesmo conjunto de avaliação ao comparar alterações. Se o agente tiver acesso além do necessário, reduza as permissões em vez de tentar corrigir tudo apenas com instruções no prompt.