Локальный ai агент без рутины чата: Cursor SDK пишет файл сам

Чтобы запустить локальный ai агент через Cursor SDK, положите ключ в переменную окружения, поставьте Node.js 22.13+ и пакет @cursor/sdk, затем одним скриптом вызовите Agent.create с режимом local и узким заданием: «напиши один файл в эту папку». Так вы экономите время на рутине «открыл IDE → скопировал ответ»: в папке появится бриф или черновик поста — без кнопки Automations и без сборки офлайн-модели.

SDK здесь — библиотека для вашего скрипта: тот же агент Cursor, только из терминала. Критерий готово — файл на диске, например brief.md. «Локальный» в docs Cursor — не Ollama и не модель без интернета: цикл агента и файлы живут на вашем ПК, а ответы модели идут через облако Cursor.

Перед первой строкой кода

Вам нужен аккаунт Cursor с рабочим API-доступом (часто это Pro или корпоративный доступ), интернет и отдельная папка под эксперимент. Один ключ CURSOR_API_KEY подходит и для local, и для cloud-режима в SDK.

Я бы не начинал с облачной VM, пачки вложенных агентов и кастомных инструментов. Для первого прогона хватает одного файла-скрипта и одного артефакта. Сравнение Cloud / Automations / SDK оставьте на потом — сейчас цель проще: ключ в env, пакет установлен, файл появился.

Ключ: Dashboard → env, не в код

Схема: ключ из Dashboard в env, не в код и не в git

Откройте Cursor Dashboard → раздел API Keys и создайте пользовательский ключ (или ключ service account). Ключи Team Admin в SDK пока не поддерживаются — если авторизация падает «странно», проверьте тип ключа, а не только баланс.

В терминале задайте переменную: export CURSOR_API_KEY=»ваш_ключ». Либо положите ключ в файл .env рядом со скриптом и не коммитьте его: добавьте .env в .gitignore. Ключ в чате, в скриншоте и в репозитории — это уже инцидент, а не «удобный старт».

Проверка: в открытом коде и в истории git строки с ключом нет. Если сомневаетесь — отзовите ключ в Dashboard и выпустите новый.

Node и пакет @cursor/sdk

Чеклист: Node 22.13+ и установка пакета @cursor/sdk

Проверьте версию: команда node -v должна показать 22.13+. Ниже — обновите Node, иначе установка или импорт пакета могут вести себя непредсказуемо.

Создайте папку проекта (лучше пустую маркетинговую, не прод-репозиторий), зайдите в неё и выполните по очереди: npm init -y, затем npm install @cursor/sdk.

На момент проверки документации (июль 2026) актуальный npm latest пакета — 1.0.24. Если что-то падает на моделях или auth, сначала обновите пакет, потом ищите «SDK сломан».

Официальный быстрый старт лежит в репозитории cursor/cookbook — можно свериться с примерами; для первого файла достаточно своего скрипта ниже.

Один скрипт run-agent.mjs

Создайте файл run-agent.mjs (модуль ESM). cwd — папка проекта, в которой агент читает и пишет файлы. Модель в примере — composer-2.5: старые id вроде composer-2 / composer-2-fast по changelog Cursor перенаправляются на Composer 2.5, но в новом коде лучше сразу писать актуальный id.

import { Agent } from «@cursor/sdk»;

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

const run = await agent.send(
  «Создай в текущей папке файл brief.md: короткий бриф на пост про пользу локального агента Cursor из скрипта. Только этот файл, без лишних правок.»
);

for await (const event of run.stream()) {
  if (event.type === «assistant») {
    process.stdout.write(event.message ?? «»);
  }
}

Запустите: node run-agent.mjs. В консоли пойдёт поток ответа. За вечер цель одна: в той же папке появился brief.md (или тот файл, который вы назвали в задании). Пока файла нет — результат не закрыт, даже если в терминале красивый текст. Получите файл — сможете повторять бриф без копипаста из чата.

Sandbox по умолчанию выключен: вызовы инструментов (запись файла, shell) идут без вашего ручного подтверждения на каждый шаг. Поэтому на первом прогоне — узкая папка и узкий промпт, а не «почисть весь репозиторий».

Критерий «получилось» и типичные ошибки

На практике результат закрыт, если в папке есть файл от агента. Откройте папку проекта и убедитесь:

есть новый файл-артефакт от агента;
ключ не лежит в git и не зашит в код;
вы можете вслух сказать: local = агент и файлы на ПК, ответы модели — через облако Cursor, не офлайн-LLM.

Типичная ошибка новичка — решить, что «SDK сломан», когда падает auth / 403 при проверке моделей (в сообществе на Free часто ломается вызов /v1/models при local create). Проверьте по списку:

проверьте, что план и API-доступ реально позволяют SDK, а не только чат в IDE;
обновите @cursor/sdk;
убедитесь, что CURSOR_API_KEY виден процессу (команда echo $CURSOR_API_KEY не пустая);
не используйте Team Admin key.

Если агент долго простаивал (порядка 15 минут), community фиксирует AuthenticationError вместо сетевой ошибки: создайте агента заново или resume по документации, не ждите «само оживёт».

Расход токенов идёт в те же пулы usage, что IDE и Cloud Agents, с тегом SDK в dashboard. Перед длинными прогонами имеет смысл глянуть лимит расходов — для одного brief.md это обычно не драма, для цикла на весь диск уже да.

Не тащите на старте

Не путайте этот маршрут с кнопкой Automations в интерфейсе и с Cloud Agents в удалённой машине: здесь ваш скрипт дергает агента на локальных файлах. Не подменяйте задачу установкой Ollama «без интернета» — это другой продукт и другой критерий готово.

Вложенные агенты, кастомные инструменты и «офис страниц» — следующий слой после того, как один файл стабильно появляется по команде. Иначе вы отлаживаете архитектуру, ещё не закрыв ключ и cwd.

Я бы оставил песочницу и автопроверку инструментов на второй проход: сначала докажите себе путь «ключ → npm → файл», потом уже ужесточайте политику инструментов.

После первого файла

Когда brief.md лежит в папке, можно решать, нужен ли вам UI Automations, облачный агент или остаётесь на скрипте на своём ПК. Для выбора режима — Cloud Agents, Automations и SDK; про интерфейс облака — гайд по Cloud Agents. Если интересна экономика прогонов — экономика AI-агентов в Cursor. Это углубление после файла на диске, не условие старта.

Практика по Cursor и агентам — в канале t.me/maya_pro и в зеркале max.ru/maya_pro.

Материал проверен: Артур Хорошев (CEO Maya AI, автор курса по Make.com и вайбкодингу).

Опора на источники: cursor.com/docs/sdk/typescript (Agent.create local/cloud, Node 22.13+, sandbox off, CURSOR_API_KEY); cursor.com/changelog/sdk-updates-jun-2026 (composer-2 → 2.5); npm @cursor/sdk 1.0.24 (июль 2026); github.com/cursor/cookbook; forum.cursor.com (Free 403 на /v1/models; idle ~15 мин → AuthenticationError); @maya_pro #1314; Яндекс Вордстат «локальный ai агент» = 183, «cursor sdk» = 34 на 21.07.2026.

Частые вопросы

Нужен ли интернет для «локального» агента Cursor SDK?

Да. Local в docs Cursor — про цикл агента и доступ к файлам на машине. Сама модель остаётся в облаке Cursor.

Чем это лучше чата в IDE?

Тем же агентом можно пользоваться из скрипта: повторять задачу, встроить в свой сценарий, не копировать ответ руками каждый раз. Для разового вопроса чат в IDE проще; для повторяемого брифа или черновика — скрипт.

Можно ли на Free-плане?

Не обещайте себе бесплатный старт без проверки. В сообществе Free иногда получает 403 на проверке моделей при local create. Рабочий путь — Pro или иной доступ, где API и список моделей реально открыты.

Нужен ли sandbox в первый день?

Не обязателен для старта. Важно сузить задачу («только файл X») и не запускать агента на всём продакшен-репозитории с широким промптом. Песочница и автопроверка инструментов — следующий слой контроля, когда сценарий уже живой.

Какую модель указать в коде?

Для нового скрипта берите composer-2.5. Старые id Composer 2 в changelog перенаправляют на 2.5, но явно актуальный id меньше путаницы при чтении кода через полгода.