How can I use code to call the Agent through API?

Support Help
, ,
1

I’m using the example from the TypeScript SDK documentation:

const result = await Agent.prompt(“What does the auth middleware do?”, {
apiKey: process.env.CURSOR_API_KEY!
model: { id: “composer-2” },
local: { cwd: process.cwd() },
});
console.log(“Agent prompt result:”, JSON.stringify(result, null, 2));

The result is:
Agent prompt result: {
“id”: “run-41fdf001-f5fa-4ffe-bb48-6bd0bbb49433”,
“status”: “error”
}

I have already generated the apiKey.
What could be the possible reasons for this error?

4

Hey, the issue is with the local: { cwd } option. It routes the run to the local agent, and composer-2 is a cloud-only model, so you immediately get an error. To run it via the cloud SDK, use cloud: {}:

const result = await Agent.prompt("What does the auth middleware do?", {
    apiKey: process.env.CURSOR_API_KEY!,
    model: { id: "composer-2" },
    cloud: {},
});

Also, there was a recent bug where the SDK returned status: error even though the run on the server completed fine. That’s already fixed.

If you want a direct REST option without the SDK, there’s an endpoint:

curl -X POST https://api.cursor.com/v0/agents \
  -u YOUR_API_KEY: \
  -H 'Content-Type: application/json' \
  -d '{
    "prompt": { "text": "What does the auth middleware do?" },
    "model": "composer-2",
    "source": { "repository": "https://github.com/your-org/your-repo" }
  }'

API details: Cloud Agents API | Cursor Docs

Let me know how it goes.

6

I intend to implement the agent functionality seen in chat dialogs through programmatic invocation. Can this be accomplished with a local agent? Additionally, I have no intention of uploading my code to GitHub.

7

My requirement is to use the features introduced at：https://cursor.com/cn/docs/sdk/typescript
However, running the examples provided there triggers the error shown above.

8

Yes, for your use case (no code upload to GitHub), you need the local agent. It works against the local cwd and doesn’t send your repo to the cloud. So local: { cwd: process.cwd() } is the right choice, I wasn’t fully correct in my previous reply about it being cloud-only.

A couple of notes:

  1. Your code is missing a comma after apiKey: process.env.CURSOR_API_KEY!. Fix that or TS won’t compile correctly.
  2. We shipped a few fixes for the local SDK last week (model selection and more). Update the package to the latest version:
npm install @cursor/sdk@latest

Working local example using composer-2:

import { Agent } from "@cursor/sdk";

const result = await Agent.prompt("What does the auth middleware do?", {
    apiKey: process.env.CURSOR_API_KEY!,
    model: { id: "composer-2" },
    local: { cwd: process.cwd() },
});

console.log(JSON.stringify(result, null, 2));

If after updating you still get status: error, try creating the agent via Agent.create() and iterate the stream. That usually shows the real reason:

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

const run = await agent.send("What does the auth middleware do?");
for await (const event of run.stream) {
    console.log(event);
}

Send me the stream output (or the error text) and I can help you more precisely.

9

Thanks a lot! The issue is resolved after running npm install @cursor/sdk@latest