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:

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.

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.

def on_started(event):

    print("Agent execution started.")


agent.events.subscribe(
    on_started,
)

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

---

Example

def log_event(event):

    print(type(event).__name__)


agent.events.subscribe(
    log_event,
)

agent.chat(
    "Hello!"
)

Example output:

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:

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.

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.

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:

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.