Agent Registration

Agent registration is the process by which agents connect to the Parallax control plane and make themselves available to execute tasks.

Registration Flow

Basic Registration

import { ParallaxAgent } from '@parallax/sdk-typescript';

const agent = new ParallaxAgent({
  name: 'my-agent',
  capabilities: ['text-analysis', 'summarization'],
  controlPlaneUrl: 'http://localhost:8080',
});

agent.onTask(async (task) => {
  return {
    result: await processTask(task.input),
    confidence: 0.85,
  };
});

// Register and start receiving tasks
await agent.start();

Configuration Options

Required Options

const agent = new ParallaxAgent({
  name: 'unique-agent-name',     // Must be unique across all agents
  capabilities: ['analysis'],     // At least one capability
});

Connection Options

const agent = new ParallaxAgent({
  name: 'my-agent',
  capabilities: ['analysis'],

  // Control plane URL (or use PARALLAX_CONTROL_PLANE_URL env var)
  controlPlaneUrl: 'http://localhost:8080',

  // Reconnection settings
  reconnectInterval: 5000,       // MS between reconnect attempts
  maxReconnectAttempts: 10,      // Max attempts before giving up (0 = infinite)

  // Connection timeout
  connectionTimeout: 10000,      // MS to wait for initial connection

  // Heartbeat settings
  heartbeatInterval: 30000,      // MS between heartbeats
});

Execution Options

const agent = new ParallaxAgent({
  name: 'my-agent',
  capabilities: ['analysis'],

  // Concurrent task handling
  maxConcurrentTasks: 5,         // Handle up to 5 tasks simultaneously

  // Task timeout
  taskTimeout: 60000,            // 60s timeout per task
});

Metadata

const agent = new ParallaxAgent({
  name: 'my-agent',
  capabilities: ['analysis'],

  // Custom metadata (visible to control plane)
  metadata: {
    model: 'gpt-4',
    version: '1.2.0',
    region: 'us-east-1',
    provider: 'openai',
  },

  // Tags for filtering
  tags: ['production', 'fast', 'english'],
});

Capabilities

Capabilities are string identifiers that describe what an agent can do. The control plane uses capabilities to match tasks to agents.

Naming Conventions

// Task types
capabilities: ['text-analysis', 'summarization', 'translation']

// Languages
capabilities: ['english', 'spanish', 'french']

// Models
capabilities: ['gpt-4', 'claude-3', 'gemini']

// Quality tiers
capabilities: ['fast', 'standard', 'expert']

// Domains
capabilities: ['medical', 'legal', 'technical']

Capability Matching

When a pattern requests agents:

agents:
  capabilities: [analysis, english]
  min: 3

The control plane finds agents that have all requested capabilities:

// ✅ Matches - has both 'analysis' AND 'english'
new ParallaxAgent({
  capabilities: ['analysis', 'english', 'gpt-4'],
});

// ❌ Doesn't match - missing 'english'
new ParallaxAgent({
  capabilities: ['analysis', 'gpt-4'],
});

Dynamic Capabilities

Update capabilities at runtime:

const agent = new ParallaxAgent({
  name: 'dynamic-agent',
  capabilities: ['analysis'],
});

// Add a capability
agent.addCapability('translation');

// Remove a capability
agent.removeCapability('analysis');

// Set all capabilities
agent.setCapabilities(['summarization', 'extraction']);

Authentication

API Key Authentication

const agent = new ParallaxAgent({
  name: 'my-agent',
  capabilities: ['analysis'],
  controlPlaneUrl: 'https://api.parallax.dev',
  apiKey: process.env.PARALLAX_API_KEY,
});

Token Authentication

const agent = new ParallaxAgent({
  name: 'my-agent',
  capabilities: ['analysis'],
  auth: {
    type: 'token',
    token: process.env.PARALLAX_TOKEN,
    refreshToken: process.env.PARALLAX_REFRESH_TOKEN,
    onRefresh: (newToken) => {
      // Store the new token
    },
  },
});

mTLS Authentication

const agent = new ParallaxAgent({
  name: 'my-agent',
  capabilities: ['analysis'],
  tls: {
    cert: fs.readFileSync('client.crt'),
    key: fs.readFileSync('client.key'),
    ca: fs.readFileSync('ca.crt'),
  },
});

Connection Lifecycle

Startup

const agent = new ParallaxAgent({ ... });

// Register task handler before starting
agent.onTask(async (task) => { ... });

// Start the agent
await agent.start();

// Agent is now connected and receiving tasks

Events

agent.on('connecting', () => {
  console.log('Connecting to control plane...');
});

agent.on('connected', () => {
  console.log('Connected and registered');
});

agent.on('registered', (info) => {
  console.log('Registered as:', info.agentId);
  console.log('Capabilities:', info.capabilities);
});

agent.on('disconnected', (reason) => {
  console.log('Disconnected:', reason);
});

agent.on('reconnecting', (attempt) => {
  console.log(`Reconnecting (attempt ${attempt})...`);
});

agent.on('reconnected', () => {
  console.log('Reconnected successfully');
});

agent.on('error', (error) => {
  console.error('Agent error:', error);
});

Shutdown

// Graceful shutdown - waits for active tasks
await agent.stop();

// Force shutdown - cancels active tasks
await agent.stop({ force: true });

// Shutdown with timeout
await agent.stop({ timeout: 10000 }); // Wait max 10s for tasks

Handling Signals

const agent = new ParallaxAgent({ ... });

// Graceful shutdown on SIGTERM/SIGINT
process.on('SIGTERM', async () => {
  console.log('Received SIGTERM, shutting down...');
  await agent.stop();
  process.exit(0);
});

process.on('SIGINT', async () => {
  console.log('Received SIGINT, shutting down...');
  await agent.stop();
  process.exit(0);
});

await agent.start();

Health Checks

Heartbeats

The SDK automatically sends heartbeats to the control plane:

const agent = new ParallaxAgent({
  heartbeatInterval: 30000,  // Every 30 seconds
});

// The control plane marks agents as unhealthy if heartbeats stop

Custom Health Checks

const agent = new ParallaxAgent({
  name: 'my-agent',
  healthCheck: async () => {
    // Check dependencies
    const dbHealthy = await checkDatabase();
    const apiHealthy = await checkExternalApi();

    return {
      healthy: dbHealthy && apiHealthy,
      details: {
        database: dbHealthy,
        externalApi: apiHealthy,
      },
    };
  },
  healthCheckInterval: 60000,  // Check every minute
});

Status Reporting

// Get current agent status
const status = agent.getStatus();
// {
//   connected: true,
//   registered: true,
//   activeTasks: 2,
//   capabilities: ['analysis'],
//   uptime: 3600000,
// }

// Report to control plane
agent.reportStatus({
  load: 0.75,        // 75% capacity used
  healthy: true,
  custom: { queueLength: 5 },
});

Multiple Agents

Running Multiple Agents

// Run multiple specialized agents
const agents = [
  new ParallaxAgent({
    name: 'analyzer-1',
    capabilities: ['analysis', 'gpt-4'],
  }),
  new ParallaxAgent({
    name: 'analyzer-2',
    capabilities: ['analysis', 'claude-3'],
  }),
  new ParallaxAgent({
    name: 'summarizer',
    capabilities: ['summarization'],
  }),
];

// Start all agents
await Promise.all(agents.map(a => {
  a.onTask(taskHandler);
  return a.start();
}));

// Stop all agents
await Promise.all(agents.map(a => a.stop()));

Agent Pool

import { AgentPool } from '@parallax/sdk-typescript';

const pool = new AgentPool({
  agents: [
    { name: 'analyzer', capabilities: ['analysis'], instances: 3 },
    { name: 'summarizer', capabilities: ['summarization'], instances: 2 },
  ],
  controlPlaneUrl: 'http://localhost:8080',
});

pool.onTask('analysis', analysisHandler);
pool.onTask('summarization', summarizationHandler);

await pool.start();  // Starts all agent instances
await pool.stop();   // Stops all agent instances

Error Handling

Connection Errors

agent.on('error', (error) => {
  if (error.code === 'CONNECTION_REFUSED') {
    console.error('Control plane not available');
  } else if (error.code === 'AUTH_FAILED') {
    console.error('Authentication failed');
  } else if (error.code === 'DUPLICATE_NAME') {
    console.error('Agent name already registered');
  }
});

Task Errors

agent.onTask(async (task) => {
  try {
    return {
      result: await processTask(task.input),
      confidence: 0.85,
    };
  } catch (error) {
    // Report error to control plane
    throw new TaskError('Processing failed', {
      code: 'PROCESSING_ERROR',
      details: error.message,
      retryable: true,
    });
  }
});

Best Practices

Unique Names - Use unique, descriptive agent names
Graceful Shutdown - Always handle SIGTERM/SIGINT for clean shutdown
Health Checks - Implement health checks for production agents
Capability Precision - Use specific capabilities rather than broad ones
Concurrent Limits - Set appropriate maxConcurrentTasks for your resources
Timeouts - Configure reasonable task timeouts
Logging - Log connection events and task processing
Monitoring - Track agent metrics in production

Next Steps

Agents Concept - Understanding agents
Executing Patterns - Running patterns
TypeScript SDK - Full SDK reference

Registration Flow​

Basic Registration​

Configuration Options​

Required Options​

Connection Options​

Execution Options​

Metadata​

Capabilities​

Naming Conventions​

Capability Matching​

Dynamic Capabilities​

Authentication​

API Key Authentication​

Token Authentication​

mTLS Authentication​

Connection Lifecycle​

Startup​

Events​

Shutdown​

Handling Signals​

Health Checks​

Heartbeats​

Custom Health Checks​

Status Reporting​

Multiple Agents​

Running Multiple Agents​

Agent Pool​

Error Handling​

Connection Errors​

Task Errors​

Best Practices​

Next Steps​