Cursor Agent A2A Service


Independent A2A-compatible service wrapping Cursor CLI agent command. This service provides a standard A2A (Agent-to-Agent) protocol interface for Cursor CLI, allowing it to be called from other A2A-compatible services like AgentStudio.

Features

- ✅ A2A Protocol Compliant - Full support for A2A protocol endpoints
- ✅ Multi-turn Conversations - Session management with workspace persistence
- ✅ Streaming Responses - Server-Sent Events (SSE) for real-time updates
- ✅ Async Task Management - Long-running task support with status polling
- ✅ Workspace Management - Automatic workspace handling in multi-turn conversations
- ✅ Session Persistence - Workspace is automatically retrieved from session context
- ✅ Project ID Mapping - Map short project IDs to workspace paths for easier API calls
- ✅ Web Management UI - Manage project mappings through a user-friendly web interface

Installation

$3

``bash


Clone the repository

git clone https://github.com/jeffkit/cursor-agent-a2a.git
cd cursor-agent-a2a

Install dependencies

pnpm install
`

$3

`bash


Global installation (recommended for CLI usage)

npm install -g cursor-agent-a2a

or

pnpm add -g cursor-agent-a2a

Local installation

npm install cursor-agent-a2a

or

pnpm add cursor-agent-a2a
`

$3

After global installation, you can use the cursor-agent-a2a command:

`bash


Install as system service

cursor-agent-a2a install --port 4300 --api-key your-api-key

Manage service

cursor-agent-a2a start # Start the service
cursor-agent-a2a stop # Stop the service
cursor-agent-a2a restart # Restart the service
cursor-agent-a2a status # Check service status

View logs

cursor-agent-a2a logs # View last 50 lines
cursor-agent-a2a logs --follow # Follow logs (like tail -f)
cursor-agent-a2a logs --lines 100 # View last 100 lines
cursor-agent-a2a logs --type stderr # View only stderr

Upgrade

cursor-agent-a2a upgrade # Upgrade to latest version

Uninstall

cursor-agent-a2a uninstall # Remove system service
`

Prerequisites

$3

Make sure Cursor CLI is installed and authenticated:

`bash


Install Cursor CLI

curl https://cursor.com/install -fsS | bash

Login (or set CURSOR_API_KEY environment variable)

cursor agent login

Verify authentication

cursor agent status
`

Configuration

Set environment variables:

`bash


API Key for A2A authentication (default: cursor-agent-demo-key)

export CURSOR_AGENT_API_KEY=your-secure-api-key

Server port (default: 4937)

export PORT=4937

Server host (default: 0.0.0.0)

export HOST=0.0.0.0

Cursor API Key (optional, uses local login if not set)

export CURSOR_API_KEY=sk_your_cursor_api_key

Default model (optional, defaults to sonnet-4.5)

export CURSOR_DEFAULT_MODEL=sonnet-4.5
`

Running

$3

`bash
pnpm run dev
`

$3

`bash


Build

pnpm run build

Start

pnpm start
`

The service will start on http://localhost:4937 (or your configured port).

API Endpoints

All endpoints require API key authentication via Authorization: Bearer header.

$3

Get the agent's capabilities and metadata.

`bash
GET /.well-known/agent-card.json
Authorization: Bearer
`

Response:
`json
{
"name": "Cursor Agent",
"description": "AI-powered code assistant via Cursor CLI...",
"version": "1.0.0",
"url": "http://localhost:4937",
"skills": [...],
"securitySchemes": [...]
}
`

$3

Send a message and get an immediate response.

`bash
POST /messages
Authorization: Bearer
Content-Type: application/json

{
"message": "Say hello",
"context": {
"workspace": "/path/to/project"
},
"sessionId": "optional-session-id"
}
`

Response:
`json
{
"response": "Hello! I'm Claude, an AI programming assistant...",
"sessionId": "chat-12345",
"metadata": {
"processingTimeMs": 1234
}
}
`

Streaming Mode:

Add ?stream=true or Accept: text/event-stream header:

`bash
POST /messages?stream=true
Authorization: Bearer
Accept: text/event-stream
`

$3

Create a long-running task and poll for status.

`bash
POST /tasks
Authorization: Bearer
Content-Type: application/json

{
"message": "Long running task",
"context": {
"workspace": "/path/to/project"
},
"timeout": 600000,
"sessionId": "optional-session-id"
}
`

Response:
`json
{
"taskId": "task-uuid",
"status": "pending",
"checkUrl": "/tasks/task-uuid"
}
`

$3

`bash
GET /tasks/:taskId
Authorization: Bearer
`

Response:
`json
{
"taskId": "task-uuid",
"status": "completed",
"output": {
"result": "Task completed successfully"
},
"createdAt": "2026-01-24T...",
"completedAt": "2026-01-24T..."
}
`

$3

`bash
DELETE /tasks/:taskId
Authorization: Bearer
`

Multi-turn Conversations

The service supports multi-turn conversations with automatic workspace management:

1. First message - Provide workspace in context:
`json
{
"message": "Create a hello.js file",
"context": {
"workspace": "/path/to/project"
}
}
`
Response includes sessionId.

2. Subsequent messages - Only need sessionId, workspace is automatically retrieved:
`json
{
"message": "Modify the file to add a function",
"sessionId": "chat-12345"
}
`

Project ID Mapping

The service supports mapping short project IDs to workspace paths for easier API calls.

$3

Access the web management interface at:
`
http://localhost:4937/manage
`

Features:
- Add new project mappings
- Edit existing projects
- Delete project mappings
- Copy project IDs for API use

$3

Once you've created a project mapping, you can use the project ID in API calls:

`bash


Using project ID in URL (no need to specify workspace in context)

curl -X POST "http://localhost:4937/messages/:projectId" \
-H "Authorization: Bearer your-api-key" \
-H "Content-Type: application/json" \
-d '{"message": "Say hello"}'

Traditional way (still supported)

curl -X POST "http://localhost:4937/messages" \
-H "Authorization: Bearer your-api-key" \
-H "Content-Type: application/json" \
-d '{
"message": "Say hello",
"context": {
"workspace": "/path/to/project"
}
}'
`

$3

When multiple workspace sources are provided, the resolution priority is:

1. Project ID from URL parameter (:projectId)
2. Workspace from context.workspace
3. Workspace from session (if sessionId is provided)
4. Current working directory (fallback)

$3

`bash


List all projects

GET /projects

Get specific project

GET /projects/:projectId

Create new project

POST /projects
{
"name": "My Project",
"workspace": "/path/to/project"
}

Update project

PUT /projects/:projectId
{
"name": "Updated Name",
"workspace": "/new/path"
}

Delete project

DELETE /projects/:projectId
`

All project management endpoints require API key authentication.

Model Configuration

You can configure which Cursor model to use in three ways:

$3

Specify the model in each API request:

`bash
curl -X POST "http://localhost:4937/messages" \
-H "Authorization: Bearer your-api-key" \
-H "Content-Type: application/json" \
-d '{
"message": "Say hello",
"model": "sonnet-4.5",
"context": {"workspace": "/path/to/project"}
}'
`

$3

Set a default model for all requests:

`bash
export CURSOR_DEFAULT_MODEL=sonnet-4.5
`

$3

If neither is specified, the service defaults to sonnet-4.5 (Claude 4.5 Sonnet).

$3

To see all available models:

`bash
cursor agent --list-models
`

Common models:
- sonnet-4.5 - Claude 4.5 Sonnet (default, balanced performance)
- sonnet-4.5-thinking - Claude 4.5 Sonnet with extended thinking
- opus-4.5 - Claude 4.5 Opus (most capable, requires credits)
- opus-4.5-thinking - Claude 4.5 Opus with extended thinking
- gpt-5.2 - GPT-5.2
- gpt-5.2-codex - GPT-5.2 Codex (code-optimized)
- gemini-3-pro - Google Gemini 3 Pro
- gemini-3-flash - Google Gemini 3 Flash (fast)

$3

1. Request body model parameter (highest priority)
2. CURSOR_DEFAULT_MODEL environment variable
3. System default: sonnet-4.5 (fallback)

$3

Using Sonnet (recommended for general use):
`bash
curl -X POST "http://localhost:4937/messages/project-id" \
-H "Authorization: Bearer cursor-agent-demo-key" \
-H "Content-Type: application/json" \
-d '{"message": "Say hello", "model": "sonnet-4.5"}'
`

Using GPT-5.2 Codex:
`bash
curl -X POST "http://localhost:4937/messages/project-id" \
-H "Authorization: Bearer cursor-agent-demo-key" \
-H "Content-Type: application/json" \
-d '{"message": "Refactor this code", "model": "gpt-5.2-codex"}'
`

Using environment default:
`bash
export CURSOR_DEFAULT_MODEL=gpt-5.2
pnpm run dev


All requests will use gpt-5.2 unless overridden


`

Usage Examples

$3

Add to your project's a2a-config.json:

`json
{
"allowedAgents": [
{
"name": "Cursor Agent",
"url": "http://localhost:4937",
"apiKey": "your-api-key",
"description": "Cursor CLI agent via A2A",
"enabled": true
}
]
}
`

Then use it in AgentStudio agents via the A2A client tool.

$3

`bash


Get agent card

curl -X GET "http://localhost:4937/.well-known/agent-card.json" \
-H "Authorization: Bearer your-api-key"

Send message

curl -X POST "http://localhost:4937/messages" \
-H "Authorization: Bearer your-api-key" \
-H "Content-Type: application/json" \
-d '{
"message": "Say hello",
"context": {
"workspace": "/path/to/project"
}
}'

Continue conversation

curl -X POST "http://localhost:4937/messages" \
-H "Authorization: Bearer your-api-key" \
-H "Content-Type: application/json" \
-d '{
"message": "Continue",
"sessionId": "chat-12345"
}'
`

Development

`bash


Type checking

pnpm run type-check

Build

pnpm run build

Development with hot reload

pnpm run dev
``

License

MIT

Author

jeffkit (bbmyth@gmail.com)

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Links

- GitHub Repository
- NPM Package
- Cursor CLI Documentation