Process Orchestration

Process Orchestration provides enterprise-grade multi-phase workflows with human-in-the-loop approvals, external participant management, and RAID-based responsibility assignment.

Why Process Orchestration?

Complex enterprise deployments require:

• Multi-phase execution: Structured phases with gates and dependencies
• Human oversight: Customer stakeholders approve critical decisions
• External participants: Magic link authentication for non-users
• RAID model: Clear responsibility assignment (Responsible, Approver, Informed, Delegator)
• Team coordination: Multiple agents working together with shared context
• Audit trail: Complete history of decisions and actions

Process Orchestration vs Workflows

Feature	Workflows	Process Orchestration
Purpose	Task automation	Enterprise deployments
Phases	Sequential nodes	Named phases with gates
Human involvement	Optional approval nodes	Required external stakeholders
Responsibility	Implicit	Explicit RAID model
Team support	Single agent focus	Multi-agent team templates
Duration	Minutes to hours	Days to weeks

Core Concepts

Process Definitions

A process definition describes the structure of a deployment:

interface ProcessDefinition {
  id: string
  name: string
  version: string
  description?: string
  phases: ProcessPhase[]
  agents: Record<string, AgentDefinition>
  humans: Record<string, HumanParticipant>
  gates: ProcessGate[]
}

Phases

Phases group related activities:

interface ProcessPhase {
  id: string
  name: string
  description?: string
  order: number
  tasks: ProcessTask[]
  requiredApprovals?: string[]  // Human participant IDs
  parallelExecution?: boolean
  estimatedDuration?: string    // e.g., "2-3 days"
}

Tasks

Tasks are the atomic units of work:

interface ProcessTask {
  id: string
  name: string
  description?: string
  assignee: string              // Agent or human ID
  dependencies?: string[]       // Task IDs
  requiredApprovals?: string[]  // Human participant IDs
  tools?: string[]              // Tools needed
  artifacts?: string[]          // Expected outputs
}

Gates

Gates are checkpoints between phases:

interface ProcessGate {
  id: string
  name: string
  beforePhase: string
  type: 'approval' | 'condition' | 'manual'
  approvers?: string[]
  condition?: string
}

RAID Model

The RAID model extends RACI for AI-driven processes:

Role	Description	Typical Actor
Responsible	Executes the work	AI Agent
Approver	Must approve before proceeding	Customer stakeholder
Informed	Notified of progress	Project managers
Delegator	Can assign work to others	Internal support

Assigning RAID Roles

const enterpriseDeploymentParticipants = {
  customer_it_admin: {
    id: 'customer_it_admin',
    name: 'Customer IT Administrator',
    role: 'approver',
    raidRole: 'approver',
    requiredApprovals: [
      'sso_config_review',
      'scim_provisioning_review',
      'production_deployment'
    ],
    notificationPreferences: {
      email: true,
      slack: false,
      inApp: true
    }
  },
  customer_ciso: {
    id: 'customer_ciso',
    name: 'Customer CISO',
    role: 'approver',
    raidRole: 'approver',
    requiredApprovals: [
      'security_review',
      'compliance_sign_off'
    ]
  },
  deeployd_support: {
    id: 'deeployd_support',
    name: 'Deeployd Support',
    role: 'delegator',
    raidRole: 'delegator',
    canDelegate: true
  }
}

External Participants

External participants are customer stakeholders who interact via magic links:

Magic Link Authentication

// Generate magic link for external participant
const magicLink = await client.processes.createExternalParticipantLink({
  processInstanceId: 'proc-123',
  participantId: 'customer_it_admin',
  email: 'admin@customer.com',
  expiresIn: '7d',
  permissions: ['view', 'approve', 'comment']
})

// Returns URL like:
// https://app.deeployd.com/external/approve?token=eyJhbGc...

External Participant Portal

External participants see:

• Current phase and progress
• Pending approvals requiring their action
• Artifacts and documentation
• Comment threads
• Decision history

Creating Processes

Define Process Structure

const enterpriseDeploymentProcess: ProcessDefinition = {
  id: 'enterprise_sso_deployment',
  name: 'Enterprise SSO Deployment',
  version: '1.0.0',
  description: 'Complete SSO and SCIM deployment for enterprise customers',

  phases: [
    {
      id: 'discovery',
      name: 'Discovery & Planning',
      order: 1,
      description: 'Gather requirements and plan deployment',
      tasks: [
        {
          id: 'requirements_gathering',
          name: 'Gather SSO Requirements',
          assignee: 'sso_agent',
          artifacts: ['sso_requirements_doc']
        },
        {
          id: 'scim_planning',
          name: 'Plan SCIM Provisioning',
          assignee: 'scim_agent',
          artifacts: ['scim_mapping_doc']
        }
      ],
      estimatedDuration: '1-2 days'
    },
    {
      id: 'configuration',
      name: 'Configuration',
      order: 2,
      requiredApprovals: ['customer_it_admin'],
      tasks: [
        {
          id: 'sso_setup',
          name: 'Configure SSO',
          assignee: 'sso_agent',
          dependencies: ['requirements_gathering'],
          requiredApprovals: ['customer_it_admin']
        },
        {
          id: 'scim_setup',
          name: 'Configure SCIM',
          assignee: 'scim_agent',
          dependencies: ['scim_planning']
        }
      ],
      parallelExecution: true,
      estimatedDuration: '2-3 days'
    },
    {
      id: 'security_review',
      name: 'Security Review',
      order: 3,
      requiredApprovals: ['customer_ciso'],
      tasks: [
        {
          id: 'security_assessment',
          name: 'Security Assessment',
          assignee: 'security_agent',
          requiredApprovals: ['customer_ciso']
        }
      ],
      estimatedDuration: '1-2 days'
    },
    {
      id: 'production',
      name: 'Production Deployment',
      order: 4,
      requiredApprovals: ['customer_it_admin', 'customer_ciso'],
      tasks: [
        {
          id: 'prod_deployment',
          name: 'Deploy to Production',
          assignee: 'deployment_lead',
          requiredApprovals: ['customer_it_admin']
        },
        {
          id: 'validation',
          name: 'Production Validation',
          assignee: 'integration_agent'
        }
      ],
      estimatedDuration: '1 day'
    }
  ],

  agents: {
    deployment_lead: {
      templateId: 'enterprise-deployment-lead',
      role: 'coordinator'
    },
    sso_agent: {
      templateId: 'sso-specialist',
      role: 'specialist'
    },
    scim_agent: {
      templateId: 'scim-specialist',
      role: 'specialist'
    },
    security_agent: {
      templateId: 'security-reviewer',
      role: 'specialist'
    },
    integration_agent: {
      templateId: 'integration-specialist',
      role: 'specialist'
    }
  },

  humans: {
    customer_it_admin: {
      role: 'approver',
      raidRole: 'approver'
    },
    customer_ciso: {
      role: 'approver',
      raidRole: 'approver'
    },
    deeployd_support: {
      role: 'delegator',
      raidRole: 'delegator'
    }
  },

  gates: [
    {
      id: 'config_approval_gate',
      name: 'Configuration Approval',
      beforePhase: 'security_review',
      type: 'approval',
      approvers: ['customer_it_admin']
    },
    {
      id: 'security_approval_gate',
      name: 'Security Sign-off',
      beforePhase: 'production',
      type: 'approval',
      approvers: ['customer_ciso']
    }
  ]
}

Start Process Instance

const instance = await client.processes.start({
  processId: 'enterprise_sso_deployment',
  name: 'Acme Corp SSO Deployment',
  context: {
    customerName: 'Acme Corporation',
    customerDomain: 'acme.com',
    idpType: 'okta',
    userCount: 5000
  },
  externalParticipants: [
    {
      participantId: 'customer_it_admin',
      email: 'it-admin@acme.com',
      name: 'John Smith'
    },
    {
      participantId: 'customer_ciso',
      email: 'ciso@acme.com',
      name: 'Jane Doe'
    }
  ]
})

console.log(instance.id)     // proc-inst-123
console.log(instance.status) // 'running'
console.log(instance.phase)  // 'discovery'

Team Templates

Team templates define the agent team for a process:

const enterpriseDeploymentTeamTemplate: TeamTemplate = {
  name: 'Enterprise Deployment Team',
  category: 'operations',
  description: 'Complete team for enterprise SSO/SCIM deployments',

  agents: [
    {
      id: 'deployment_lead',
      name: 'Enterprise Deployment Lead',
      role: 'Deployment Project Manager',
      systemPrompt: `You are the deployment lead responsible for...`,
      tools: [
        { name: 'project_status' },
        { name: 'escalate_to_human' },
        { name: 'delegate_to_agent' }
      ],
      hierarchy: {
        level: 1,
        canDelegate: true,
        subordinates: ['sso_agent', 'scim_agent', 'security_agent', 'integration_agent']
      }
    },
    {
      id: 'sso_agent',
      name: 'SSO Specialist',
      role: 'SSO Configuration Expert',
      systemPrompt: `You are an SSO specialist...`,
      tools: [
        { name: 'configure_saml' },
        { name: 'configure_oidc' },
        { name: 'test_sso_flow' }
      ],
      hierarchy: {
        level: 2,
        reportsTo: 'deployment_lead'
      }
    }
    // ... more agents
  ],

  sharedOnboarding: {
    properties: {
      customerName: { type: 'string', title: 'Customer Name' },
      customerDomain: { type: 'string', title: 'Customer Domain' },
      idpType: { type: 'string', enum: ['okta', 'azure_ad', 'google', 'other'] },
      deploymentTimeline: { type: 'string', title: 'Target Timeline' }
    },
    required: ['customerName', 'customerDomain', 'idpType']
  },

  orchestration: {
    mode: 'hierarchical',
    entryAgentId: 'deployment_lead',
    escalationPath: ['deployment_lead', 'deeployd_support']
  },

  interactionRules: [
    {
      id: 'security_escalation',
      trigger: 'security_concern_detected',
      action: 'escalate',
      target: 'security_agent',
      priority: 'high'
    },
    {
      id: 'customer_approval_required',
      trigger: 'phase_gate_reached',
      action: 'request_approval',
      target: 'external_participant',
      timeout: '48h'
    }
  ]
}

Shared Storage

Process instances have shared storage accessible to all agents:

// Store artifact
await client.processes.storeArtifact('proc-inst-123', {
  key: 'sso_requirements',
  type: 'document',
  content: {
    idpType: 'okta',
    attributes: ['email', 'firstName', 'lastName', 'department'],
    groups: ['engineering', 'sales', 'support']
  },
  metadata: {
    createdBy: 'sso_agent',
    phase: 'discovery'
  }
})

// Retrieve artifact
const artifact = await client.processes.getArtifact('proc-inst-123', 'sso_requirements')

// List all artifacts
const artifacts = await client.processes.listArtifacts('proc-inst-123', {
  phase: 'discovery',
  type: 'document'
})

Approval Workflow

Request Approval

// Agent requests approval
await client.processes.requestApproval('proc-inst-123', {
  taskId: 'sso_setup',
  approverIds: ['customer_it_admin'],
  title: 'SSO Configuration Review',
  description: 'Please review the SSO configuration before we proceed',
  artifacts: ['sso_config_summary'],
  expiresIn: '48h'
})

External Participant Approves

External participants receive email with magic link:

Subject: Approval Required: SSO Configuration Review

Hi John,

The SSO configuration for your deployment is ready for review.

[Review and Approve] <-- Magic link button

This link expires in 48 hours.

Handle Approval Response

// Listen for approval events
client.processes.onApprovalResponse('proc-inst-123', (response) => {
  console.log({
    taskId: response.taskId,
    approved: response.approved,
    approver: response.approverEmail,
    comments: response.comments,
    timestamp: response.timestamp
  })

  if (response.approved) {
    // Continue to next phase
  } else {
    // Handle rejection, notify agents
  }
})

Process Monitoring

Get Process Status

const status = await client.processes.getStatus('proc-inst-123')

console.log({
  currentPhase: status.currentPhase,
  completedPhases: status.completedPhases,
  pendingApprovals: status.pendingApprovals,
  blockedTasks: status.blockedTasks,
  progress: status.progressPercent,
  estimatedCompletion: status.estimatedCompletion
})

Phase Timeline

const timeline = await client.processes.getTimeline('proc-inst-123')

for (const phase of timeline.phases) {
  console.log({
    name: phase.name,
    status: phase.status,
    startedAt: phase.startedAt,
    completedAt: phase.completedAt,
    tasks: phase.tasks.map(t => ({
      name: t.name,
      status: t.status,
      assignee: t.assignee
    }))
  })
}

Audit Trail

const auditLog = await client.processes.getAuditLog('proc-inst-123', {
  limit: 100,
  types: ['approval', 'phase_transition', 'task_completion']
})

for (const entry of auditLog.entries) {
  console.log({
    timestamp: entry.timestamp,
    type: entry.type,
    actor: entry.actor,
    action: entry.action,
    details: entry.details
  })
}

API Reference

Process Endpoints

Endpoint	Method	Description
/api/processes	GET	List process definitions
/api/processes/:id	GET	Get process definition
/api/processes/:id/instances	POST	Start new instance
/api/processes/instances/:id	GET	Get instance status
/api/processes/instances/:id/phase	POST	Advance to next phase
/api/processes/instances/:id/approvals	GET	List pending approvals
/api/processes/instances/:id/artifacts	GET/POST	Manage artifacts

Team Template Endpoints

Endpoint	Method	Description
/api/team-templates	GET	List templates
/api/team-templates/:id	GET	Get template
/api/team-templates/:id/instantiate	POST	Create team from template

Best Practices

1. Clear Phase Boundaries

Define phases with clear entry/exit criteria:

phases: [
  {
    id: 'configuration',
    entryConditions: ['requirements_approved'],
    exitConditions: ['all_tasks_complete', 'config_approved'],
    requiredApprovals: ['customer_it_admin']
  }
]

2. Reasonable Approval Timeouts

Set appropriate timeouts based on stakeholder availability:

// Standard business approval
timeout: '48h'

// Urgent security decision
timeout: '4h'
escalateAfter: '2h'

// Complex compliance review
timeout: '7d'
reminders: ['24h', '72h']

3. Comprehensive Shared Context

Ensure agents have the context they need:

sharedOnboarding: {
  properties: {
    // Business context
    customerName: { type: 'string' },
    contractTier: { type: 'string', enum: ['standard', 'enterprise', 'strategic'] },

    // Technical context
    idpType: { type: 'string' },
    existingIntegrations: { type: 'array', items: { type: 'string' } },

    // Deployment context
    targetGoLive: { type: 'string', format: 'date' },
    stakeholderContacts: { type: 'object' }
  }
}

4. Graceful Error Handling

Handle failures without blocking the entire process:

errorHandling: {
  taskFailure: 'retry_with_escalation',
  maxRetries: 3,
  escalateTo: 'deployment_lead',
  notifyParticipants: ['deeployd_support']
}

---

Next: Learn about Teams for configuring multi-agent collaboration.