Официальный набор для TypeScript встраивает агента прямо в ваш процесс. Требуется современная версия среды выполнения, и есть выбор из двух режимов, задаваемый ровно одним ключом. Локальный режим исполняет цикл агента и файловые инструменты внутри вашего процесса, хотя рассуждение всё равно идёт через размещённые модели: локальность здесь про то, где читаются и пишутся файлы, а не про то, где считается ответ. Облачный создаёт изолированную виртуальную машину. Это принципиально разные модели доверия - в первом случае вы отдаёте инструментам доступ к своей файловой системе, во втором к чужой временной, - и выбирают их осознанно.
Понятия у набора те же, что и в программном интерфейсе: агент - долгоживущий контейнер, запуск - один запрос, события приходят в нормализованном виде, одинаковом для обоих режимов. Есть и короткая форма для разовой задачи, которая сама создаёт агента, отправляет запрос, ждёт результат и освобождает ресурсы. Она удобна ровно там, где не нужно продолжение разговора: разовая проверка, разовая сводка, разовая правка по чёткой постановке. Как только появляется второй запрос по тем же материалам, дешевле держать агента и слать ему следующий запуск, чем поднимать контекст заново.
Полезно один раз увидеть минимальную интеграцию. Ниже - создание агента с ключом, моделью и локальным режимом с включённой изоляцией, отправка запроса и чтение потока событий. Обратите внимание на две детали: явное включение песочницы и формулировка задачи без правок. Обе они не случайны и обе относятся к одному и тому же - к границе того, что программа может сделать с вашим рабочим каталогом.
Самое важное предупреждение здесь касается поведения по умолчанию. Быстрый старт локального режима не показывает подтверждений: команды оболочки, правки и запись файлов выполняются автоматически. Это логично для программного интерфейса - спрашивать некого, и любое ожидание подтверждения заблокировало бы процесс, - но означает, что запуск на рабочем дереве с вашими учётными данными без изоляции равносилен выдаче полного доступа скрипту, который вы только что написали и ещё ни разу не проверяли.
Отсюда практическое правило: до первого запуска на реальном каталоге включают изоляцию и, если нужно, обработчики событий. Песочница в параметрах старта - это одна строка, а её отсутствие превращает неточность в формулировке задачи в изменения файлов, которых никто не ждал. Тот же принцип, что и в интерактивной работе, только цена невнимательности выше: человек за редактором видит предложенную правку и может её отклонить, а программа не остановится и не переспросит.
Облачный режим снимает часть этих вопросов, но добавляет свои: окружение, секреты, сеть и артефакты. Зато там доступны результаты работы в виде файлов, снимков экрана и видео. Выбор между режимами обычно решается одним вопросом - должна ли работа идти на вашей машине с её файлами или в чистой изолированной среде. Если задача сводится к чтению репозитория и подготовке изменения, локальность не даёт ничего, кроме риска.
Есть сценарий, в котором про это забывают чаще всего, - запуск набора внутри собственного сервиса или сборочного конвейера. Процесс там обычно уже нагружен переменными окружения: ключами от хранилищ, токенами развёртывания, доступами к базам. Инструменты агента работают в этом же процессе, а значит, команда оболочки, запущенная им, видит ровно то же окружение. Отсюда правило, не связанное с самим набором: исполнитель запускают с минимальным набором секретов, а не с тем, который достался ему по наследству от родительского процесса. Признак нарушенной границы узнаваем: агент решает задачу неожиданно быстрым способом - обращается к внешнему сервису или к базе, о которых в постановке не было ни слова, просто потому, что доступ лежал рядом.
Обработчики событий - вторая точка контроля, и о ней стоит думать как о конструкции, а не как о настройке. Они позволяют вклиниться перед действием инструмента и разрешить его, отклонить или записать в журнал, то есть построить ту самую проверку, которой в автоматическом режиме нет по устройству. Их же используют для аудита: без записи о том, какие команды выполнял агент, разбор последствий сводится к чтению истории изменений файлов. Третья обязанность - жизненный цикл ресурсов: конструкция автоматического освобождения в примере не украшение, а гарантия того, что после разовой задачи не останется висящего агента, который продолжает числиться живым и стоить денег.
Инженерный вывод простой: набор для языка превращает агента в компонент вашего сервиса, и относиться к нему нужно как к компоненту. У него есть конфигурация, границы, обработка ошибок и жизненный цикл ресурсов. Написанный по-быстрому скрипт, который создаёт агента с полными правами на рабочем каталоге, - это не интеграция, а способ однажды объяснять коллегам, откуда взялись изменения.
Типичные провалы предсказуемы. Запустить локальный режим на рабочем дереве без изоляции. Ждать подтверждений там, где их нет по устройству. Отдать агенту всё окружение родительского процесса вместе с чужими секретами. Смешать оба режима в одной конфигурации вместо явного выбора. И не освобождать ресурсы, оставляя долгоживущих агентов после разовых задач.
import { Agent } from "@cursor/sdk";
await using agent = await Agent.create({
apiKey: process.env.CURSOR_API_KEY!,
model: { id: "composer-2.5" },
local: {
cwd: process.cwd(),
// без песочницы агент пишет в рабочий каталог,
// запускает команды оболочки и ходит в сеть
sandboxOptions: { enabled: true },
},
});
const run = await agent.send("Summarize this repository without edits");
for await (const event of run.stream()) {
console.log(event);
}