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

# Events

> React to agent lifecycle events

Agents emit events you can listen to - track progress, log activity, and extend behavior.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "Event System"
        A[🤖 Agent] --> B[📡 Events]
        B --> C[📝 Logger]
        B --> D[📊 Analytics]
        B --> E[🔔 Alerts]
    end

    classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef tool fill:#189AB4,stroke:#7C90A0,color:#fff
    class A agent
    class B,C,D,E tool
    classDef agent fill:#8B0000,color:#fff
    classDef tool fill:#189AB4,color:#fff

```

> [!NOTE]
>
> This page covers the **`AgentEventBus`** — a publish/subscribe hook system for agent lifecycle (`start`, `message`, `complete`, `error`). For the **per-turn structured event stream** used to render tool calls and text deltas in real time, see [Streaming Events](https://praison.ai/docs/js/streaming-events.md).

## Quick Start

**1. Simple Usage**

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

const agent = new Agent({
  instructions: 'You are a helpful assistant'
});

agent.on('message', (event) => {
  console.log('Agent said:', event.content);
});

agent.on('tool_call', (event) => {
  console.log('Tool used:', event.name);
});

await agent.chat('Search for weather');
```

**2. With Configuration**

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
agent.on('*', (event) => {
  console.log(`[${event.type}]`, event.data);
});
```

***

## User Interaction Flow

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant User
    participant Agent
    participant Handler as Event Handler
    
    User->>Agent: "Search for weather"
    Agent->>Handler: emit('start')
    Agent->>Handler: emit('tool_call', search)
    Agent->>Handler: emit('message', response)
    Agent->>Handler: emit('complete')
    Agent-->>User: "The weather is..."
```

***

## Configuration Levels

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
// Level 1: Method - Simple listener
agent.on('message', (e) => console.log(e));

// Level 2: Array - Multiple events
agent.on(['start', 'complete'], (e) => {
  console.log(`${e.type} at ${e.timestamp}`);
});

// Level 3: Instance - Event bus
import { AgentEventBus } from 'praisonai';

const bus = new AgentEventBus();

bus.subscribe('agent.*', (event) => {
  sendToAnalytics(event);
});

const agent = new Agent({ eventBus: bus });
```

***

## Event Types

| Event | When |
| - | - |
| `start` | Agent begins processing |
| `message` | Agent produces output |
| `tool_call` | Agent calls a tool |
| `error` | Something goes wrong |
| `complete` | Agent finishes |

***

## API Reference

> [card] [Events Module](https://praison.ai/docs/sdk/reference/typescript/modules/events.md)
>
> Complete events module

> [card] [AgentEventBus](https://praison.ai/docs/sdk/reference/typescript/classes/AgentEventBus.md)
>
> Event bus class

***

## Best Practices

> [accordion] Log important events
>
> Track tool calls and errors for debugging.

> [accordion] Use wildcards sparingly
>
> Subscribe to specific events for better performance.

> [accordion] Handle errors
>
> Always listen for 'error' events in production.

***

## Related

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

> [card] [PubSub](https://praison.ai/docs/js/pubsub.md)
>
> Publish-subscribe


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