> ## 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

**1. 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
});
```

**2. With Configuration**

See the sections below for advanced options.

***

## 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

> [card] [Hooks Manager](https://praison.ai/docs/js/hooks-manager.md)
>
> Hooks Manager

> [card] [Callbacks](https://praison.ai/docs/js/callbacks.md)
>
> Callbacks


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.