collet

Agent Communication Protocol (ACP) SDK for TypeScript

A TypeScript SDK for building agent-to-agent communication systems using the Agent Communication Protocol.

Features

• 📡 Request/response messaging pattern
• ⏱️ Built-in timeout support
• 🔌 Event-driven architecture
• 📊 Connection state management
• 🔄 Automatic reconnection with exponential backoff
• 📦 Zero external dependencies

Installation

npm install collet

Quick Start

Server

import { createServer } from 'collet';

const server = createServer({ port: 5000, verbose: true });

// Register request handlers
server.handle('echo', async (request) => ({
  result: `Echo: ${request.params}`
}));

server.handle('add', async (request) => {
  const [a, b] = request.params as number[];
  return { result: a + b };
});

// Start server
await server.listen();

Client

import { createClient } from 'collet';

const client = createClient({
  url: 'localhost',
  port: 5000,
  verbose: true
});

// Connect to server
await client.connect();

// Send requests
const echoResult = await client.request('echo', 'Hello');
console.log(echoResult); // "Echo: Hello"

const sumResult = await client.request('add', [5, 3]);
console.log(sumResult); // 8

// Listen for events
client.on(ACPEventType.Connected, (event) => {
  console.log('Connected to server');
});

// Disconnect
await client.disconnect();

API Reference

Server

const server = createServer({
  port: 5000,
  host: 'localhost',    // optional, default: localhost
  timeout: 30000,       // optional, default: 30000ms
  verbose: false,       // optional, default: false
});

await server.listen();
server.handle('method_name', async (request) => ({
  result: 'response_data'
}));
await server.close();

Client

const client = createClient({
  url: 'localhost',
  port: 5000,
  timeout: 5000,           // optional, default: 5000ms
  reconnectAttempts: 3,    // optional, default: 3
  reconnectDelay: 1000,    // optional, default: 1000ms
  verbose: false,          // optional, default: false
});

await client.connect();
const result = await client.request('method', params, timeout);
await client.disconnect();

client.on(ACPEventType.Connected, handler);
client.on(ACPEventType.Error, handler);

Message Types

interface ACPMessage {
  id: string;
  type: string;
  payload: unknown;
  metadata?: Record<string, unknown>;
  timestamp?: number;
  correlationId?: string;
}

interface ACPRequest extends ACPMessage {
  method: string;
  params?: unknown;
  timeout?: number;
}

interface ACPResponse extends ACPMessage {
  requestId: string;
  result?: unknown;
  error?: ACPError;
}

Events

enum ACPEventType {
  Connected = 'connected',
  Disconnected = 'disconnected',
  Error = 'error',
  Message = 'message',
  Request = 'request',
  Response = 'response',
}

Examples

Echo Server

const server = createServer({ port: 5000 });
server.handle('ping', async (req) => ({ result: 'pong' }));
await server.listen();

RPC Server

const server = createServer({ port: 8080 });

server.handle('calculate', async (req) => {
  const { operation, a, b } = req.params as Record<string, unknown>;
  let result;

  if (operation === 'add') result = (a as number) + (b as number);
  if (operation === 'multiply') result = (a as number) * (b as number);

  return { result };
});

await server.listen();

Load Balanced Client

const servers = ['server1', 'server2', 'server3'];

for (const server of servers) {
  const client = createClient({ url: server, port: 5000 });
  try {
    await client.connect();
    const result = await client.request('process', data);
    await client.disconnect();
    return result;
  } catch (error) {
    continue; // Try next server
  }
}

Error Handling

try {
  const result = await client.request('operation', params);
} catch (error) {
  if (error.message.includes('timeout')) {
    console.log('Request timed out');
  } else if (error.message.includes('not connected')) {
    console.log('Client not connected');
  }
}

License

Apache-2.0

Support

For issues and questions, visit: https://github.com/collet/collet-ext