Overview

The ACP Worker provides complete support for the Agent Client Protocol (ACP), enabling seamless integration with ACP-compliant agents and MCP servers. It runs as a child process of stdio Bus kernel, handling protocol messages via NDJSON over stdin/stdout.

Location: workers-registry/acp-worker/

Features

• Complete ACP Protocol Support: Full implementation of initialize, session management, and prompt handling
• MCP Server Integration: Connect to and execute tools from Model Context Protocol servers
• Session-Based Routing: Maintains session affinity for stateful agent interactions
• Graceful Shutdown: Handles SIGTERM signals for clean process termination
• TypeScript Support: Full type definitions included for type-safe development
• High Performance: Efficient NDJSON protocol for low-latency message routing

Configuration

Basic Configuration

Create a configuration file for stdio Bus kernel:

{
  "pools": [
    {
      "id": "acp-registry",
      "command": "npx",
      "args": [
        "@stdiobus/workers-registry",
        "acp-worker"
      ],
      "instances": 1
    }
  ]
}

High-Throughput Configuration

For production deployments with higher load:

{
  "pools": [
    {
      "id": "acp-registry",
      "command": "npx",
      "args": [
        "@stdiobus/workers-registry",
        "acp-worker"
      ],
      "instances": 4
    }
  ],
  "limits": {
    "max_input_buffer": 4194304,
    "max_output_queue": 16777216,
    "backpressure_timeout_sec": 120
  }
}

Configuration Fields

Integration with MCP Servers

The ACP Worker can connect to MCP servers to execute tools and access resources. This enables agents to leverage MCP server capabilities through the ACP protocol.

MCP Server Configuration

Configure MCP servers in your ACP Worker setup:

import { ACPAgent } from '@stdiobus/workers-registry/workers/acp-worker';
 
// MCP servers are configured within the ACP Worker implementation
// See workers-registry/acp-worker/src/mcp/ for integration details

Tool Execution Flow

The tool execution flow follows this pattern:

1. Client sends ACP Request to stdio Bus kernel
2. Kernel forwards NDJSON message to ACP Worker
3. Worker makes Tool Call to MCP Server
4. MCP Server returns Tool Result to Worker
5. Worker sends NDJSON response back to Kernel
6. Kernel returns ACP Response to Client

Session Management

The ACP Worker maintains session affinity to ensure stateful interactions are routed to the same worker instance.

Session Affinity

Messages with the same sessionId are automatically routed to the same worker instance:

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "prompt",
  "sessionId": "sess-123",
  "params": {
    "prompt": "Hello, agent!"
  }
}

Session Lifecycle

1. Initialize: Client sends initialize request to establish connection
2. Session Creation: Worker creates a new session with unique sessionId
3. Message Routing: All subsequent messages with the same sessionId route to the same worker
4. Session Cleanup: Worker cleans up session resources on disconnect or timeout

Protocol Messages

Initialize Request

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "initialize",
  "params": {
    "clientInfo": {
      "name": "my-client",
      "version": "1.0.0"
    }
  }
}

Initialize Response

{
  "jsonrpc": "2.0",
  "id": "1",
  "result": {
    "serverInfo": {
      "name": "acp-registry"
      "version": "2.0.3"
    },
    "capabilities": {
      "prompts": true,
      "tools": true
    }
  }
}

Prompt Request

{
  "jsonrpc": "2.0",
  "id": "2",
  "method": "prompt",
  "sessionId": "sess-123",
  "params": {
    "prompt": "What is the weather today?",
    "context": {}
  }
}

Building from Source

To build the ACP Worker from source:

cd node_modules/@stdiobus/workers-registry/workers-registry/acp-worker
npm install
npm run build

The compiled output will be in the dist/ directory.

Testing

Test Connection

Send a test message to verify the ACP Worker is running:

echo '{"jsonrpc":"2.0","id":"1","method":"initialize","params":{"clientInfo":{"name":"test","version":"1.0"}}}' | nc localhost 9000

Expected Response

{"jsonrpc":"2.0","id":"1","result":{"serverInfo":{"name":"acp-registry""version":"2.0.3"},"capabilities":{"prompts":true,"tools":true}}}

Programmatic Usage

Module Import

// Import ACP worker (default export)
import worker from '@stdiobus/workers-registry';
 
// Import specific ACP worker
import acpWorker from '@stdiobus/workers-registry/workers/acp-worker';

TypeScript Types

import type { ACPAgent } from '@stdiobus/workers-registry/workers/acp-worker';
 
// Use types for type-safe development
const agent: ACPAgent = /* ... */;

Troubleshooting

Worker Crashes

If the ACP Worker crashes frequently, increase restart limits:

{
  "limits": {
    "max_restarts": 10,
    "restart_window_sec": 120
  }
}

Next Steps

• Registry Launcher - Route to multiple agents
• MCP-to-ACP Proxy - IDE integration

Resources

• Agent Client Protocol SDK
• ACP Worker Source