Skip to main content
Pre-hooks and post-hooks are a simple way to validate or modify the input and output of an Agent run.

​
When Hooks Are Triggered

Hooks execute at specific points in the Agent run lifecycle:
  • Pre-hooks: Execute immediately after the agent session is loaded, before any processing begins. They run before before the model context is prepared and before any LLM execution begins, i.e. any modifications to the input, session state, or dependencies will be applied before LLM execution.
  • Post-hooks: Execute after the Agent generates a response and the output is prepared, but before the response is returned to the user. In streaming responses, they run after each chunk of the response is generated.

​
Pre-hooks

Pre-hooks execute at the very beginning of your Agent run, giving you complete control over what reaches the LLM. They’re perfect for implementing input validation, security checks, or any data preprocessing against the input your Agent receives.

​
Common Use Cases

Input Validation
  • Validate format, length, content or any other property of the input.
  • Remove or mask sensitive information.
  • Normalize input data.
Data Preprocessing
  • Transform input format or structure.
  • Enrich input with additional context.
  • Apply any other business logic before sending the input to the LLM.

​
Basic Example

Let’s create a simple pre-hook that validates the input length and raises an error if it’s too long: 
from agno.agent import Agent
from agno.models.openai import OpenAIChat
from agno.exceptions import CheckTrigger, InputCheckError
from agno.run.agent import RunInput

# Simple function we will use as a pre-hook
def validate_input_length(
    run_input: RunInput,
) -> None:
    """Pre-hook to validate input length."""
    max_length = 1000
    if len(run_input.input_content) > max_length:
        raise InputCheckError(
            f"Input too long. Max {max_length} characters allowed",
            check_trigger=CheckTrigger.INPUT_NOT_ALLOWED,
        )

agent = Agent(
    name="My Agent",
    model=OpenAIChat(id="gpt-4o"),
    # Provide the pre-hook to the Agent using the pre_hooks parameter
    pre_hooks=[validate_input_length],
)
You can see complete examples of pre-hooks in the Examples section.

​
Pre-hook Parameters

Pre-hooks run automatically during the Agent run and receive the following parameters:
  • run_input: The input to the Agent run that can be validated or modified
  • agent: Reference to the Agent instance
  • session: The current agent session
  • session_state: The current session state (optional)
  • dependencies: Dependencies passed to the Agent run (optional)
  • metadata: Metadata for the run (optional)
  • user_id: The user ID for the run (optional)
  • debug_mode: Whether debug mode is enabled (optional)
The framework automatically injects only the parameters your hook function accepts, so you can define hooks with just the parameters you need. You can learn more about the parameters in the Pre-hooks reference.

​
Post-hooks

Post-hooks execute after your Agent generates a response, allowing you to validate, transform, or enrich the output before it reaches the user. They’re perfect for output filtering, compliance checks, response enrichment, or any other output transformation you need.

​
Common Use Cases

Output Validation
  • Validate response format, length, and content quality.
  • Remove sensitive or inappropriate information from responses.
  • Ensure compliance with business rules and regulations.
Output Transformation
  • Add metadata or additional context to responses.
  • Transform output format for different clients or use cases.
  • Enrich responses with additional data or formatting.

​
Basic Example

Let’s create a simple post-hook that validates the output length and raises an error if it’s too long: 
from agno.agent import Agent
from agno.models.openai import OpenAIChat
from agno.exceptions import CheckTrigger, OutputCheckError
from agno.run.agent import RunOutput

# Simple function we will use as a post-hook
def validate_output_length(
    run_output: RunOutput,
) -> None:
    """Post-hook to validate output length."""
    max_length = 1000
    if len(run_output.content) > max_length:
        raise OutputCheckError(
            f"Output too long. Max {max_length} characters allowed",
            check_trigger=CheckTrigger.OUTPUT_NOT_ALLOWED,
        )

agent = Agent(
    name="My Agent",
    model=OpenAIChat(id="gpt-5-mini"),
    # Provide the post-hook to the Agent using the post_hooks parameter
    post_hooks=[validate_output_length],
)
You can see complete examples of post-hooks in the Examples section.

​
Post-hook Parameters

Post-hooks run automatically during the Agent run and receive the following parameters:
  • run_output: The output from the Agent run that can be validated or modified
  • agent: Reference to the Agent instance
  • session: The current agent session
  • session_state: The current session state (optional)
  • dependencies: Dependencies passed to the Agent run (optional)
  • metadata: Metadata for the run (optional)
  • user_id: The user ID for the run (optional)
  • debug_mode: Whether debug mode is enabled (optional)
The framework automatically injects only the parameters your hook function accepts, so you can define hooks with just the parameters you need. You can learn more about the parameters in the Post-hooks reference.

​
Guardrails

A popular use case for hooks are Guardrails: built-in safeguards for your Agents. You can learn more about them in the Guardrails section.

​
Developer Resources