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:
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:
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:
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
curl -N "$LAP_URL/v1/sessions/$SESSION/events/stream" \
-H "Authorization: Bearer $MASTER_KEY"
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 |
Cursor sessions can start immediately when you include prompt in the POST /session body.
