Agent SDK
Встраивайте агента Cusp в программы на TypeScript и Python — с инструментами внутри процесса, колбэками разрешений, хуками, структурированным выводом и лимитами расходов.
Agent SDK запускает агента Cusp из вашего кода. Вы отправляете промпт и получаете поток типизированных сообщений. Ваши инструменты, хуки и решения о разрешениях выполняются в вашем процессе, а сам агент работает в демоне (daemon) Cusp. Поэтому каждая сессия SDK — обычная сессия Cusp: её можно открыть в десктопном приложении или возобновить командой cusp --resume.
API небольшой: query() с параметрами, поток типизированных сообщений и ваши собственные инструменты, хуки и обработчики разрешений.
Будет доступно с первым публичным релизом.
Первый запрос
Будет доступно с первым публичным релизом.
query() передаёт потоком такие сообщения:
| Сообщение | Содержит |
|---|---|
system | Начало сессии (init) и границы сжатия контекста |
assistant | Блоки текста, размышлений и использования инструментов |
user | Результаты инструментов |
stream_event | Частичные дельты, если включён includePartialMessages |
result | Одно на каждый промпт: итоговый текст, стоимость, расход токенов, отказы в разрешениях, структурированный вывод и id вашего сообщения |
Пока запрос выполняется, у него можно вызывать interrupt(), setModel(), setPermissionMode() и rewindFiles(). Чтобы отправлять уточнения потоком, передайте в качестве промпта асинхронный итерируемый объект с сообщениями.
Для диалога с несколькими репликами используйте CuspSDKClient: connect(), query(), receiveResponse(), interrupt() и disconnect(). В TypeScript он поддерживает await using.
Подтверждение вызовов инструментов из кода
canUseTool принимает решение по любому вызову инструмента, который ещё не разрешён режимом разрешений или allowedTools. Он же отвечает на вопросы агента с вариантами ответа.
const run = query({
prompt: "Run the test suite and fix the first failure",
options: {
allowedTools: ["Read", "Grep", "Glob", "Bash(bun test:*)"],
canUseTool: async (toolName, input, { title }) =>
(await confirm(`Allow ${title ?? toolName}?`))
? { behavior: "allow" }
: { behavior: "deny", message: "The user declined" },
},
});canUseTool — один из входов движка разрешений Cusp, а не способ его обойти. Запрещающие правила и защищённые пути по-прежнему действуют, а песочница по-прежнему изолирует команды оболочки.
Собственные инструменты
Определите инструменты в своём процессе и передайте их агенту как MCP-сервер внутри процесса. Агент видит их как mcp__<server>__<tool>.
Будет доступно с первым публичным релизом.
Хуки
hooks принимает колбэки для тех же событий, что и хуки в настройках (PreToolUse, PostToolUse, Stop и так далее), с теми же входными и выходными JSON. В Python регистрируйте их через HookMatcher(matcher="Bash", hooks=[...]).
Параметры
В TypeScript имена параметров пишутся в camelCase, в Python — в snake_case (allowed_tools, permission_mode, max_budget_usd…).
| Параметр | По умолчанию | Назначение |
|---|---|---|
model, effort | Значение рабочей области | provider:model или id модели, а также уровень рассуждений |
cwd | Текущая папка | Рабочая область |
systemPrompt | Полный промпт агента Cusp | { type: "preset", preset: "cusp", append } дополняет его; строка заменяет его |
permissionMode | default | acceptEdits, plan, auto, dontAsk или bypassPermissions |
allowedTools, disallowedTools | Правила, например Bash(npm test:*) или Edit(src/**) | |
canUseTool, hooks | См. выше | |
agents | Субагенты: { name: { description, prompt, tools?, model? } } | |
mcpServers | Конфигурации серверов stdio, http или sse либо серверы внутри процесса | |
settingSources | Все | Какие настройки, память и конфигурацию MCP загружать: user, project и local. [] не загружает ничего |
settings | Дополнительные настройки, как в settings.json | |
resume, continue, forkSession, title | Выбрать сессию или создать её ответвление | |
maxTurns | Остановиться после стольких ходов модели с error_max_turns | |
maxBudgetUsd | Остановиться, когда расходы запроса достигнут этой суммы, с error_max_budget_usd | |
outputFormat | { type: "json_schema", schema }; результат содержит structured_output | |
includePartialMessages | false | Передавать частичные дельты потоком |
abortController | Прерывание останавливает запуск | |
executable | $CUSP_EXECUTABLE, затем cusp | CLI, который нужно запустить |
daemonUrl, daemonToken | Найти или запустить демон | Подключиться к конкретному демону |
Как это работает
query() запускает cusp -p --input-format stream-json --output-format stream-json и общается с ним через стандартный ввод и вывод. Ваши инструменты и хуки внутри процесса CLI предоставляет агенту на loopback-адресе со случайным портом и токеном, а каждый вызов пересылает в ваш процесс. Оба SDK используют один и тот же протокол.
Что важно знать
- Системный промпт по умолчанию — полный промпт агента Cusp, а не минимальный.
rewindFiles(userMessageId)откатывает не только файлы, но и переписку. Id берётся из поляuser_message_idрезультата.- Возможностям, которым нужны настройки на уровне сессии (инструменты внутри процесса, хуки, агенты,
settingSources, замена системного промпта), нужен актуальный демон. Более старый демон при запуске выдаёт понятную ошибку, а не игнорирует их молча.
Дальше
- Разрешения: режимы и синтаксис правил.
- Бюджеты и чеки: сколько стоит запуск.
JetBrains, Zed и редакторы с ACP
Запускайте Cusp командой `cusp acp` в любом редакторе, который поддерживает Agent Client Protocol, — в IDE JetBrains, Zed, Kiro и других.
GitHub Action
Упомяните @cusp в issue или PR либо запускайте запрос по расписанию — Cusp поработает в отдельной ветке, сообщит о ходе работы в комментарии и откроет или обновит PR.