@orchestree/conductor

Workflow orchestration and agent management for Orchestree. Create, execute, and monitor complex workflows with intelligent agent routing and distributed execution.

Installation

npm install @orchestree/conductor

Quick Start

const { WorkflowClient } = require('@orchestree/conductor');

const client = new WorkflowClient({
  apiKey: 'your-api-key',
  baseURL: 'https://api.orchestree.io',
});

// Create a workflow
const workflow = await client.createWorkflow({
  name: 'DataProcessingPipeline',
  steps: [
    {
      id: 'step1',
      name: 'Validate Data',
      type: 'validation',
      config: { schema: 'data-schema-v1' },
    },
    {
      id: 'step2',
      name: 'Process Data',
      type: 'processing',
      config: { processor: 'standard' },
    },
  ],
  metadata: { version: '1.0' },
});

// Execute the workflow
const execution = await client.runWorkflow(workflow.id, {
  data: { /* input data */ },
});

// Monitor execution
const logs = await client.getExecutionLogs(execution.executionId);
console.log(logs);

Core Concepts

Workflows

Workflows are sequences of steps that define complex processes. Each workflow can be versioned, monitored, and triggered by various events.

Agents

Agents are distributed executors that handle task execution. Register agents to expand the conductor's capabilities.

Memory Store

A distributed key-value store for sharing state across workflow executions.

Fleet Management

Monitor and manage multiple agents as a unified fleet with health checks and load balancing.

API Reference

WorkflowClient

Constructor

new WorkflowClient(config)

Config Options:

• apiKey (string, required): Your Orchestree API key
• baseURL (string, optional): API base URL (default: https://api.orchestree.io)

Methods

createWorkflow(workflowDef)

Create a new workflow.

const workflow = await client.createWorkflow({
  name: 'MyWorkflow',
  steps: [/* steps */],
  metadata: { /* optional */ },
});

Parameters:

• workflowDef.name (string): Workflow name
• workflowDef.steps (array): Array of workflow steps
• workflowDef.metadata (object, optional): Additional metadata

Returns: Promise

runWorkflow(workflowId, input, options)

Execute a workflow.

const execution = await client.runWorkflow('workflow-123', {
  userId: 'user-456',
  action: 'process',
});

Parameters:

• workflowId (string): ID of workflow to execute
• input (object, optional): Input parameters
• options (object, optional): Execution options

Returns: Promise

listWorkflows(filters)

List all workflows.

const workflows = await client.listWorkflows({
  status: 'active',
  limit: 20,
  offset: 0,
});

Parameters:

• filters.status (string): Filter by status
• filters.limit (number): Maximum results
• filters.offset (number): Pagination offset
• filters.tags (array): Filter by tags

Returns: Promise<Workflow[]>

getExecutionLogs(executionId, options)

Retrieve execution logs.

const logs = await client.getExecutionLogs('exec-123', {
  limit: 100,
});

Parameters:

• executionId (string): Execution ID
• options (object, optional): Log retrieval options

Returns: Promise<ExecutionLog[]>

registerAgent(agentDef)

Register a new agent.

const agent = await client.registerAgent({
  name: 'DataProcessor',
  endpoint: 'https://agent.example.com',
  capabilities: ['process', 'validate'],
  timeout: 30000,
});

Parameters:

• agentDef.name (string): Agent name
• agentDef.endpoint (string): Agent endpoint URL
• agentDef.capabilities (array): List of capabilities
• agentDef.metadata (object, optional): Additional metadata
• agentDef.timeout (number, optional): Request timeout

Returns: Promise

routeTask(task, options)

Route a task to an appropriate agent.

const result = await client.routeTask({
  type: 'data-process',
  payload: { data: [1, 2, 3] },
}, {
  priority: 'high',
  timeout: 60000,
});

Parameters:

• task.type (string): Task type
• task.payload (object): Task payload
• options.timeout (number, optional): Timeout in milliseconds
• options.retryCount (number, optional): Number of retries
• options.priority (string, optional): Task priority

Returns: Promise

getMemory(key, scope)

Get value from memory store.

const value = await client.getMemory('session-123', 'global');

Parameters:

• key (string): Memory key
• scope (string, optional): Memory scope (default: 'global')

Returns: Promise

setMemory(key, value, scope, options)

Set value in memory store.

await client.setMemory('session-123', { user: 'john' }, 'global', {
  ttl: 3600,
  encrypted: true,
});

Parameters:

• key (string): Memory key
• value (any): Value to store
• scope (string, optional): Memory scope (default: 'global')
• options.ttl (number, optional): Time to live in seconds
• options.encrypted (boolean, optional): Enable encryption

Returns: Promise

getFleetStatus(fleetId)

Get fleet status.

const status = await client.getFleetStatus('fleet-123');

Parameters:

• fleetId (string, optional): Fleet ID

Returns: Promise

listAgents(filters)

List all registered agents.

const agents = await client.listAgents({
  status: 'active',
});

Parameters:

• filters (object, optional): Filter options

Returns: Promise<Agent[]>

getExecutionStatus(executionId)

Get execution status.

const status = await client.getExecutionStatus('exec-123');

Parameters:

• executionId (string): Execution ID

Returns: Promise

cancelExecution(executionId)

Cancel a running execution.

await client.cancelExecution('exec-123');

Parameters:

• executionId (string): Execution ID

Returns: Promise

Error Handling

try {
  const result = await client.runWorkflow('workflow-123', {});
} catch (error) {
  console.error('Execution failed:', error.message);
}

License

MIT