Epic: Expand Lifecycle Events and Middleware

[araujof]

Description

This epic enhances the BeeAI Framework’s event and middleware systems to enable deeper observability, robust guardrail enforcement, reflection, and flexible data transformation across the agent lifecycle.

Currently, the RequirementAgent emits only a limited set of lifecycle events (e.g., start, success, ...). This restricts the ability to plug in reusable middleware for redaction, sanitization, filtering, and observability.

By expanding and standardizing the event model, and introducing a general-purpose middleware API, we’ll make it easier to build secure, transparent, and extensible agent behaviors.

Design

Motivation

AI agents interact with chat models, memory stores, and external tools — all of which can introduce risks or complexity without proper visibility and control. A middleware layer that can fully mediate these interactions can enable and scale agent governance and security with the framework.

This will provide a robust, extensible, and secure foundation for observability and control across agent operations — enabling developers to build safer, more transparent, and maintainable AI systems.

Advantages

• Consistency: Unified event and middleware model improves framework cohesion.
• Security: Middleware enforces guardrails like redaction and prompt sanitization.
• Observability: Full lifecycle event tracing for better visibility.
• Extensibility: Easy to build and share custom middleware.
• Adoption: Better developer experience with documentation and examples.

Changes

1. Expanded Lifecycle Events

• Add/document pre/post events for all major operations:
  • Chat model invocations (pre and post invocations)
  • Memory operations (on memory read, write, and update)
  • Tool invocations (pre and post tool invocations)
• Normalize naming conventions across framework components.
• Ensure events carry rich metadata (input/output, timestamps, context).

2. Reusable Middleware Framework

• Expose explicit middleware/event management APIs for supporting process continuation (currently, the way to achieve this is to return an agent output object).
• Enable chaining for:
  • Memory redaction and sanitization
  • Prompt injection and jailbreak detection
  • Observability, logging, and metrics instrumentation
  • Input/output transformation or filtering

3. Documentation and Developer Experience

• Add clear event and middleware documentation.
• Provide ready-to-use middleware templates.
• Offer developer guidance on writing and composing custom middleware.

Tasks

Task 1: Expand Lifecycle Events

• [ ] Extend RequirementAgent to emit complete pre/post event sets for:
  • [x] Chat model invocations
  • [ ] Memory operations (read, write, update)
  • [x] Tool invocations
• [x] Normalize event naming across framework objects.
• [x] Enrich event payloads with contextual metadata.
• [x] Add tests and usage examples.
• Reference: Current Events Documentation

Task 2: Implement Middleware for Redaction and Sanitization

• [ ] Design and implement middleware for:
  • [ ] Memory redaction (PII, sensitive data)
  • [ ] I/O sanitization for agents, tools, and chat models
  • [ ] Prompt injection and jailbreak detection
• [x] Support middleware chaining and context propagation.
• [ ] Add tests and configuration examples.

Task 3: Documentation Updates

• [x] Update existing event documentation.
• [x] Create a new Middleware section with:
  • [x] Architecture overview and API reference
  • [x] Built-in middleware
  • [x] Guide for creating and registering custom middleware
• [ ] Include examples for middleware chaining.

Task 4: Workshop Notebook

• [ ] Create a Jupyter or notebook-based workshop covering:
  • [ ] Lifecycle event tracing
  • [ ] Custom middleware development
  • [ ] Real-world examples: redaction, sanitization, observability

[Tomas2D]

Add pre/post events for all major operations: Chat model invocations (on_chat_pre_invoke, on_chat_post_invoke) Memory operations (on_memory_read, on_memory_write, on_memory_pre_update, etc.) Tool invocations (on_tool_pre_invoke, on_tool_post_invoke)

These events are not necessarily to be defined as they already exist. Internally, every prominent component returns start/success/error/finish (this is done by RunContext), so these events do not need to be repeated for every parent component (like RequirementAgent) in this example. In other words, when you run RequirementAgent`, you can easily listen to all nested events (from components like tools/chat models/embedding models/middlewares/sub-agents), etc. In addition, such an event includes all metadata: source timestamps, etc.

Given that we could simplify how one can bind to these events more easily.

[araujof]

Add pre/post events for all major operations: Chat model invocations (on_chat_pre_invoke, on_chat_post_invoke) Memory operations (on_memory_read, on_memory_write, on_memory_pre_update, etc.) Tool invocations (on_tool_pre_invoke, on_tool_post_invoke)

These events are not necessarily to be defined as they already exist. Internally, every prominent component returns start/success/error/finish (this is done by RunContext), so these events do not need to be repeated for every parent component (like RequirementAgent) in this example. In other words, when you run RequirementAgent`, you can easily listen to all nested events (from components like tools/chat models/embedding models/middlewares/sub-agents), etc. In addition, such an event includes all metadata: source timestamps, etc.

Given that we could simplify how one can bind to these events more easily.

Agreed. I realized that, but thanks for pointing it out. I will update the spec to reflect that and include any missing events.

[dosubot[bot]]

Hi, @araujof. I'm Dosu, and I'm helping the beeai-framework team manage their backlog and am marking this issue as stale.

Issue Summary:

• You proposed expanding lifecycle events and adding a middleware API for better observability, security, and extensibility.
• Tomas2D clarified that many lifecycle events already exist internally via RunContext with start/success/error/finish events.
• This allows nested event listening without redundant event definitions.
• You agreed to update the specification to simplify event binding and include any missing events.
• The discussion focused on refining event handling and middleware support to improve developer experience.

Next Steps:

• Please confirm if this issue is still relevant to the latest version of the beeai-framework and if you plan to continue updating the specification.
• If no further updates are provided, I will automatically close this issue in 7 days.

Thank you for your understanding and contribution!

[araujof]

Hi, @araujof. I'm Dosu, and I'm helping the beeai-framework team manage their backlog and am marking this issue as stale.

Issue Summary:

• You proposed expanding lifecycle events and adding a middleware API for better observability, security, and extensibility.
• Tomas2D clarified that many lifecycle events already exist internally via RunContext with start/success/error/finish events.
• This allows nested event listening without redundant event definitions.
• You agreed to update the specification to simplify event binding and include any missing events.
• The discussion focused on refining event handling and middleware support to improve developer experience.

Next Steps:

• Please confirm if this issue is still relevant to the latest version of the beeai-framework and if you plan to continue updating the specification.
• If no further updates are provided, I will automatically close this issue in 7 days.

Thank you for your understanding and contribution!

WIP

[dosubot[bot]]

Hi, @araujof. I'm Dosu, and I'm helping the beeai-framework team manage their backlog and am marking this issue as stale.

Issue Summary:

• You proposed expanding lifecycle events and adding a reusable middleware API for better observability, security, and extensibility.
• Tomas2D noted that many lifecycle events already exist internally via RunContext, allowing nested event listening without redundant definitions.
• You agreed to update the spec to incorporate these existing events.
• The discussion has centered on simplifying event binding and improving middleware support.
• You confirmed the issue is still a work in progress.

Next Steps:

• Please let me know if this issue is still relevant to the latest version of the beeai-framework by commenting here to keep the discussion open.
• Otherwise, this issue will be automatically closed in 7 days.

Thank you for your understanding and contribution!