Tutorial do Cursor SDK: execute agentes de código com TypeScript

A Cursor anunciou seu SDK para TypeScript no fim de abril de 2026 e o lançou em beta público. O pacote é publicado como @cursor/sdk e roda em ambientes Node, como scripts, jobs de CI e serviços de backend.

A principal diferença em relação ao uso do Cursor no editor é onde a tarefa começa. Em vez de abrir um chat e digitar o prompt você mesmo, seu código cria o agente, envia a tarefa, transmite eventos, aguarda o resultado e trata erros.

Neste tutorial, configuramos o SDK, executamos um quickstart local e, depois, construímos o projeto principal: um agente em nuvem que corrige um bug em um repositório do GitHub e abre um pull request. Eu deixo o bug pequeno de propósito para que o fluxo do SDK fique visível. Em seguida, cobrimos os pontos de extensão e as verificações de segurança necessárias antes de adaptar o padrão. O projeto em nuvem usa um repositório de apoio com o script de inicialização e o projeto alvo.

O SDK está em beta público, então confira a documentação oficial antes de reutilizar este código em um projeto de longo prazo.

O que é o Cursor SDK?

O Cursor SDK é um pacote TypeScript, @cursor/sdk, que permite criar e executar agentes do Cursor via código. Ele dá acesso a:

• Execuções de agentes locais e em nuvem.
• Ferramentas de codebase do Cursor, incluindo indexação, busca, grep, servidores MCP, skills, hooks e subagentes.
• Os modelos disponíveis na sua conta Cursor, incluindo Composer 2, GPT-5.5 e Claude.

O SDK usa o mesmo sistema de agentes do Cursor IDE, CLI e app web. A diferença é que você o chama a partir de TypeScript.

Quando usar o SDK

O SDK se encaixa em tarefas que devem começar pelo código, e não por uma pessoa digitando no editor. Eu usaria em um job de CI que pede para um agente inspecionar um teste com falha, um webhook que cria uma branch para correção de bug ou uma ferramenta interna que roda uma tarefa fixa de agente a partir de um formulário.

SDK versus o app Cursor

O SDK é mais uma forma de usar agentes do Cursor, ao lado do Cursor IDE e do cursor agent CLI.

Use o IDE para conversar no editor. Use a CLI para prompts no terminal. Use o SDK quando código TypeScript precisar criar o agente, enviar a tarefa e lidar com o resultado. Como mencionado acima, a CLI não aceita chaves de provedores externos; o SDK também autentica apenas com uma chave de API do Cursor.

Como o Cursor SDK se organiza

Antes de escrever código, ajuda conhecer os poucos objetos e opções de runtime que o SDK expõe.

Arquitetura do Cursor SDK em três runtimes. Imagem do autor.

Três runtimes

O SDK suporta três locais onde um agente pode rodar.

Neste artigo, usamos local e nuvem do Cursor. A nuvem autogerenciada, citada acima, é principalmente para planos Enterprise. O código do SDK muda via a chave de configuração que você passa: local ou cloud.

Runtime, ferramentas e modelos

Uma execução no SDK tem três partes. O runtime é onde executa. As ferramentas do agente incluem indexação, busca, chamadas de ferramenta MCP, skills, hooks e subagentes. O modelo é selecionado com model: { id: "composer-2" } ou outro id disponível na sua conta.

Você define essas peças na configuração do agente.

Agent e Run

Os dois objetos principais do SDK são o Agent e o Run. Um agente guarda o estado da conversa, a configuração do workspace e as definições do modelo. Um run é um prompt enviado a esse agente, com seu próprio stream, status, resultado e handle de cancelamento.

A separação importa porque agentes em nuvem impõem um run ativo por agente. Se você tentar enviar um segundo prompt enquanto o primeiro ainda está rodando, a API retorna 409 agent_busy. Para rodar em paralelo, crie agentes separados, e não vários runs no mesmo agente.

Streaming de eventos

Cada run expõe um stream de eventos via run.stream(), que é um iterador assíncrono. Cada evento tem um campo type. No beta público atual, o SDK emite eventos system, user, assistant, tool_call, thinking, status, request e task. Não há um evento documentado connection:reconnecting; reconexões são tratadas dentro do SDK.

Para atualizações de nível mais baixo, agent.send() também aceita callbacks onDelta e onStep.

Configurando o Cursor SDK

A configuração é só Node, TypeScript e uma chave de API do Cursor.

Pré-requisitos

Você precisa de:

• Node.js 22 ou mais recente. O pacote oficialmente suporta Node 18+, mas o Node 22 acompanha os exemplos do cookbook oficial e suporta a flag --env-file usada abaixo para carregar o .env.

• Uma conta Cursor no plano Pro (US$ 20/mês) ou superior para agentes em nuvem.

• Familiaridade básica com TypeScript.

• tsx para rodar TypeScript sem compilar.

Instale o SDK e as ferramentas de TypeScript:

Instale o SDK

Em uma pasta nova:

npm init -y
npm install @cursor/sdk
npm install --save-dev typescript tsx @types/node

Adicione "type": "module" ao seu package.json para que os imports funcionem como ESM. Depois, adicione um tsconfig.json que suporte await no topo do arquivo e descarte assíncrono explícito:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "lib": ["ES2022", "ESNext.Disposable"],
    "strict": true,
    "esModuleInterop": true
  }
}

Obtenha uma chave de API do Cursor

A chave era gerada originalmente em cursor.com/dashboard/cloud-agents, mas foi movida para cursor.com/dashboard/integrations. Se um guia apontar para "Cloud Agents", confira em Integrations.

Gere User API Keys em Integrations. Imagem do autor.

Gere uma User API Key ali e armazene como CURSOR_API_KEY:

echo 'CURSOR_API_KEY=crsr_your_key_here' > .env

Adicione .env ao seu .gitignore. O SDK lê process.env diretamente; ele não carrega arquivos .env para você.

Estrutura do projeto

Estrutura de pastas: package.json, tsconfig.json, .env e src/ para seus scripts. Adicione uma pasta .cursor/ para hooks, skills e subagentes quando precisar.

Seu primeiro agente Cursor local

O primeiro exemplo é propositalmente pequeno. Ele cria um agente local, envia um prompt, transmite a resposta e encerra o agente.

Crie um agente local

Crie src/01-quickstart.ts:

import { Agent, type SDKMessage } from "@cursor/sdk";

const agent = await Agent.create({
  apiKey: process.env.CURSOR_API_KEY!,
  model: { id: "composer-2" },
  local: { cwd: process.cwd() },
});

Agent.create() retorna um handle antes do agente fazer qualquer trabalho. local: { cwd: process.cwd() } aponta o agente para o diretório de trabalho atual. O SDK suporta descarte assíncrono; em código de tutorial, eu prefiro um bloco finally explícito porque evita dúvidas sobre a versão de await using.

Envie um prompt e transmita a resposta

Enviar um prompt retorna um objeto Run com seu próprio stream e status. Este exemplo lê o stream em um loop for await e imprime apenas o texto do assistant.

try {
  const run = await agent.send(
    `Write a terminal-friendly summary for a screenshot.

Output exactly:
Local agent summary
- Purpose: demonstrates a local Cursor SDK agent.
- Key files: src/01-quickstart.ts, package.json, tsconfig.json.
- SDK action: creates an agent and streams assistant text.

Rules:
Print exactly those three bullets.
No Markdown bold.
No extra explanation.`,
  );

  for await (const event of run.stream()) {
    if (event.type !== "assistant") continue;
    for (const block of event.message.content) {
      if (block.type === "text") {
        process.stdout.write(block.text);
      }
    }
  }

  const result = await run.wait();
  const duration = result.durationMs === undefined ? "" : `duration=${result.durationMs}ms`;
  console.log(`\n[done] status=${result.status}${duration}`);
} finally {
  await agent[Symbol.asyncDispose]();
}

O agente emite vários tipos de evento, incluindo thinking, tool_call e status. Este exemplo filtra pelo texto do assistant porque esse é o conteúdo visível. event.message.content é tipado e utilizável para streaming, mas é baseado em blocos e pode incluir chamadas de ferramenta. Se você só precisa do texto final, pule o stream e leia result.result após run.wait(). durationMs é público, porém opcional, então o exemplo o trata como opcional.

Trate erros

O SDK lança erros tipados que estendem CursorAgentError. Casos comuns incluem AuthenticationError para chave inválida, ConfigurationError para id de modelo inválido, RateLimitError, IntegrationNotConnectedError e NetworkError.

import { CursorAgentError } from "@cursor/sdk";

try {
  // ... agent code
} catch (error) {
  if (error instanceof CursorAgentError) {
    console.error([${error.code ?? "unknown"}] ${error.message});
    if (error.isRetryable) {
      console.error("Retryable. Try again in a moment.");
    }
  } else {
    throw error;
  }
}

A flag isRetryable é o que sua lógica de retry deve checar. Erros de rede e limite de taxa são retomáveis; configuração ruim e autenticação não são.

Execute

Salve o arquivo e rode com o carregador de .env do Node e tsx.

node --env-file=.env --import tsx/esm src/01-quickstart.ts

A flag --env-file=.env carrega CURSOR_API_KEY antes do script iniciar. O script deve imprimir o texto do assistant e, depois, um rodapé de status em uma linha. Se você vir um erro de autenticação, confira seu .env e confirme que a chave foi gerada no painel de Integrations.