Sunbelt Computer Software

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:

First message - Provide workspace in context:

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

Response includes sessionId.

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:

Project ID from URL parameter (:projectId)
Workspace from context.workspace
Workspace from session (if sessionId is provided)
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

Request body model parameter (highest priority)
CURSOR_DEFAULT_MODEL environment variable
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 (bbmyth@gmail.com)

Contributing

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

Name		Name	Last commit message	Last commit date
coverage		coverage
src		src
.gitignore		.gitignore
CHANGELOG-project-mapping.md		CHANGELOG-project-mapping.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
EXAMPLES.md		EXAMPLES.md
LICENSE		LICENSE
README.md		README.md
com.jeffkit.cursor-agent-a2a.plist		com.jeffkit.cursor-agent-a2a.plist
cursor-agent-a2a-1.3.1.tgz		cursor-agent-a2a-1.3.1.tgz
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
test-project-mapping.sh		test-project-mapping.sh
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Sunbelt Computer Software

PL/B Language Development and Support

Latest commit

History

Folders and files

Repository files navigation

Cursor Agent A2A Service

Features

Installation

As a Standalone Service

As an NPM Package

CLI Tool

Prerequisites

Cursor CLI Setup

Configuration

Running

Development Mode

Production Mode

API Endpoints

Agent Card Discovery

Send Message (Synchronous)

Create Async Task

Query Task Status

Cancel Task

Multi-turn Conversations

Project ID Mapping

Management UI

Using Project IDs

Workspace Resolution Priority

Project Management API

Model Configuration

1. Per-Request Model (Highest Priority)

2. Environment Variable

3. System Default

Available Models

Model Priority

Examples

Usage Examples

Using with AgentStudio

Using with curl

Development

License

Author

Contributing

Links

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages