feat: add event hooks for llm tool usage and response handling

[Soulter]

Modifications / 改动点

• This is NOT a breaking change. / 这不是一个破坏性变更。

Screenshots or Test Results / 运行截图或测试结果

---

Checklist / 检查清单

• 😊 如果 PR 中有新加入的功能，已经通过 Issue / 邮件等方式和作者讨论过。/ If there are new features added in the PR, I have discussed it with the authors through issues/emails, etc.
• 👀 我的更改经过了良好的测试，并已在上方提供了“验证步骤”和“运行截图”。/ My changes have been well-tested, and "Verification Steps" and "Screenshots" have been provided above.
• 🤓 我确保没有引入新依赖库，或者引入了新依赖库的同时将其添加到了 requirements.txt 和 pyproject.toml 文件相应位置。/ I have ensured that no new dependencies are introduced, OR if new dependencies are introduced, they have been added to the appropriate locations in requirements.txt and pyproject.toml.
• 😮 我的更改没有引入恶意代码。/ My changes do not introduce malicious code.

由 Sourcery 提供的摘要

在 LLM 工具调用前后新增事件钩子，并将其接入到代理的钩子管线中。

新功能：

• 引入装饰器，用于注册在调用 LLM 函数工具之前以及在接收其结果之后触发的事件处理器。
• 通过公共的事件/过滤器注册 API 暴露新的 LLM 工具使用与响应钩子。

增强内容：

• 扩展事件类型枚举和代理运行钩子，以发出围绕函数工具执行过程的相关事件。

Original summary in English

Summary by Sourcery

Add new event hooks around LLM tool invocation and wire them into the agent hook pipeline.

New Features:

• Introduce decorators to register handlers for events fired before calling an LLM function tool and after receiving its result.
• Expose the new LLM tool usage and response hooks through the public event/filter registration API.

Enhancements:

• Extend the event type enumeration and agent run hooks to emit events surrounding function tool execution.

[sourcery-ai]

你好，我发现了 1 个问题，并给出了一些整体层面的反馈：

• 新增 docstring 中的装饰器示例使用的是 @on_using_llm_tool() / @on_llm_tool_respond()，但实际导出的装饰器名称是 register_on_using_llm_tool / register_on_llm_tool_respond；建议统一命名，或者添加别名，这样示例代码就能与用户实际需要导入和调用的内容保持一致。
• 你新增了 EventType.OnCallingFuncToolEvent 和 EventType.OnAfterCallingFuncToolEvent 两个事件；建议在枚举的注释（或命名）中进一步明确哪个是“前(before)”、哪个是“后(after)”，以减少未来 Hook 实现者的歧义。

给 AI 代理的提示词

Please address the comments from this code review:

## Overall Comments
- The decorator examples in the new docstrings use `@on_using_llm_tool()` / `@on_llm_tool_respond()`, but the actual exported decorator names are `register_on_using_llm_tool` / `register_on_llm_tool_respond`; consider aligning the naming or adding aliases so the example code matches what users should actually import and call.
- You’ve added both `EventType.OnCallingFuncToolEvent` and `EventType.OnAfterCallingFuncToolEvent`; it may be worth clarifying in the enum comments (or names) which is explicitly "before" vs "after" to reduce ambiguity for future hook implementers.

## Individual Comments

### Comment 1
<location> `astrbot/core/star/register/star_handler.py:420` </location>
<code_context>
+    ```py
+    from astrbot.core.agent.tool import FunctionTool
+
+    @on_using_llm_tool()
+    async def test(self, event: AstrMessageEvent, tool: FunctionTool, tool_args: dict | None) -> None:
+        ...
</code_context>

<issue_to_address>
**issue (typo):** Example decorator name in the docstring likely should be `@on_llm_tool_respond()` instead of `@on_using_llm_tool()`.

In the `register_on_llm_tool_respond` docstring, this example still uses `@on_using_llm_tool()`, likely copied from the earlier function. Updating it to `@on_llm_tool_respond()` would better match this function’s name and behavior and avoid confusing users.

Suggested implementation:

```python
def register_on_llm_tool_respond(**kwargs):
    """当函数工具调用结束，准备将函数工具的结果加入消息流中时的事件。

    Examples:
    ```py
    from astrbot.core.agent.tool import FunctionTool

    @on_llm_tool_respond()
    async def test(self, event: AstrMessageEvent, tool: FunctionTool, tool_args: dict | None) -> None:
        ...
    ```

    请务必接收三个参数：event, tool, tool_args

    """

    def decorator(awaitable):
        _ = get_handler_or_create(awaitable, EventType.OnFuncToolRespondEvent, **kwargs)
        return awaitable

```

If the existing `register_on_llm_tool_respond` docstring text differs (e.g., different Chinese description or parameter list), adjust the `SEARCH` block to match the current docstring exactly and only replace the decorator line in the example from `@on_using_llm_tool()` to `@on_llm_tool_respond()`. The `register_on_using_llm_tool` example in the snippet you shared is already correct and does not need to be changed.
</issue_to_address>

---

Sourcery 对开源项目免费使用——如果你觉得我们的 Review 有帮助，欢迎分享 ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{帮我变得更有用！请在每条评论上点 👍 或 👎，我会根据你的反馈改进后续的 Review。}

Original comment in English

Hey - I've found 1 issue, and left some high level feedback:

• The decorator examples in the new docstrings use @on_using_llm_tool() / @on_llm_tool_respond(), but the actual exported decorator names are register_on_using_llm_tool / register_on_llm_tool_respond; consider aligning the naming or adding aliases so the example code matches what users should actually import and call.
• You’ve added both EventType.OnCallingFuncToolEvent and EventType.OnAfterCallingFuncToolEvent; it may be worth clarifying in the enum comments (or names) which is explicitly "before" vs "after" to reduce ambiguity for future hook implementers.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- The decorator examples in the new docstrings use `@on_using_llm_tool()` / `@on_llm_tool_respond()`, but the actual exported decorator names are `register_on_using_llm_tool` / `register_on_llm_tool_respond`; consider aligning the naming or adding aliases so the example code matches what users should actually import and call.
- You’ve added both `EventType.OnCallingFuncToolEvent` and `EventType.OnAfterCallingFuncToolEvent`; it may be worth clarifying in the enum comments (or names) which is explicitly "before" vs "after" to reduce ambiguity for future hook implementers.

## Individual Comments

### Comment 1
<location> `astrbot/core/star/register/star_handler.py:420` </location>
<code_context>
+    ```py
+    from astrbot.core.agent.tool import FunctionTool
+
+    @on_using_llm_tool()
+    async def test(self, event: AstrMessageEvent, tool: FunctionTool, tool_args: dict | None) -> None:
+        ...
</code_context>

<issue_to_address>
**issue (typo):** Example decorator name in the docstring likely should be `@on_llm_tool_respond()` instead of `@on_using_llm_tool()`.

In the `register_on_llm_tool_respond` docstring, this example still uses `@on_using_llm_tool()`, likely copied from the earlier function. Updating it to `@on_llm_tool_respond()` would better match this function’s name and behavior and avoid confusing users.

Suggested implementation:

```python
def register_on_llm_tool_respond(**kwargs):
    """当函数工具调用结束，准备将函数工具的结果加入消息流中时的事件。

    Examples:
    ```py
    from astrbot.core.agent.tool import FunctionTool

    @on_llm_tool_respond()
    async def test(self, event: AstrMessageEvent, tool: FunctionTool, tool_args: dict | None) -> None:
        ...
    ```

    请务必接收三个参数：event, tool, tool_args

    """

    def decorator(awaitable):
        _ = get_handler_or_create(awaitable, EventType.OnFuncToolRespondEvent, **kwargs)
        return awaitable

```

If the existing `register_on_llm_tool_respond` docstring text differs (e.g., different Chinese description or parameter list), adjust the `SEARCH` block to match the current docstring exactly and only replace the decorator line in the example from `@on_using_llm_tool()` to `@on_llm_tool_respond()`. The `register_on_using_llm_tool` example in the snippet you shared is already correct and does not need to be changed.
</issue_to_address>

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}