Hooks

Overview

Hooks are the mechanism by which modules participate in the Agent Runtime's 7-step pipeline. Rather than modules being called directly, the runtime broadcasts lifecycle events at each pipeline step, and modules register handlers (hooks) for the steps they care about. This decoupled design allows modules to be added or removed without changing the runtime code.

Hook Lifecycle

During each agent execution cycle, the runtime invokes hooks in a defined order corresponding to the pipeline steps. A module can register hooks for any subset of these steps:

• on_input -- Called during Input Processing. Modules can inspect or transform the raw input.
• on_context -- Called during Context Building. Modules contribute their domain-specific context to the shared context object.
• on_pre_reasoning -- Called before LLM Reasoning. Modules can inject system prompts or modify the message history.
• on_tool_call -- Called during Tool Execution when a module's MCP tool is invoked.
• on_response -- Called during Response Generation. Modules can augment or post-process the agent's response.
• on_state_update -- Called during State Update. Modules persist any changes from the current cycle.

Execution Order

When multiple modules register hooks for the same step, they execute in module registration order. Each hook receives the shared context object and can read or modify it. Hooks are async functions, allowing modules to perform I/O operations like database queries or API calls without blocking the pipeline.

Practical Example

The Memory module's on_context hook queries EverMemOS for relevant past interactions and adds them to the context. During on_state_update, it persists the current interaction for future retrieval. This pattern of reading during context building and writing during state update is common across most modules.