Events

BindAI provides event and callback mechanisms for observing and extending agent execution. There are two related but distinct event mechanisms:

Agent callbacks — Agent.on() and Agent.emit() provide lightweight named callbacks directly on an agent.
Core events — EventBus provides a structured event-publishing mechanism used by BindAI runtime components and integrations.

These mechanisms are useful for:

Logging
Monitoring
Analytics
Notifications
Debugging
Auditing
Custom integrations
Automation triggers
Application-specific execution behavior

Agent Events

The Agent class provides a lightweight named-event API. Register a callback with:

agent.on(event, callback)

Emit an event with:

agent.emit(event, *args)

For example:

def logger(message):
    print("Event received:", message)


agent.on("message", logger)

agent.emit(
    "message",
    "Hello from BindAI",
)

The callback receives the positional arguments supplied to emit(). Agent events are primarily useful for application-level callbacks and lightweight integrations.

Registering Callbacks

Use Agent.on() to register a callback for a named event.

def on_complete(result):
    print("Completed:", result)


agent.on(
    "task_completed",
    on_complete,
)

The first argument is the event name. The second argument is the callback that should run when the event is emitted. Multiple callbacks can be registered for the same event.

def audit(result):
    print("Audit:", result)


def metrics(result):
    print("Metrics:", result)


agent.on("execution", audit)
agent.on("execution", metrics)

When the event is emitted, the registered callbacks are invoked.

Emitting Events

Use Agent.emit() to emit a named event.

agent.emit(
    "task_completed",
    "report-123",
)

Callbacks registered for that event receive the emitted arguments. For example:

def on_task_completed(task_id):
    print("Completed:", task_id)


agent.on(
    "task_completed",
    on_task_completed,
)

agent.emit(
    "task_completed",
    "report-123",
)

The event name and callback argument contract should remain consistent within an application.

Custom Events

Agent event names are strings, allowing applications to define their own event names.

def on_status(status):
    print("Status:", status)


agent.on(
    "status_changed",
    on_status,
)

agent.emit(
    "status_changed",
    "completed",
)

Use descriptive event names that clearly communicate what happened. Application-specific event names should be documented together with their callback arguments.

Event Arguments

Agent.emit() accepts positional arguments after the event name. For example:

agent.emit(
    "task_completed",
    "report-123",
    True,
)

A callback can receive those arguments:

def on_task_completed(task_id, success):
    print(task_id, success)


agent.on(
    "task_completed",
    on_task_completed,
)

Output:

report-123 True

The callback signature must match the arguments emitted by the application.

Core EventBus

BindAI also provides a core EventBus abstraction.

from bindai_core.events import EventBus

An event bus allows components to subscribe to named events and publish structured Event objects. Create an event bus:

bus = EventBus()

Subscribe to an event:

bus.subscribe(
    "my.event",
    handler,
)

Publish an event:

bus.publish(event)

This mechanism is separate from the Agent.on() / Agent.emit() callback API. The event bus is intended for communication between BindAI components and integrations that need a structured event boundary.

Event Objects

Core events are represented by Event objects.

from bindai_core.events import Event


class MyEvent(Event):
    @property
    def name(self) -> str:
        return "my.event"

An event can carry a payload:

event = MyEvent(
    payload={
        "message": "hello",
    },
)

The base event also provides framework-managed event metadata such as an identifier and timestamp. Applications can therefore use structured event objects instead of passing arbitrary positional arguments between core components.

Subscribing to EventBus Events

Use EventBus.subscribe() to register an event handler.

def handle_event(event):
    print(event.name)
    print(event.payload)


bus.subscribe(
    "my.event",
    handle_event,
)

The handler receives the published Event object. Unlike Agent.on(), the callback does not receive arbitrary positional arguments supplied by the publisher. Instead, it receives the structured event.

Publishing EventBus Events

Publish an event with EventBus.publish().

bus.publish(
    MyEvent(
        payload={
            "message": "hello",
        },
    )
)

The event bus finds handlers registered for the event name and invokes them. The event bus also supports a wildcard subscription:

bus.subscribe(
    "*",
    handle_event,
)

A wildcard handler receives published events regardless of their specific event name.

Unsubscribing

EventBus handlers can be removed with unsubscribe().

bus.unsubscribe(
    "my.event",
    handle_event,
)

This is useful when an integration or component no longer needs to receive events. A handler should generally be unsubscribed when the component owning the subscription is disposed or no longer active.

EventBus Handler Isolation

The core EventBus isolates handler failures from the publishing component. If a handler raises an exception, the event bus logs the failure rather than allowing the handler exception to interrupt the remaining event handling. Conceptually:

EventBus.publish()

      |

      +----> Handler A
      |
      +----> Handler B
      |
      +----> Handler C

If one handler fails, the event bus records the failure and continues processing the other handlers. This is useful for optional integrations such as logging, metrics, notifications, and automation. Event handlers should nevertheless be kept small and reliable.

Agent EventBus

Each Agent has an event bus available through:

agent.events

For example:

def handle_event(event):
    print(
        event.name,
        event.payload,
    )


agent.events.subscribe(
    "tool.executed",
    handle_event,
)

The agent can publish framework events through this event bus as part of its execution behavior. This provides a structured event boundary for integrations that need to observe agent activity.

Agent Callbacks vs EventBus

The two mechanisms serve different purposes.

Mechanism	Purpose
`agent.on()`	Register a callback for a named agent event
`agent.emit()`	Emit a lightweight named agent event
`agent.events.subscribe()`	Subscribe to structured core events
`agent.events.publish()`	Publish a structured `Event`
`agent.events.unsubscribe()`	Remove a core event handler

A useful rule is:

Use Agent.on() / Agent.emit() for lightweight application-level callbacks.
Use EventBus when components need to communicate through structured BindAI events.
Use automation triggers when an event should initiate an automation action.

Agent Lifecycle

Agent execution also has lifecycle behavior. The execution engine publishes framework events such as agent-started and agent-finished events through the core event infrastructure. Agent execution also exposes lifecycle callback methods:

agent.before_run(...)
agent.after_run(...)
agent.on_error(...)

These mechanisms should not be treated as interchangeable. Lifecycle callbacks are directly associated with execution lifecycle behavior, while the event bus provides a decoupled event boundary for event consumers. Do not assume undocumented event names or callback signatures.

Tool Events

Tool execution can also produce core events. The agent publishes a ToolExecutedEvent through its event bus after a tool execution. For example:

def on_tool(event):
    print(
        "Tool executed:",
        event.tool_name,
    )


agent.events.subscribe(
    "tool.executed",
    on_tool,
)

The exact event name should be obtained from the corresponding BindAI event type rather than assumed in application code. Tool events are useful for integrations such as:

Logging
Auditing
Metrics
Monitoring
Automation
Debugging

For detailed tool result behavior, see the Tool Results documentation.

Events and Automation

The core event system provides the foundation for event-driven automation. BindAI’s Automation package provides EventTrigger, which can listen to an EventBus and invoke a target when a matching event is published. The relationship is:

BindAI Component
       |
       v
   EventBus
       |
       v
  EventTrigger
       |
       v
 Automation Target

For example:

from bindai_automation import EventTrigger


def handle_event(event):
    print(
        "Automation triggered:",
        event.payload,
    )


trigger = EventTrigger(
    bus=agent.events,
    event_name="my.event",
    target=handle_event,
)

trigger.attach()

Once attached, the trigger listens for the configured event. When the matching event is published:

agent.events.publish(
    MyEvent(
        payload={
            "message": "hello",
        },
    )
)

the automation target is invoked. This creates a clean boundary between event production and automation behavior.

Enabling and Disabling Automation Triggers

EventTrigger supports temporary enable/disable behavior.

trigger.disable()

While disabled, matching events do not invoke the target. It can be enabled again:

trigger.enable()

This is useful when an automation should remain attached to an event source but temporarily stop reacting to events.

Detaching Automation Triggers

A trigger can be detached from its event source:

trigger.detach()

After detaching, the trigger no longer receives events from that event bus. This allows applications to manage the lifetime of automation subscriptions explicitly.

Trigger Registry

BindAI Automation also provides TriggerRegistry.

from bindai_automation import TriggerRegistry

registry = TriggerRegistry()

Triggers can be registered by name:

registry.register(
    "notification",
    trigger,
)

They can then be retrieved:

trigger = registry.get(
    "notification",
)

The registry provides named management of automation triggers. It is useful when an application needs to manage multiple triggers independently.

Event-Driven Architecture

The event and automation layers can be combined into a larger architecture:

                    +----------------+
                    | BindAI Agent   |
                    +-------+--------+
                            |
                            v
                       Core Event
                            |
                            v
                        EventBus
                            |
             +--------------+--------------+
             |              |              |
             v              v              v
          Logging        Metrics       EventTrigger
                                           |
                                           v
                                      Automation
                                           |
                              +------------+------------+
                              |            |            |
                              v            v            v
                           Workflow     Notification   Service

The important principle is that the component producing an event does not need to know which consumers will react to it. This reduces coupling between agents, integrations, monitoring systems, and automation.

Events and Workflows

Events can also act as boundaries around larger application workflows. For example:

Agent
  |
  v
EventBus
  |
  v
EventTrigger
  |
  v
Workflow
  |
  +---- Condition
  |
  +---- Agent
  |
  +---- Human Task
  |
  v
Workflow Result

Events should generally initiate or notify workflows rather than contain complex orchestration logic themselves. For explicit multi-step orchestration, use BindAI workflows.

Events and External Integrations

Events can connect BindAI execution to external application services. For example:

Agent
  |
  v
EventBus
  |
  +---- Logger
  |
  +---- Metrics
  |
  +---- Notification
  |
  +---- Automation
  |
  +---- External Integration

External service calls should generally be delegated to dedicated application components or BindAI connections rather than implemented as large event handlers.

Keeping Event Handlers Lightweight

Event handlers should generally perform small, focused operations. Good event handlers include:

Logging
Updating counters
Recording metrics
Creating audit records
Triggering lightweight notifications
Scheduling background work
Passing work to another application component

Avoid putting large amounts of business logic directly inside event callbacks. For complex processing, use an event as the boundary and delegate the work to another component.

Error Handling in Event Handlers

Event handlers are application code and can introduce their own errors. For EventBus handlers, BindAI isolates handler exceptions so that one failing handler does not prevent the event bus from continuing to other handlers. Applications should still implement appropriate logging and error handling within handlers when the operation itself is important. For example:

def handle_event(event):
    try:
        process_event(event)
    except Exception as exc:
        logger.exception(
            "Event processing failed: %s",
            exc,
        )

Optional monitoring or notification behavior should not unnecessarily complicate the primary agent execution path.

Event Naming

Use descriptive event names. Framework event names should come from the corresponding BindAI event types. For application-specific agent events, use names that clearly describe what happened:

task_completed
execution_started
execution_failed
status_changed

For core EventBus events, prefer stable event names that identify the event type. Avoid ambiguous names that make it difficult for subscribers to understand what the event represents.

Hooks and Callbacks

Events are not the only extension mechanism available to agents. Agents also expose hooks and lifecycle callbacks. The hook() method allows application code to register hook behavior:

def custom_hook(context):
    print("Hook executed")


agent.hook(custom_hook)

Agents also provide lifecycle callback methods such as:

agent.before_run(...)
agent.after_run(...)
agent.on_error(...)

These mechanisms are useful for execution-related behavior. The exact hook contract depends on the execution mechanism using the hook, so applications should follow the callback interface provided by the relevant BindAI API.

Events vs Hooks

Events and hooks serve related but different purposes.

Mechanism	Primary purpose
`Agent.on()`	Agent-level named callback
`Agent.emit()`	Agent-level named event emission
`EventBus`	Structured event communication
`EventTrigger`	Turn an event into an automation action
`hook()`	Attach reusable execution-related behavior
Lifecycle callbacks	React directly to execution lifecycle stages

A simple rule is:

Use agent callbacks for lightweight local callbacks.
Use core events for structured communication between components.
Use automation triggers when events should initiate actions.
Use hooks for reusable execution-related behavior.
Use workflows for explicit multi-step orchestration.

Testing Events

Event behavior should be tested independently from external services. A simple agent callback test can verify that a callback receives emitted values:

received = []


def callback(message):
    received.append(message)


agent.on(
    "message",
    callback,
)

agent.emit(
    "message",
    "hello",
)

assert received == ["hello"]

A core event bus can be tested independently:

received = []


def callback(event):
    received.append(event)


bus.subscribe(
    "my.event",
    callback,
)

bus.publish(
    MyEvent(
        payload={
            "message": "hello",
        },
    )
)

assert len(received) == 1
assert received[0].payload["message"] == "hello"

Automation triggers can then be tested at the integration boundary:

EventBus
   |
   v
EventTrigger
   |
   v
Target

Tests should verify:

Event registration
Event emission
EventBus subscription
EventBus publication
Event arguments or payloads
Multiple subscribers
Handler isolation
Trigger attachment
Trigger detachment
Trigger enable/disable behavior

Avoid requiring external services when testing the core event mechanism.

Events and Observability

Events provide useful building blocks for observability. Applications can connect events to:

Logging
Metrics
Tracing
Auditing
Error monitoring

However, the event mechanism itself is not a complete observability platform. Observability systems may require additional infrastructure for:

Persistent event storage
Distributed tracing
Metrics aggregation
Dashboards
Alerting
Background processing

Treat BindAI events as an integration mechanism rather than assuming they provide a complete observability stack.

Event-Driven Applications

As an application grows, events can provide boundaries between independent components. For example:

                    Agent
                      |
                      v
                   EventBus
                      |
        +-------------+-------------+
        |             |             |
        v             v             v
     Logging       Metrics      Automation
                                    |
                                    v
                                 Workflow
                                    |
                         +----------+----------+
                         |          |          |
                         v          v          v
                       Agent     Service    Notification

This architecture allows the agent and other BindAI components to remain focused on their primary responsibilities while application integrations react independently.

Current Event Architecture

The current BindAI event architecture can be summarized as:

Agent-level callbacks

    agent.on()
        |
        v
    agent.emit()


Core events

    Event
      |
      v
    EventBus
      |
      +---- subscribe()
      |
      +---- publish()


Automation

    EventBus
      |
      v
    EventTrigger
      |
      v
    Automation Target

These layers are related, but they should not be treated as interchangeable APIs.

Best Practices

Use descriptive event names.
Keep application event contracts consistent.
Document callback arguments for custom agent events.
Use structured Event objects with EventBus.
Prefer framework event types when consuming BindAI core events.
Keep event handlers small and focused.
Keep heavy business logic outside event handlers.
Handle important handler failures appropriately.
Use EventTrigger when an event should initiate automation.
Detach triggers when they are no longer needed.
Use hooks for reusable execution-related behavior.
Use lifecycle callbacks for lifecycle-specific behavior.
Use workflows for complex orchestration.
Test event mechanisms independently from external services.
Do not assume undocumented lifecycle event names or callback signatures.
Do not treat the event system as a complete observability platform.

Summary

BindAI provides several complementary mechanisms for reacting to agent activity. At the agent level:

agent.on(event, callback)

agent.emit(event, *args)

For structured core events:

agent.events.subscribe(event_name, handler)

agent.events.publish(event)

For event-driven automation:

EventBus
   |
   v
EventTrigger
   |
   v
Automation Target

These mechanisms allow BindAI applications to connect agent execution with logging, monitoring, auditing, notifications, automation, workflows, and external services without tightly coupling those components to the agent itself. The key principle is to use the appropriate layer for the job: agent callbacks for lightweight local behavior, EventBus for structured event communication, automation triggers for event-driven actions, and workflows for complex orchestration.

​Events

​Agent Events

​Registering Callbacks

​Emitting Events

​Custom Events

​Event Arguments

​Core EventBus

​Event Objects

​Subscribing to EventBus Events

​Publishing EventBus Events

​Unsubscribing

​EventBus Handler Isolation

​Agent EventBus

​Agent Callbacks vs EventBus

​Agent Lifecycle

​Tool Events

​Events and Automation

​Enabling and Disabling Automation Triggers

​Detaching Automation Triggers

​Trigger Registry

​Event-Driven Architecture

​Events and Workflows

​Events and External Integrations

​Keeping Event Handlers Lightweight

​Error Handling in Event Handlers

​Event Naming

​Hooks and Callbacks

​Events vs Hooks

​Testing Events

​Events and Observability

​Event-Driven Applications

​Current Event Architecture

​Best Practices

​Summary

Events

Agent Events

Registering Callbacks

Emitting Events

Custom Events

Event Arguments

Core EventBus

Event Objects

Subscribing to EventBus Events

Publishing EventBus Events

Unsubscribing

EventBus Handler Isolation

Agent EventBus

Agent Callbacks vs EventBus

Agent Lifecycle

Tool Events

Events and Automation

Enabling and Disabling Automation Triggers

Detaching Automation Triggers

Trigger Registry

Event-Driven Architecture

Events and Workflows

Events and External Integrations

Keeping Event Handlers Lightweight

Error Handling in Event Handlers

Event Naming

Hooks and Callbacks

Events vs Hooks

Testing Events

Events and Observability

Event-Driven Applications

Current Event Architecture

Best Practices

Summary