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

As a Standalone Service

# Clone the repository
git clone https://github.com/jeffkit/cursor-agent-a2a.git
cd cursor-agent-a2a

# Install dependencies
pnpm install

As an NPM Package

# 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

CLI Tool

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

# 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

Cursor CLI Setup

Make sure Cursor CLI is installed and authenticated:

# 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:

# 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

Development Mode

pnpm run dev

Production Mode

# 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 <api-key> header.

Agent Card Discovery

Get the agent's capabilities and metadata.

GET /.well-known/agent-card.json
Authorization: Bearer <api-key>

Response:

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

Send Message (Synchronous)

Send a message and get an immediate response.

POST /messages
Authorization: Bearer <api-key>
Content-Type: application/json

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

Response:

{
  "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:

POST /messages?stream=true
Authorization: Bearer <api-key>
Accept: text/event-stream

Create Async Task

Create a long-running task and poll for status.

POST /tasks
Authorization: Bearer <api-key>
Content-Type: application/json

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

Response:

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

Query Task Status

GET /tasks/:taskId
Authorization: Bearer <api-key>

Response:

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

Cancel Task

DELETE /tasks/:taskId
Authorization: Bearer <api-key>

Multi-turn Conversations

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

1. First message - Provide workspace in context:

   {
     "message": "Create a hello.js file",
     "context": {
       "workspace": "/path/to/project"
     }
   }

   Response includes sessionId.

2. Subsequent messages - Only need sessionId, workspace is automatically retrieved:

   {
     "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.

Management UI

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

Using Project IDs

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

# 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"
    }
  }'

Workspace Resolution Priority

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)

Project Management API

# 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:

1. Per-Request Model (Highest Priority)

Specify the model in each API request:

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"}
  }'

2. Environment Variable

Set a default model for all requests:

export CURSOR_DEFAULT_MODEL=sonnet-4.5

3. System Default

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

Available Models

To see all available models:

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)

Model Priority

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

Examples

Using Sonnet (recommended for general use):

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:

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:

export CURSOR_DEFAULT_MODEL=gpt-5.2
pnpm run dev
# All requests will use gpt-5.2 unless overridden

Usage Examples

Using with AgentStudio

Add to your project's a2a-config.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.

Using with curl

# 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

# Type checking
pnpm run type-check

# Build
pnpm run build

# Development with hot reload
pnpm run dev

License

MIT

Author

jeffkit ([email protected])

Contributing

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

Links

• GitHub Repository
• NPM Package
• Cursor CLI Documentation