@cursor/sdk 1.0.31 systemPrompt fails in Local Agent with unknown option '--system-prompt'

Support Bug Reports
1

Where does the bug appear (feature/product)?

Cursor SDK

Describe the Bug

In @cursor/[email protected], the documented main-agent systemPrompt option is accepted by TypeScript and Agent.create() succeeds, but the Local Agent run fails with [invalid_argument] unknown option ‘–system-prompt’. The same environment works normally when systemPrompt is omitted. Cursor Support also checked the failing request and confirmed it failed on the agent side before reaching the model provider.

Steps to Reproduce

  1. Create an isolated Node.js project and install @cursor/[email protected].

  2. Use Node.js v22.22.2 and TypeScript Local Agent with model composer-2.5.

  3. First verify that the Local Agent works without systemPrompt:

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(“Reply with exactly: NORMAL_AGENT_WORKS”);
const result = await run.wait();

This succeeds and returns NORMAL_AGENT_WORKS.

requestId:
2933c422-ed41-46ef-999a-02a92f31b24d

  1. Then add the documented systemPrompt option:

const agent = await Agent.create({
apiKey: process.env.CURSOR_API_KEY!,
model: { id: “composer-2.5” },
systemPrompt: No matter what the user asks, reply exactly with: CURSOR_SYSTEM_PROMPT_WORKS ,
local: { cwd: process.cwd() },
});

const run = await agent.send(“What is 2 + 2?”);
const result = await run.wait();

  1. Agent.create() succeeds and agent.send() returns a run, but run.wait() finishes with:

status: error
message: [invalid_argument] unknown option ‘–system-prompt’

Failing requestId:
2120645a-b790-4751-8084-8145ab1b382a

The only relevant difference between the two tests is the presence of systemPrompt.

Expected Behavior

The Local Agent should accept the documented systemPrompt option and run normally.

For this reproduction, the replacement system prompt should cause the model to reply:

CURSOR_SYSTEM_PROMPT_WORKS

The run should reach the model provider instead of failing in the Local Agent runtime with unknown option ‘–system-prompt’.

Operating System

Linux

Version Information

@cursor/sdk: 1.0.31
Node.js: v22.22.2
npm: 10.9.7
Runtime: TypeScript Local Agent
Model: composer-2.5

OS: Ubuntu 24.04.4 LTS (Noble Numbat)
Kernel: Linux 6.8.0-101-generic
Architecture: x86_64

For AI issues: which model did you use?

composer-2.5

For AI issues: add Request ID with privacy disabled

2120645a-b790-4751-8084-8145ab1b382a

Additional Information

Cursor Support inspected the failing request:

requestId: 2120645a-b790-4751-8084-8145ab1b382a

and confirmed that the run failed on the agent side before reaching the model provider.

Support described this as either a docs/SDK surface vs Local Agent runtime gap, or gated access that is not enabled for the key.

Support tickets:
T-F45104
T-F46099

The reproduction was performed in an isolated environment with @cursor/[email protected]. Production remains pinned to @cursor/[email protected].

Does this stop you from using Cursor

No - Cursor works, but with this issue

5

Hey, thanks for the detailed report and the request ID, that makes it easy to see what’s going on.

You read the situation correctly. systemPrompt was added in 1.0.31 and it’s in the docs, but access is currently enabled per account, and your account isn’t in the enabled set yet. So the SDK accepts the option, but the run fails on the first send(). Your code and environment are fine, this isn’t a setup issue on your side. The error message for this case is honestly misleading. I’ve passed both the access rollout and the wording of the error to the team.

What actually works in 1.0.31 right now:

  1. Put your instructions in AGENTS.md or .cursor/rules/*.mdc in the cwd you pass to the local agent. Rules load together with the built-in prompt, and this is the closest thing to a persistent instruction layer today.
  2. Or add your instructions at the start of the message you pass into agent.send().

Neither option replaces the built-in prompt the way systemPrompt will, but until access is expanded, this is the workable path. I’ll reply here as soon as there’s an update on access.

8

Thanks for confirming. Glad to know my environment and implementation are correct. I’ll keep production pinned to 1.0.30 and wait for the access rollout. Looking forward to testing systemPrompt once it becomes available for my account.