@hook Decorator

Configure a hook to run as a non-blocking background task with @hook(run_in_background=True).

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

Parameter	Type	Default	Description
run_in_background	bool	False	When 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
from agno.run.agent import RunOutput


@hook(run_in_background=True)
def log_analytics(run_output: RunOutput) -> None:
    print(run_output.metrics)

Combining with Regular Hooks

You can mix background and regular hooks on the same agent:

uv pip install -U agno openai

from agno.agent import Agent
from agno.exceptions import OutputCheckError
from agno.hooks import hook
from agno.models.openai import OpenAIChat
from agno.run.agent import RunOutput


def validate_output(run_output: RunOutput) -> None:
    if not run_output.content:
        raise OutputCheckError("Empty response not allowed")


@hook(run_in_background=True)
def send_notification(run_output: RunOutput) -> None:
    print(f"Response complete: {run_output.run_id}")

agent = Agent(
    model=OpenAIChat(id="gpt-5.2"),
    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.

Treat background hook arguments as read-only. AgentOS attempts to deep-copy run_input, run_context, run_output, session_state, dependencies, and metadata before queueing a hook. If a value cannot be copied, AgentOS logs a warning and passes the original reference. Background hooks can write to databases and external services.

See Also

• Background Hooks
• Pre-hooks Reference
• Post-hooks Reference