Background Hooks (Global)

Run non-guardrail agent hooks as background tasks using AgentOS

Run non-guardrail hooks as FastAPI background tasks by enabling run_hooks_in_background at the AgentOS level. Guardrail hooks remain synchronous so they can accept or reject the run before processing continues.

1. Create a Python file

   background_hooks_global.py

   import asyncio
   
   from agno.agent import Agent
   from agno.db.sqlite import SqliteDb
   from agno.models.openai import OpenAIResponses
   from agno.os import AgentOS
   from agno.run.agent import RunInput
   
   
   # Pre-hook for logging requests
   def log_request(run_input: RunInput, agent):
       """
       This pre-hook is queued while the run starts and executes after the response.
       Background pre-hooks cannot modify run_input for the active run.
       """
       print(f"[Background Pre-Hook] Request received for agent: {agent.name}")
       print(f"[Background Pre-Hook] Input: {run_input.input_content}")
   
   
   # Post-hook for logging analytics
   async def log_analytics(run_output, agent, session):
       """
       This post-hook will run in the background after the response is sent.
       It won't block the API response.
       """
       print(f"[Background Post-Hook] Logging analytics for run: {run_output.run_id}")
       print(f"[Background Post-Hook] Agent: {agent.name}")
       print(f"[Background Post-Hook] Session: {session.session_id}")
   
       # Simulate a slow operation
       await asyncio.sleep(2)
       print("[Background Post-Hook] Analytics logged successfully!")
   
   
   # Another post-hook for sending notifications
   async def send_notification(run_output, agent):
       """
       Another background task that sends notifications without blocking the response.
       """
       print(f"[Background Post-Hook] Sending notification for agent: {agent.name}")
       # Simulate a slow operation
       await asyncio.sleep(3)
       print("[Background Post-Hook] Notification sent!")
   
   
   # Create an agent with hooks
   agent = Agent(
       id="background-task-agent",
       name="BackgroundTaskAgent",
       model=OpenAIResponses(id="gpt-5.2"),
       instructions="You are a helpful assistant",
       db=SqliteDb(db_file="tmp/agent.db"),
       pre_hooks=[log_request],
       post_hooks=[log_analytics, send_notification],
       markdown=True,
   )
   
   # Create AgentOS with background hooks enabled
   agent_os = AgentOS(
       agents=[agent],
       run_hooks_in_background=True,  # Non-guardrail hooks run in background
   )
   
   # Get the FastAPI app
   app = agent_os.get_app()
   
   if __name__ == "__main__":
       agent_os.serve(app="background_hooks_global:app", port=7777, reload=True)
   
2. Set up your virtual environment

   Mac

   uv venv --python 3.12
   source .venv/bin/activate
   

   uv venv --python 3.12
   .venv\Scripts\activate
   
3. Install dependencies

   uv pip install -U "agno[os]" openai
   
4. Export your OpenAI API key

   Mac/Linux

   export OPENAI_API_KEY="your_openai_api_key_here"
   

   $Env:OPENAI_API_KEY="your_openai_api_key_here"
   
5. Run the server

   Mac/Linux

   python background_hooks_global.py
   

   python background_hooks_global.py
   
6. Test the endpoint

   curl -X POST http://localhost:7777/agents/background-task-agent/runs \
     -F "message=Hello, how are you?" \
     -F "stream=false"
   

   The response will be returned immediately. Check the server logs to see the background hooks executing after the response is sent.

What Happens

1. The agent processes the request
2. The response is sent immediately to the user
3. Non-guardrail pre-hooks and post-hooks run in the background
4. Guardrail hooks run synchronously and can block the request
5. The user doesn’t have to wait for background tasks to complete

With run_hooks_in_background=True on AgentOS, non-guardrail hooks for all agents run in the background. Guardrail hooks remain synchronous. Use the @hook decorator for per-hook control.