Agents API

The Agents API enables discovery and communication with agents in your Private Connect workspace. Use it to build distributed systems, coordinate workflows, and orchestrate multi-agent operations.

Overview

Access the Agents API through the agents property:

import { PrivateConnect } from '@privateconnect/sdk';

const pc = new PrivateConnect({ apiKey: 'your-api-key' });
const agents = await pc.agents.list();

Methods

list()

List all agents in the workspace.

list(options?: { onlineOnly?: boolean }): Promise<Agent[]>

options

object

Optional filtering options

Show properties

onlineOnly

boolean

Only return agents that are currently online

Agent[]

Array of agents in the workspace

Show Agent properties

string

Unique agent identifier

name

string | undefined

Human-readable agent name

label

string

Agent label for display

isOnline

boolean

Whether the agent is currently online

lastSeenAt

string

ISO timestamp of last activity

capabilities

string[]

Array of registered capability names

services

string[]

Array of service names exposed by this agent

Example

All Agents
Online Only

const agents = await pc.agents.list();

agents.forEach(agent => {
  console.log(`${agent.label} (${agent.isOnline ? 'online' : 'offline'})`);
  console.log(`  Capabilities: ${agent.capabilities.join(', ')}`);
  console.log(`  Services: ${agent.services.join(', ')}`);
});

const onlineAgents = await pc.agents.list({ onlineOnly: true });

console.log(`${onlineAgents.length} agents online`);

findByCapability()

Find agents that have a specific capability.

findByCapability(capability: string): Promise<Agent[]>

capability

string

required

The capability name to search for

Agent[]

Array of agents with the specified capability

Example

// Find all agents that can deploy
const deployers = await pc.agents.findByCapability('deploy');

if (deployers.length > 0) {
  console.log(`Found ${deployers.length} agents with deploy capability`);
  deployers.forEach(agent => {
    console.log(`  - ${agent.label}`);
  });
}

registerCapabilities()

registerCapabilities(
  capabilities: Array<{ name: string; metadata?: Record<string, unknown> }>
): Promise<void>

capabilities

array

required

Array of capabilities to register

Show Capability object

name

string

required

Capability name (e.g., ‘deploy’, ‘monitor’, ‘backup’)

metadata

object

Optional metadata describing the capability

Example

await pc.agents.registerCapabilities([
  { 
    name: 'deploy',
    metadata: { 
      environments: ['staging', 'production'],
      maxConcurrent: 3
    }
  },
  { 
    name: 'monitor',
    metadata: { 
      interval: 60,
      metrics: ['cpu', 'memory', 'disk']
    }
  },
]);

console.log('Capabilities registered');

sendMessage()

Send a message to another agent.

sendMessage(
  toAgentId: string,
  payload: Record<string, unknown>,
  options?: { 
    channel?: string; 
    type?: 'request' | 'response' | 'event' 
  }
): Promise<{ messageId: string }>

toAgentId

string

required

Target agent ID

payload

object

required

Message payload (any JSON-serializable object)

options

object

Optional message options

Show properties

channel

string

Channel name for organizing messages (e.g., ‘deployments’, ‘alerts’)

type

'request' | 'response' | 'event'

Message type for workflow coordination

messageId

string

Unique identifier for the sent message

Example

Simple Message
With Channel
Request/Response

const { messageId } = await pc.agents.sendMessage(
  'agent-xyz',
  { action: 'deploy', version: '1.2.3' }
);

console.log(`Message sent: ${messageId}`);

await pc.agents.sendMessage(
  'monitoring-agent',
  { 
    event: 'threshold_exceeded',
    metric: 'cpu',
    value: 95
  },
  { 
    channel: 'alerts',
    type: 'event'
  }
);

// Send request
const { messageId } = await pc.agents.sendMessage(
  'database-agent',
  { query: 'get_stats' },
  { type: 'request' }
);

// Later, respond
await pc.agents.sendMessage(
  'original-agent-id',
  { stats: { connections: 42, queries: 1337 } },
  { type: 'response' }
);

broadcast()

Broadcast a message to all online agents.

broadcast(
  payload: Record<string, unknown>,
  options?: { channel?: string }
): Promise<{ sent: number }>

payload

object

required

Message payload to broadcast

options

object

Optional broadcast options

Show properties

channel

string

Channel name for organizing messages

sent

number

Number of agents that received the message

Example

// Notify all agents of maintenance window
const { sent } = await pc.agents.broadcast(
  {
    type: 'maintenance',
    startsAt: '2024-03-15T02:00:00Z',
    duration: 60,
    message: 'Database upgrade in progress'
  },
  { channel: 'system' }
);

console.log(`Notified ${sent} agents`);

getMessages()

Retrieve messages for this agent.

getMessages(options?: {
  channel?: string;
  unreadOnly?: boolean;
  limit?: number;
}): Promise<Message[]>

options

object

Optional filtering options

Show properties

channel

string

Filter by channel name

unreadOnly

boolean

Only return unread messages

limit

number

Maximum number of messages to return

Message[]

Array of messages

Show Message properties

string

Unique message identifier

from

object

Sender information

Show properties

string

Sender agent ID

name

string | undefined

Sender agent name

label

string | undefined

Sender agent label

channel

string

Channel name

type

string

Message type

payload

object

Message payload

createdAt

string

ISO timestamp when message was created

isRead

boolean

Whether the message has been read

Example

Unread Messages
By Channel

const unread = await pc.agents.getMessages({ unreadOnly: true });

console.log(`You have ${unread.length} unread messages`);

unread.forEach(msg => {
  console.log(`From: ${msg.from.label}`);
  console.log(`Channel: ${msg.channel}`);
  console.log(`Payload:`, msg.payload);
});

const alerts = await pc.agents.getMessages({
  channel: 'alerts',
  limit: 10
});

alerts.forEach(alert => {
  console.log(`[${alert.createdAt}] ${alert.payload.message}`);
});

markRead()

Mark messages as read.

markRead(messageIds: string[]): Promise<void>

messageIds

string[]

required

Array of message IDs to mark as read

Example

// Get unread messages
const messages = await pc.agents.getMessages({ unreadOnly: true });

// Process them
messages.forEach(msg => {
  console.log(`Processing: ${msg.payload.action}`);
  // ... handle message ...
});

// Mark all as read
const messageIds = messages.map(m => m.id);
await pc.agents.markRead(messageIds);

console.log(`Marked ${messageIds.length} messages as read`);

Complete Example

Here’s a complete example showing agent orchestration:

import { PrivateConnect } from '@privateconnect/sdk';

const pc = new PrivateConnect({ 
  apiKey: process.env.PRIVATECONNECT_API_KEY!,
  agentId: 'orchestrator'
});

// Register capabilities
await pc.agents.registerCapabilities([
  { name: 'orchestrate', metadata: { version: '1.0' } }
]);

// Find deployment agents
const deployers = await pc.agents.findByCapability('deploy');

if (deployers.length === 0) {
  console.log('No deployment agents available');
  process.exit(1);
}

// Send deployment request to first available agent
const target = deployers[0];
const { messageId } = await pc.agents.sendMessage(
  target.id,
  {
    action: 'deploy',
    environment: 'production',
    version: '1.2.3',
    services: ['api', 'worker']
  },
  { 
    channel: 'deployments',
    type: 'request'
  }
);

console.log(`Deployment request sent to ${target.label}`);

// Poll for response
while (true) {
  await new Promise(resolve => setTimeout(resolve, 5000));
  
  const messages = await pc.agents.getMessages({
    channel: 'deployments',
    unreadOnly: true
  });
  
  const response = messages.find(m => m.type === 'response');
  
  if (response) {
    console.log('Deployment complete:', response.payload);
    await pc.agents.markRead([response.id]);
    break;
  }
}

Overview

REST API

SDK

Overview

Methods

list()

Example

findByCapability()

Example

registerCapabilities()

Example

sendMessage()

Example

broadcast()

Example

getMessages()

Example

markRead()

Example

Complete Example

Next Steps

Services API

Sessions API

Build docs developers (and LLMs) love

Overview

REST API

SDK

​Overview

​Methods

​list()

​Example

​findByCapability()

​Example

​registerCapabilities()

​Example

​sendMessage()

​Example

​broadcast()

​Example

​getMessages()

​Example

​markRead()

​Example

​Complete Example

​Next Steps

Services API

Sessions API

Build docs developers (and LLMs) love

Overview

Methods

list()

Example

findByCapability()

Example

registerCapabilities()

Example

sendMessage()

Example

broadcast()

Example

getMessages()

Example

markRead()

Example

Complete Example

Next Steps