async hooks

[pgrayy]

Description

Support asynchronous hooks so as not to block the async event loop when invoking agents asynchronously. Note, this will be particularly useful for Bidirectional Agents, which only operates asynchronously.

Usage

import asyncio
from typing import Any

from strands import Agent
from strands.hooks import BeforeInvocationEvent, HookProvider, HookRegistry

class AsyncHook(HookProvider):
    def register_hooks(self, registry: HookRegistry, **kwargs: Any) -> None:
        registry.add_callback(BeforeInvocationEvent, self.hook_1)
        registry.add_callback(BeforeInvocationEvent, self.hook_2)

    async def hook_1(self, event: BeforeInvocationEvent) -> None:
        print("STARTING HOOK 1")
        await asyncio.sleep(5)
        print("ENDING HOOK 1")

    async def hook_2(self, event: BeforeInvocationEvent) -> None:
        print("STARTING HOOK 2")
        await asyncio.sleep(1)
        print("ENDING HOOK 2")

async def func_1() -> None:
    print("STARTING FUNC 1")
    await asyncio.sleep(3)
    print("ENDING FUNC 1")

async def main() -> None:
    agent = Agent(hooks=[AsyncHook()], callback_handler=None)

    task1 = asyncio.create_task(func_1())
    task2 = asyncio.create_task(agent.invoke_async("What is 2+2"))

    await asyncio.gather(task1, task2)

asyncio.run(main())

"""
Output (note the interleaving with `func_1`):
% python save/hooks/async_test.py
STARTING FUNC 1
STARTING HOOK 1
ENDING FUNC 1
ENDING HOOK 1
STARTING HOOK 2
ENDING HOOK 2
"""

A few additional notes:

• Async hooks are still executed sequentially, one after the other.
• AgentInitializedEvent still does not support async callbacks since it is emitted from __init__. If users attempt to register an async callback on this event, they will receive a ValueError. We could wrap the event in a thread, which would allow us to call its hooks asynchronously, but this technically is a breaking change.
• Turning hook_1 and hook_2 into sync methods would result in the following output (note the lack of interleaving with func_1):

% python save/hooks/async_test.py
STARTING FUNC 1
STARTING HOOK 1
ENDING HOOK 1
STARTING HOOK 2
ENDING HOOK 2
ENDING FUNC 1

Related Issues

#1017

Documentation PR

Will follow up after review.

Type of Change

New feature

Testing

How have you tested the change? Verify that the changes do not break functionality or introduce warnings in consuming repositories: agents-docs, agents-tools, agents-cli

• I ran hatch run prepare: Updated unit tests
• I ran hatch test tests_integ/hooks/**/*.py: Wrote new integ tests.

Checklist

• I have read the CONTRIBUTING document
• I have added any necessary tests that prove my fix is effective or my feature works
• I have updated the documentation accordingly
• I have added an appropriate example to the documentation to outline the feature, or no new docs are needed
• My changes generate no new warnings
• Any dependent changes have been merged and published

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[zastrowm]

Inclined towards this - however I'd like to see if we can do full async (minus Agent.__init__) instead of trying to support both. Agent.init needs further api design (#330) which is why I'm okay holding off on that

[codecov]

Codecov Report

❌ Patch coverage is 97.10145% with 2 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/strands/hooks/registry.py	91.66%	1 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!

[dbschmigelski]

Sorry, high level, if we are executing sequentially why do we care if we are blocking the event loop? Isn't it already blocked by being sequential?

If this is more of a benefit to hook authors where they can write async code, that makes sense to me. But can you explain what other benefit they get?

[pgrayy]

Sorry, high level, if we are executing sequentially why do we care if we are blocking the event loop? Isn't it already blocked by being sequential?

If this is more of a benefit to hook authors where they can write async code, that makes sense to me. But can you explain what other benefit they get?

The Usage example above highlights this. Hooks run sequentially amongst themselves but they run concurrently with other concurrent tasks. So the Usage example shows an external function (func_1) that is no longer blocked by the hook execution. It can run concurrently with the hooks.

[dbschmigelski]

Sorry, high level, if we are executing sequentially why do we care if we are blocking the event loop? Isn't it already blocked by being sequential?
If this is more of a benefit to hook authors where they can write async code, that makes sense to me. But can you explain what other benefit they get?

The Usage example above highlights this. Hooks run sequentially amongst themselves but they run concurrently with other concurrent tasks. So the Usage example shows an external function (func_1) that is no longer blocked by the hook execution. It can run concurrently with the hooks.

Oh haha, ok event loop is an overloaded term. This is about the asyncio event loop not the Strands Agents Event Loop

[pgrayy]

Sorry, high level, if we are executing sequentially why do we care if we are blocking the event loop? Isn't it already blocked by being sequential?
If this is more of a benefit to hook authors where they can write async code, that makes sense to me. But can you explain what other benefit they get?

The Usage example above highlights this. Hooks run sequentially amongst themselves but they run concurrently with other concurrent tasks. So the Usage example shows an external function (func_1) that is no longer blocked by the hook execution. It can run concurrently with the hooks.

Oh haha, ok event loop is an overloaded term. This is about the asyncio event loop not the Strands Agents Event Loop

Oh yes lol. TypeScript fortunately we are switching to the term "agent loop".

[mehtarac]

Note to be a reminder: we will need to add hooks to the Bidirectional Agent constructor once this is merged in

[mehtarac]

Curious if we had a chance to test this with the bidirectional agent as well?

[pgrayy]

Curious if we had a chance to test this with the bidirectional agent as well?

Have not yet tested with Bidirectional agents. I first need to adjust the hook events so they can accept a bidirectional agent. Right now they only support a converse stream agent (src). The solution for that is being tracked in another issue.