· Changelog

Changelog

Armazenamentos personalizados, ferramentas personalizadas e Auto-review para o SDK do Cursor

Entregamos um conjunto de novas funcionalidades nos SDKs de TypeScript e Python. Agora você pode escolher como os metadados do agente e da execução são persistidos, expor suas próprias funções ao agente como ferramentas, encaminhar chamadas de ferramentas locais por meio do Auto-review e aninhar subagentes em qualquer profundidade. Esta versão também traz um conjunto de correções de confiabilidade, performance e plataforma que facilitam a execução de agentes de SDK locais e na nuvem em scripts de produção, CI e integrações personalizadas.

Ferramentas personalizadas

Agora você pode passar suas próprias ferramentas para o agente local fornecendo definições de função por meio de local.customTools, em Agent.create() ou em cada send(). O SDK as expõe ao agente por meio de um servidor MCP integrado chamado custom-user-tools, para que o modelo chame seu código pelo mesmo caminho e com o mesmo controle de permissões que qualquer outra ferramenta MCP.

Antes, expor uma capacidade personalizada significava configurar seu próprio servidor MCP stdio ou HTTP remoto e conectá-lo ao agente. Agora, uma definição de função é suficiente. As ferramentas personalizadas também ficam visíveis para todos os subagentes de um agente pai, então uma ferramenta definida uma vez fica disponível ao longo de toda a execução.

Auto-review

Por padrão, um agente local do SDK executa chamadas de ferramenta sem pedir aprovação, já que não há nenhum humano no processo em uma execução headless. Defina local.autoReview para encaminhar essas chamadas para o Auto-review. Um classificador decide quais chamadas são executadas automaticamente e quais devem ser mantidas em espera, em vez de ignorar a revisão por completo.

Você orienta esse classificador com instruções em linguagem natural em permissions.json. O campo autoRun.allow_instructions descreve padrões de chamadas que devem tender a ser permitidos, e autoRun.block_instructions descreve aqueles que devem ser mantidos para revisão. Por exemplo, você pode permitir inspeções somente leitura de artefatos de build, sempre pausando em operações destrutivas, como exclusões.

{
  "autoRun": {
    "allow_instructions": [
      "Read-only inspections of build artifacts under ./dist are fine."
    ],
    "block_instructions": [
      "Always pause delete operations so I get a chance to review them."
    ]
  }
}

JSONL e armazenamentos personalizados

Ambos os SDKs persistem os metadados de agentes e execuções para que você possa retomar um agente após reiniciar um processo. Até agora, esse armazenamento era feito em SQLite. Agora, você também pode optar por um armazenamento em JSONL, que grava um arquivo simples, append-only, que você pode ler, comparar com diff e versionar. Tanto SqliteLocalAgentStore quanto JsonlLocalAgentStore são exportados diretamente.

Se nenhuma das opções padrão se adequar à sua configuração, implemente a interface pública LocalAgentStore e passe-a por local.store. Crie um armazenamento em memória para execuções efêmeras de CI ou use o Postgres como backend de persistência quando quiser que o estado do agente fique junto com o restante dos dados da sua aplicação. O SDK de Python expõe armazenamentos de host, JSONL e JSONL composto por meio da bridge.

Subagentes aninhados

Os subagentes agora podem criar seus próprios subagentes, e assim por diante. Um subagente revisor pode delegar para um subagente que escreve testes, que pode delegar ainda mais, com cada nível mantendo seu próprio prompt e modelo. Não há nada para ativar; uma sessão de subagente registra o executor necessário para chamar Task, então o aninhamento funciona automaticamente para qualquer agente que defina subagentes.

Melhorias de confiabilidade, performance e plataforma

Esta versão também inclui uma série de correções que melhoram a experiência em ambos os SDKs.

  • Correlação de execuções: Todo send() agora inclui um requestId gerado pela plataforma, exposto em Run e RunResult e persistido nos armazenamentos em memória, SQLite e JSONL. Vincule um script ou uma execução de CI a logs de backend, análises e threads de suporte sem precisar inferi-lo a partir de agentId.
  • wait() confiável em execuções locais: Execuções locais não resolvem mais wait() antes que o resultado do terminal seja gravado. A hidratação continua sendo atualizada até que a execução chegue a um estado final, para que a automação leia um resultado completo.
  • Checkpoints seguros ao descartar: Descartar um agente local não remove mais dados de checkpoint quando falta uma referência raiz, mas ainda existem blobs de checkpoint. O diretório do agente só é limpo quando realmente não há mais nada a preservar.
  • Streaming na nuvem por HTTP/1.1: Sessões de agente na nuvem agora fazem streaming corretamente em transportes HTTP/1.1 usados por alguns proxies, implementações fetch mais antigas do Node e certas imagens de CI. O comportamento em HTTP/2 permanece inalterado.

  • Importação mais leve: Importar @cursor/sdk não carrega mais antecipadamente toda a stack de agente local. Consumidores que usam apenas a nuvem ou apenas tipos evitam o custo do tempo de execução local até a primeira chamada local, sem nenhuma mudança na API. A primeira chamada local paga o custo de uma importação única e depois permanece em cache.
  • Tipos TypeScript autocontidos: Os arquivos .d.ts publicados não fazem mais referência a pacotes de espaço de trabalho não publicados. Isso corrige erros TS2305 e TS2307 com skipLibCheck: false e o any silencioso em tipos de stream como TurnEndedUpdate.
  • ripgrep empacotado: Execuções locais de shell usam o binário rg empacotado da plataforma sem modificar o seu PATH global. No Windows, adicionar o ripgrep no início não sobrescreve mais a variável Path.

  • Composer 2 direciona para Composer 2.5: Clientes SDK que ainda fixam slugs composer-2 descontinuados são direcionados automaticamente para o Composer 2.5, preservando as variantes rápidas, para que scripts mais antigos continuem funcionando.

  • list_runs com escopo de espaço de trabalho: Client, AsyncClient e Agent.list_runs aceitam um cwd opcional, e a bridge usa como fallback o espaço de trabalho em que foi iniciada. Isso corrige resultados espúrios de "agente não encontrado" quando a bridge é executada como subprocesso.
  • Erros de não encontrado mais claros: Buscar um agente que não está no espaço de trabalho resolvido retorna um erro claro de não encontrado, em vez de um erro interno opaco.
  • Versão 0.1.6 e análises: cursor-sdk 0.1.6 documenta o caminho de release do Buildkite e rotula o uso do SDK como sdk-python- para análises mais claras.

Execute npm install @cursor/sdk ou pip install cursor-sdk para atualizar. Scripts que fixam composer-2 passam automaticamente para o Composer 2.5, e requestId é uma adição segura ao esquema de metadados da sua execução. Consulte a documentação do TypeScript e do Python para ver todos os detalhes.