feat(hooks): accept callable hook callbacks in Agent constructor

[agent-of-mkmeral]

Motivation

Currently, the hooks parameter in Agent.__init__ only accepts HookProvider instances:

# This works
agent = Agent(hooks=[MyHookProvider()])

# This does NOT work (TypeError)
def on_start(event: BeforeInvocationEvent) -> None:
    print('Starting!')
agent = Agent(hooks=[on_start])  # ❌

However, Agent.add_hook() (added in #1706) already supports plain callables:

# This works fine after construction
agent = Agent()
agent.add_hook(on_start)  # ✅

This inconsistency is confusing. If you can register a callable via add_hook(), you should also be able to pass it via the constructor.

Changes

src/strands/agent/agent.py:

• Updated hooks param type from list[HookProvider] to list[HookProvider | HookCallback]
• Updated init logic to dispatch: HookProvider → add_hook(), callable → add_callback(None, hook)
• Added ValueError for invalid hook types with clear error message
• Updated docstring

After This Change

def on_start(event: BeforeInvocationEvent) -> None:
    print('Starting!')

def on_model(event: BeforeModelCallEvent) -> None:
    print('Model call!')

# All of these now work:
agent = Agent(hooks=[on_start])  # ✅ Plain callable
agent = Agent(hooks=[MyHookProvider()])  # ✅ HookProvider (unchanged)
agent = Agent(hooks=[on_start, MyHookProvider(), on_model])  # ✅ Mixed list

Callables must have typed event parameters (same requirement as agent.add_hook()). Lambdas without type hints will raise ValueError with a helpful message.

Tests

Added 12 new test cases in tests/strands/agent/test_agent_hooks_callable.py:

• Plain callable acceptance
• HookProvider backward compatibility
• Mixed list (HookProvider + callable)
• Callable invoked during agent lifecycle
• Invalid hook type raises ValueError
• None and empty list handling
• Multiple callables
• Async callable support
• Async AgentInitializedEvent rejection
• Lambda without type hint raises ValueError

All 24 existing hook tests + 61 hook registry tests continue to pass.

Related

• feat(agent): add add_hook convenience method for hook callback registration #1706 (feat: add add_hook convenience method)

cc @mkmeral

[mkmeral]

/strands review

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[mkmeral]

@agent-of-mkmeral did you not run hatch run prepare to check everything? do it, fix the issues

[github-actions]

Assessment: ✅ Approve

This PR addresses a legitimate usability gap by enabling the hooks constructor parameter to accept plain callable callbacks, matching the behavior of agent.add_hook(). The implementation is clean and the test coverage is comprehensive.

Review Summary

• API Design: Minimal change that adds consistency with existing add_hook() method - aligns well with SDK tenets (simple at any scale, obvious path is happy path)
• Implementation: Correctly dispatches between HookProvider and callable types, with clear error message for invalid hooks
• Testing: 12 well-structured test cases covering plain callables, HookProviders, mixed lists, async callbacks, and error conditions
• Backward Compatibility: Fully maintained - existing HookProvider usage continues to work unchanged

Well done on the clear PR description with before/after examples!

[agent-of-mkmeral]

Fixed! Ran hatch run prepare and addressed the issues:

Commit: e3f9481

Issues found & fixed

Issue	Fix
F841 unused variable agent (line 48)	Removed assignment — Agent(hooks=[provider], ...)
F841 unused variable agent (line 150)	Removed assignment — Agent(hooks=[callback_a, callback_b], ...)
Unused import MagicMock	Removed by formatter
Formatting inconsistencies	Auto-fixed by hatch run format

Verification

• ✅ hatch run format — clean
• ✅ hatch run lint — All checks passed!
• ✅ ruff check — clean
• ✅ mypy ./src — no issues found in 140 source files
• ✅ All 121 collected tests passed (the Python 3.14 xray propagator errors are a pre-existing upstream issue)