Skip to main content
The @hook decorator allows you to configure individual hook behavior. It can be applied to both pre-hooks and post-hooks.

​
Import

from agno.hooks import hook

​
Parameters

ParameterTypeDefaultDescription
run_in_backgroundboolFalseWhen True, the hook runs as a background task after the response is sent. Requires AgentOS.

​
Usage

​
Background Execution

Mark a hook to run in the background without blocking the API response: 
from agno.hooks import hook

@hook(run_in_background=True)
async def log_analytics(run_output, agent):
    """Runs after the response is sent to the user."""
    await store_metrics(run_output)

​
Combining with Regular Hooks

You can mix background and regular hooks on the same agent: 
from agno.hooks import hook

def validate_output(run_output, agent):
    """Runs synchronously, blocks response until complete."""
    if not run_output.content:
        raise OutputCheckError("Empty response not allowed")

@hook(run_in_background=True)
async def send_notification(run_output, agent):
    """Runs in background after response is sent."""
    await notify_user(run_output.content)

agent = Agent(
    model=OpenAIChat(id="gpt-4o"),
    post_hooks=[validate_output, send_notification],
)

​
Important Notes

Background execution requires AgentOS. When running agents directly (not through AgentOS), hooks marked with run_in_background=True will execute synchronously.
Background hooks cannot modify data. Since background hooks run after the response is sent, any modifications to run_input, run_output, or other parameters won’t affect the agent’s processing. Use background mode only for logging, analytics, or notifications.

​
See Also