> ## Documentation Index
> Fetch the complete documentation index at: https://docs.litellm-agent-platform.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Cursor Agents API

> Run agents using the Cursor Agents runtime.

The Cursor runtime lets you create and run Cursor background agents through the LiteLLM Agent Platform. Sessions support repository and pull-request context. The platform normalizes Cursor's event stream to the standard Anthropic Managed Agents shape, so calling code is runtime-agnostic.

## Prerequisites

* LiteLLM Agent Platform running
* Cursor API key (from your Cursor account settings)

## 1. Add your Cursor API key

Open **Settings → Credentials** in the UI and add your Cursor API key.

Or via the API:

```bash theme={null}
curl -X PUT $LAP_URL/api/agent-runtimes/cursor/credentials \
  -H "Authorization: Bearer $MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "<your-cursor-api-key>",
    "api_base": "https://api.cursor.com"
  }'
```

## 2. Select the built-in runtime

`cursor` is a built-in runtime. You do not need to register a custom runtime harness unless you are proxying through your own Cursor-compatible service.

## 3. Create an agent

In the UI, click **New Agent**, choose `cursor` as the runtime, and save.

Or via the API:

```bash theme={null}
curl -X POST $LAP_URL/api/agents \
  -H "Authorization: Bearer $MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-cursor-agent",
    "owner_id": "local-user",
    "runtime": "cursor",
    "model": "claude-opus-4-5",
    "system": "You are a coding assistant."
  }'
```

## 4. Start a session with repo context

Cursor sessions accept `environment` fields for repository and PR settings:

```bash theme={null}
SESSION=$(curl -s -X POST $LAP_URL/session \
  -H "Authorization: Bearer $MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "runtime": "cursor",
    "agent_id": "<agent-id>",
    "prompt": "Fix the failing tests in src/utils.ts",
    "environment": {
      "repository": "https://github.com/your-org/your-repo",
      "ref": "main",
      "auto_create_pr": false
    }
  }' | jq -r .id)
```

## 5. Stream events

```bash theme={null}
curl -N "$LAP_URL/v1/sessions/$SESSION/events/stream" \
  -H "Authorization: Bearer $MASTER_KEY"
```

Cursor's native events (`assistant`, `tool_call`, `status`, `result`) are normalized to the Anthropic event surface:

| Cursor event       | Normalized to            |
| ------------------ | ------------------------ |
| `status` (running) | `session.status_running` |
| `assistant`        | `agent.message`          |
| `tool_call`        | `agent.tool_use`         |
| `result`           | `agent.tool_result`      |
| `status` (idle)    | `session.status_idle`    |

See [Internal SDK contract](/engineering/sdk-api-contract) for the Rust SDK types.

<Note>
  Cursor sessions can start immediately when you include `prompt` in the `POST /session` body.
</Note>