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

# 02.6 events

# Events

BindAI includes an event system that allows applications to observe and react to important actions during execution.

Events make it easy to build:

* Logging
* Monitoring
* Analytics
* Auditing
* Metrics
* Notifications
* Debugging tools

Instead of modifying the framework itself, you can subscribe to events and execute your own logic whenever something important happens.

***

# Why Events?

Every AI request involves multiple steps.

For example:

```text id="kd6ejb" theme={null}
User Request
      │
      ▼
Agent Started
      │
      ▼
Model Request
      │
      ▼
Model Response
      │
      ▼
Tool Execution
      │
      ▼
Agent Finished
```

Each of these stages can emit an event.

Applications can listen for these events without changing the execution pipeline.

***

# Event Bus

Every agent contains its own event bus.

```python id="b7zjlwm" theme={null}
agent.events
```

The event bus is responsible for publishing execution events.

***

# Built-in Events

BindAI publishes several built-in events.

| Event              | Description                      |
| ------------------ | -------------------------------- |
| AgentStartedEvent  | Agent execution begins           |
| AgentFinishedEvent | Agent execution completes        |
| ModelRequestEvent  | Request sent to the model        |
| ModelResponseEvent | Response received from the model |
| ToolExecutedEvent  | A tool finishes execution        |

Additional events may be introduced as new framework features are added.

***

# Subscribing to Events

Register a listener using the event bus.

```python id="5egdnm" theme={null}
def on_started(event):

    print("Agent execution started.")


agent.events.subscribe(
    on_started,
)
```

Whenever the agent publishes an event, the subscriber is called.

***

# Example

```python id="8mjkkg" theme={null}
def log_event(event):

    print(type(event).__name__)


agent.events.subscribe(
    log_event,
)

agent.chat(
    "Hello!"
)
```

Example output:

```text id="zl7tgb" theme={null}
AgentStartedEvent

ModelRequestEvent

ModelResponseEvent

AgentFinishedEvent
```

***

# Model Events

Two of the most useful events occur around model generation.

## ModelRequestEvent

Published immediately before the provider receives the request.

Useful for:

* request logging
* prompt inspection
* debugging
* analytics

***

## ModelResponseEvent

Published after the language model returns a response.

Useful for:

* latency measurement
* response logging
* output validation
* monitoring

***

# Tool Events

Whenever an agent executes a tool, BindAI publishes:

```text id="9slk8l" theme={null}
ToolExecutedEvent
```

This event can be used to:

* measure tool usage
* collect statistics
* audit external API calls
* monitor execution frequency

***

# Agent Lifecycle Events

Every execution publishes lifecycle events.

```text id="7wp2yq" theme={null}
AgentStartedEvent

↓

...

↓

AgentFinishedEvent
```

These are commonly used for:

* timing execution
* measuring throughput
* tracking active requests
* monitoring production systems

***

# Event Flow

A typical execution looks like this.

```text id="twst8g" theme={null}
AgentStartedEvent

        │

        ▼

ModelRequestEvent

        │

        ▼

ModelResponseEvent

        │

        ▼

ToolExecutedEvent
(optional)

        │

        ▼

AgentFinishedEvent
```

Some events only occur when required.

For example, `ToolExecutedEvent` is only published if the language model invokes a tool.

***

# Custom Events

Applications can publish their own events.

Example:

```python id="9nq5wg" theme={null}
agent.events.publish(
    MyCustomEvent()
)
```

This allows teams to integrate BindAI into existing event-driven architectures.

***

# Common Use Cases

The event system is useful for many production scenarios.

Examples include:

* Logging every prompt
* Measuring response times
* Counting model usage
* Monitoring tool execution
* Recording audit trails
* Sending notifications
* Exporting metrics to monitoring platforms

Because events are independent of the execution engine, these features can be added without modifying agents or workflows.

***

# Events vs Hooks

BindAI provides both events and hooks.

| Events                  | Hooks                           |
| ----------------------- | ------------------------------- |
| Broadcast notifications | Execute custom logic            |
| Multiple subscribers    | Agent-specific callbacks        |
| Observe execution       | Modify behavior after execution |
| Suitable for monitoring | Suitable for application logic  |

Events are primarily intended for observing execution.

Hooks are intended for extending agent behavior.

***

# Best Practices

* Keep event handlers lightweight.
* Avoid blocking execution inside subscribers.
* Use events for logging and monitoring.
* Use hooks or middleware when execution behavior needs to change.
* Keep event listeners independent of business logic.

***

# Next Steps

Continue with **Execution** to learn how BindAI processes requests internally through its execution pipeline.