Add global `on_run_start` and `on_run_end` lifecycle hooks to `RunHooksBase`

[dannyhorcajo]

Please read this first

• Have you read the docs? Agents SDK docs
• Have you searched for related issues? Others may have had similar requests

Describe the feature

Feature

Add two optional async methods to RunHooksBase:

async def on_run_start(
    context: RunContextWrapper[TContext]
) -> None: 
    ...
async def on_run_end(
    context: RunContextWrapper[TContext],
    result: Optional[Any],
) -> None:
    ...

Called exactly once per run (before first agent starts; after final agent finishes).

Why

Current hooks are per-agent or per-tool. Missing global boundaries makes it hard to:

• Start/end a root trace span
• Capture total run latency and aggregated metrics
• Initialize and tear down shared resources
• Emit a single audit/compliance record

Although it is technically possible to simulate run-level start/end by calling custom pre/post functions outside Runner.run(), that splits lifecycle logic across two places: global boundaries outside the runner and per‑agent/tool events inside hooks.

First‑class on_run_start/ on_run_end centralizes all lifecycle concerns in one hooks class, and keeps instrumentation symmetrical.

[seratch]

Thanks for sharing this idea. With this SDK, your code directly runs the Runner's run method, so I still don't understand why you need these hooks. You can simply do anything right before/after the runner invocation.

[dannyhorcajo]

Hi @seratch, indeed that is possible.

Nevertheless I think it would be an easy-to-implement and quality of life addition to the SDK to have all the hooks' logic centralized inside the Hooks class itself, rather than it being spread out throughout the code, which is harder to maintain in the long run.

In my case, I need to update MLFlow's traces before and after Runner.run(), which can quickly branch out:

mlflow.update_current_trace(request_preview=user_input)  # Pre-run logic
tracing_hooks = TracingHooks()

try:
    result = Runner.run(main_agent, user_input, hooks=tracing_hooks)
    mlflow.update_current_trace(response_preview=result.final_output)  # Post-run logic

    return result.final_output

except InputGuardrailTripwireTriggered as e:
    fallback_result = Runner.run(fallback_agent, user_input, hooks=tracing_hooks)
    mlflow.update_current_trace(response_preview=fallback_result.final_output)  # Post-run logic is repeated

    return fallback_result.final_output

This is what I'm currently using at the moment - it works, but can quickly be cumbersome for more complex code.

Sure, I could move all start and end logic to two methods inside TracingHooks and invoke those before and after Runner.run(), but it would still be error-prone because of the need to copy-paste the same code for every run, versus simply passing the hooks to the runner and having them being called automatically 😄

[ihower]

@dannyhorcajo You can refactor your code like this:

async def traced_runner_run(*args, **kwargs):
    result = await Runner.run(*args, **kwargs)
    mlflow.update_current_trace(response_preview=result.final_output)
    return result

Then you can simplify your logic to:

try:
    result = await traced_runner_run(main_agent, user_input, hooks=tracing_hooks)
    return result.final_output
except InputGuardrailTripwireTriggered:
    fallback_result = await traced_runner_run(fallback_agent, user_input, hooks=tracing_hooks)
    return fallback_result.final_output

This way, your pre/post-run logic stays centralized without needing new SDK-level hooks, and it achieves the same goal in a clean, reusable way.