> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Workflow Hooks

> Lifecycle hooks for workflow execution

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    User([User]) --> Agent[Agent]
    Agent --> Output([Output])

    classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef tool fill:#189AB4,stroke:#7C90A0,color:#fff

    class Agent agent
    class User,Output tool
    classDef agent fill:#8B0000,color:#fff
    classDef tool fill:#189AB4,color:#fff
```

# Workflow Hooks

Add lifecycle hooks to workflows for monitoring, logging, and custom logic.

## Quick Start

<Steps>
  <Step title="Simple Usage">
    ```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    import { AgentFlow, WorkflowHooksConfig } from 'praisonai';

    const hooks: WorkflowHooksConfig = {
      onWorkflowStart: (workflow, input) => {
        console.log(`Starting: ${workflow.name}`);
      },
      
      onStepStart: (stepName, context) => {
        console.log(`Step ${context.stepIndex + 1}/${context.totalSteps}: ${stepName}`);
      },
      
      onStepComplete: (stepName, result) => {
        console.log(`${stepName} completed`);
      },
      
      onWorkflowComplete: (workflow, result) => {
        console.log(`Workflow done!`);
      }
    };

    const flow = new AgentFlow({
      name: 'my-workflow',
      hooks
    });
    ```
  </Step>

  <Step title="With Configuration">
    See the sections below for advanced options.
  </Step>
</Steps>

***

## Basic Usage

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import { AgentFlow, WorkflowHooksConfig } from 'praisonai';

const hooks: WorkflowHooksConfig = {
  onWorkflowStart: (workflow, input) => {
    console.log(`Starting: ${workflow.name}`);
  },
  
  onStepStart: (stepName, context) => {
    console.log(`Step ${context.stepIndex + 1}/${context.totalSteps}: ${stepName}`);
  },
  
  onStepComplete: (stepName, result) => {
    console.log(`${stepName} completed`);
  },
  
  onWorkflowComplete: (workflow, result) => {
    console.log(`Workflow done!`);
  }
};

const flow = new AgentFlow({
  name: 'my-workflow',
  hooks
});
```

## All Hooks

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
interface WorkflowHooksConfig {
  // Workflow lifecycle
  onWorkflowStart?: (workflow, input) => void | Promise<void>;
  onWorkflowComplete?: (workflow, result) => void | Promise<void>;
  onWorkflowError?: (workflow, error) => void | Promise<void>;
  
  // Step lifecycle
  onStepStart?: (stepName, context) => void | Promise<void>;
  onStepComplete?: (stepName, result, context) => void | Promise<void>;
  onStepError?: (stepName, error, context) => void | Promise<void>;
}
```

## Step Context

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
interface StepContext {
  stepName: string;
  stepIndex: number;      // 0-based
  totalSteps: number;
  input: any;             // Current step input
  previousResults: Record<string, any>;
}
```

## Pre-built Hooks

### Logging Hooks

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import { createLoggingWorkflowHooks } from 'praisonai';

const hooks = createLoggingWorkflowHooks((msg, data) => {
  console.log(`[Workflow] ${msg}`, data);
});

// Output:
// [Workflow] Workflow "my-workflow" started { input: ... }
// [Workflow] Step "step1" started (1/3)
// [Workflow] Step "step1" completed { result: ... }
// ...
```

### Timing Hooks

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import { createTimingWorkflowHooks } from 'praisonai';

const { hooks, getTimings } = createTimingWorkflowHooks();

const flow = new AgentFlow({ hooks });
await flow.run(input);

const timings = getTimings();
console.log(timings);
// {
//   workflow_abc123: 5432,      // Total ms
//   step_research: 2100,
//   step_write: 3200
// }
```

## WorkflowHooksExecutor

For programmatic hook execution:

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import { WorkflowHooksExecutor, createWorkflowHooks } from 'praisonai';

const executor = createWorkflowHooks({
  onWorkflowStart: (wf, input) => console.log('Start'),
  onStepComplete: (name, result) => console.log(`${name} done`)
}, true); // logging = true

// Check if hooks configured
if (executor.hasHooks()) {
  console.log('Hooks:', executor.getConfiguredHooks());
}

// Execute manually
await executor.onWorkflowStart(workflowRef, input);
await executor.onStepComplete('step1', result, context);
```

## Error Handling

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
const hooks: WorkflowHooksConfig = {
  onStepError: async (stepName, error, context) => {
    console.error(`Step ${stepName} failed:`, error.message);
    
    // Log to external service
    await logToSentry({
      step: stepName,
      error: error.message,
      context
    });
  },
  
  onWorkflowError: async (workflow, error) => {
    console.error(`Workflow ${workflow.name} failed`);
    
    // Send alert
    await sendAlert({
      workflow: workflow.id,
      error: error.message
    });
  }
};
```

## Async Hooks

All hooks support async functions:

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
const hooks: WorkflowHooksConfig = {
  onStepComplete: async (stepName, result) => {
    // Save to database
    await db.insert('step_results', {
      step: stepName,
      result,
      timestamp: new Date()
    });
  }
};
```

## Related

<CardGroup cols={2}>
  <Card title="Hooks Manager" icon="book" href="/docs/js/hooks-manager">Hooks Manager</Card>
  <Card title="Callbacks" icon="robot" href="/docs/js/callbacks">Callbacks</Card>
</CardGroup>