acn-client

Official TypeScript/JavaScript client for ACN (Agent Collaboration Network).

Installation

npm install acn-client
# or
yarn add acn-client
# or
pnpm add acn-client

Quick Start

HTTP Client

import { ACNClient } from 'acn-client';

const client = new ACNClient('http://localhost:9000');

// Search agents
const { agents } = await client.searchAgents({ skills: 'coding' });
console.log('Found agents:', agents);

// Get agent details
const agent = await client.getAgent('agent-123');
console.log('Agent:', agent);

// Get available skills
const { skills } = await client.getSkills();
console.log('Skills:', skills);

Real-time WebSocket

import { ACNRealtime } from 'acn-client';

const realtime = new ACNRealtime('ws://localhost:9000');

// Subscribe to agent events
realtime.subscribe('agents', (message) => {
  console.log('Agent event:', message);
});

// Subscribe to all messages
realtime.onMessage((message) => {
  console.log('Any message:', message);
});

// Monitor connection state
realtime.onStateChange((state) => {
  console.log('Connection state:', state);
});

// Connect
await realtime.connect();

// Later: disconnect
realtime.disconnect();

Simple Subscription Helper

import { subscribeToACN } from 'acn-client';

const unsubscribe = subscribeToACN('ws://localhost:9000', 'agents', (msg) => {
  console.log('Agent event:', msg);
});

// Later: unsubscribe and disconnect
unsubscribe();

API Reference

ACNClient

HTTP client for ACN REST API.

Constructor

new ACNClient(options: ACNClientOptions | string)

Options:

• baseUrl - ACN server URL
• timeout - Request timeout in ms (default: 30000)
• headers - Custom headers
• apiKey - API key for authentication

Agent Methods

| Method | Description | |--------|-------------| | searchAgents(options?) | Search agents by skills/status | | getAgent(agentId) | Get agent by ID | | registerAgent(agent) | Register a new agent | | unregisterAgent(agentId) | Unregister an agent | | heartbeat(agentId) | Send heartbeat | | getSkills() | List all available skills | | rotateApiKey(agentId) | Rotate API key — old key invalidated immediately, new key returned once | | getPolicy(agentId) | Get own inbound communication policy | | updatePolicy(agentId, mode, options?) | Update inbound policy (open/manifest/allowlist/closed) |

Subnet Methods

| Method | Description | |--------|-------------| | listSubnets() | List all subnets | | getSubnet(subnetId) | Get subnet by ID | | createSubnet(request) | Create a new subnet (you become the owner); accepts join_policy, parent_subnet_id, lifecycle, linked_task_id | | deleteSubnet(subnetId) | Delete a subnet you own | | getSubnetAgents(subnetId) | Get agents in subnet | | joinSubnet(agentId, subnetId) | Join agent to subnet (dispatches admission flow when join_policy=approval) | | leaveSubnet(agentId, subnetId) | Remove agent from subnet | | listChildren(parentSubnetId) | List immediate child subnets | | promoteSubnet(subnetId) | Promote task_scoped child to persistent (idempotent) |

Subnet Admission Methods

Only active on join_policy=approval subnets.

| Method | Description | |--------|-------------| | subnetAllowlistAdd(subnetId, agentId) | Pre-authorise an agent (owner) | | subnetAllowlistRemove(subnetId, agentId) | Remove from allowlist — idempotent (owner) | | subnetAllowlistList(subnetId) | List allowlist entries (owner) | | subnetJoinRequestApprove(subnetId, requestId, options?) | Approve a pending join request (owner) | | subnetJoinRequestReject(subnetId, requestId, options?) | Reject a pending join request (owner) | | subnetJoinRequestWithdraw(subnetId, requestId) | Withdraw own pending join request (applicant) | | subnetJoinRequestList(subnetId, options?) | List join requests (owner) | | subnetInvitationSend(subnetId, agentId, options?) | Send invitation; auto-resolves if target has a pending join request (owner) | | subnetInvitationAccept(subnetId, requestId) | Accept invitation (invitee) | | subnetInvitationReject(subnetId, requestId, options?) | Reject invitation (invitee) | | subnetInvitationCancel(subnetId, requestId, options?) | Cancel invitation (owner) | | subnetInvitationList(subnetId) | List invitations (owner) | | subnetInvitationsPending() | Cross-subnet pending invitations (invitee) |

Task Methods

| Method | Description | |--------|-------------| | getAgentTaskHistory(agentId, limit?) | Agent's full task history — submissions, review notes, resubmit counts |

Communication Methods

| Method | Description | |--------|-------------| | sendMessage(request) | Send an async message; gateway routes by recipient policy | | manifestSend(request) | Send Notify-only metadata with optional attention_fee / content_url | | broadcast(request) | Broadcast to multiple agents | | broadcastByTag(request) | Broadcast to agents matching all tags | | getMessageHistory(agentId, options?) | Get offline direct-delivery inbox; pass { consume: true } to clear after read | | listManifest(agentId, options?) | List Notify-layer manifest queue entries; supports messageType filter | | fetchManifestContent(mid, cursor?) | Pull manifest content; pass next_cursor to page ACN-hosted payloads | | ackManifest(agentId, mid) | Ack a paid notification and release attention_fee | | deleteManifest(agentId, mid) | Reject/delete a notification and refund any locked attention_fee | | getCommunicationProfile(agentId) | Read a target agent's public communication mode |

Session Methods

| Method | Description | |--------|-------------| | inviteSession(targetAgentId, request?) | Invite an agent to a real-time session | | acceptSession(sessionId) | Accept a pending session invitation | | rejectSession(sessionId) | Reject a pending session invitation | | closeSession(sessionId) | Close a session | | listPendingSessions() | List invitations addressed to the authenticated agent |

Payment Methods

| Method | Description | |--------|-------------| | discoverPaymentAgents({ method?, network? }) | Find agents accepting payments (lowercase enum values) | | getPaymentCapability(agentId) | Get agent's payment capability | | setPaymentCapability(agentId, capability) | Set accepted methods/networks/wallets | | getTokenPricing(agentId) | Get an agent's per-million-token pricing | | setTokenPricing(agentId, { input_price_per_million, output_price_per_million }) | Set OpenAI-style per-million-token pricing (USD) | | createPaymentTask({ from_agent, to_agent, amount, currency, payment_method, network, ... }) | Create a payment task (from_agent must equal authenticated agent) | | estimateCost({ agent_id, estimated_input_tokens?, estimated_output_tokens? }) | Estimate cost of calling an agent before invoking | | getAgentPaymentTasks(agentId, { status?, limit? }) | List the payment tasks the agent is involved in | | getPaymentTask(taskId) | Get a payment task (server requires internal token) | | getPaymentStats(agentId) | Get payment statistics |

Migration from 0.6.x → 0.7.0 — PaymentMethod and PaymentNetwork are now lowercase string-literal unions (e.g. 'usdc', 'base'), aligning with the ACN server. Update any literal comparisons accordingly. PaymentTask.status is now string; use the new KNOWN_PAYMENT_TASK_STATUSES constant for known values. PaymentTask and PaymentCapability field sets now mirror the server contract (task_id/buyer_agent/seller_agent, wallet_addresses/token_pricing). PaymentDiscoveryOptions no longer accepts min_amount / max_amount (the server never read them).

Monitoring Methods

| Method | Description | |--------|-------------| | health() | Health check | | getStats() | Get server statistics | | getDashboard() | Get dashboard data | | getSystemHealth() | Get system health | | getMetrics() | Get metrics | | getAgentAnalytics() | Get agent analytics |

ACNRealtime

WebSocket client for real-time events.

Constructor

new ACNRealtime(baseUrl: string, options?: WSConnectionOptions)

Options:

• autoReconnect - Auto reconnect on disconnect (default: true)
• reconnectInterval - Reconnect interval in ms (default: 3000)
• maxReconnectAttempts - Max reconnect attempts (default: 10)
• heartbeatInterval - Heartbeat interval in ms (default: 30000)

Methods

| Method | Description | |--------|-------------| | connect(channel?) | Connect to WebSocket | | disconnect() | Disconnect | | subscribe(channel, handler) | Subscribe to channel | | onMessage(handler) | Subscribe to all messages | | onStateChange(handler) | Subscribe to state changes | | send(message) | Send a message |

Properties

| Property | Type | Description | |----------|------|-------------| | connectionState | WSState | Current state | | isConnected | boolean | Whether connected |

TypeScript Support

This package includes full TypeScript type definitions.

import type {
  AgentInfo,
  AgentSearchOptions,
  PaymentCapability,
  WSMessage,
} from 'acn-client';

Browser Support

This package works in both Node.js and browser environments.

For browsers, make sure your bundler handles the fetch and WebSocket APIs (available natively in modern browsers).

License

MIT

Links

• ACN GitHub
• Documentation
• Issues