fix: register_agent decorator NameError

[whatevertogo]

Summary

• 修复 @register_agent 装饰器在插件中使用时导致的 NameError: name 'AstrAgentContext' is not defined 错误
• 将 Agent[AstrAgentContext] 和 BaseAgentRunHooks[AstrAgentContext] 改为使用 Any 类型参数
• 移除 TYPE_CHECKING 块中对 AstrAgentContext 的导入（因为运行时不再需要）
• 添加单元测试验证修复效果

问题原因

之前为了解决循环导入问题，将 AstrAgentContext 放入 TYPE_CHECKING 块中导入。但 register_agent 装饰器在运行时执行 Agent[AstrAgentContext]，这需要 AstrAgentContext 类在运行时可用，而 TYPE_CHECKING 块中的导入仅在类型检查时生效。

解决方案

使用 Any 作为泛型类型参数，避免运行时对 AstrAgentContext 的依赖。这与 Agent 类的设计兼容，因为泛型参数主要用于类型提示，不影响运行时行为。

Test plan

• 运行新增的单元测试 tests/unit/test_star_register_agent.py
• 验证 @register_agent 装饰器可正常注册 subagent
• 确认不再触发 AstrAgentContext 的运行时导入

Fixes #5721

🤖 Generated with Claude Code

Summary by Sourcery

放宽 star 处理程序（handler）中 agent 和 run hook 的类型参数限制，以避免在运行时依赖 AstrAgentContext，并确保 register_agent 装饰器在运行时正常工作。

Bug Fixes:

• 通过移除对 AstrAgentContext 的运行时泛型依赖，修复了由于缺少 AstrAgentContext 而导致的 register_agent 装饰器运行时失败问题。

Tests:

• 新增单元测试，验证使用 register_agent 时不会在运行时触发对 AstrAgentContext 的导入，并且能够成功注册 agent。

Original summary in English

Summary by Sourcery

Relax agent and run hook type parameters in the star handler to avoid runtime dependencies on AstrAgentContext and ensure the register_agent decorator works at runtime.

Bug Fixes:

• Fix register_agent decorator runtime failure caused by missing AstrAgentContext by removing its runtime generic dependency.

Tests:

• Add a unit test verifying that using register_agent does not trigger a runtime import of AstrAgentContext and successfully registers an agent.

[dosubot]

Documentation Updates

1 document(s) were updated by changes in this PR:

pr4697的改动

View Changes

@@ -353,6 +353,51 @@
 - 消息格式为两行输出，第一行显示工具名称，第二行显示截断的返回结果
 
 工具分配可通过 UI 或配置文件完成。相关配置项说明已在配置文件注释中明确。
+
+#### 在插件中注册 SubAgent（PR #5765）
+
+[PR #5765](https://github.com/AstrBotDevs/AstrBot/pull/5765) 修复了插件开发者使用 `@register_agent` 装饰器时的运行时错误，确保插件可以正常注册子代理。
+
+**装饰器签名：**
+
+```python
+@register_agent(
+    name: str,
+    instruction: str,
+    tools: list[str | FunctionTool] | None = None,
+    run_hooks: BaseAgentRunHooks[Any] | None = None,
+)
+```
+
+**类型参数说明：**
+
+装饰器内部使用 `Agent[Any]` 和 `BaseAgentRunHooks[Any]` 泛型类型参数（而非 `AstrAgentContext`），以避免插件中的类型检查问题和运行时导入错误。这种设计确保插件开发者无需关心内部上下文类型，即可正常注册子代理。
+
+**使用示例：**
+
+插件开发者可通过 `@register_agent` 装饰器注册子代理，示例如下：
+
+```python
+from astrbot.api import register_agent
+from astrbot.api.event import AstrMessageEvent
+
+@register_agent(
+    name="DataProcessor",
+    instruction="处理和分析用户提供的数据",
+    tools=["read_file", "write_file"]
+)
+async def data_processor_handler(event: AstrMessageEvent):
+    # 子代理的自定义处理逻辑
+    return "Data processing complete"
+```
+
+注册后，主代理会自动生成 `transfer_to_DataProcessor` 工具，可通过该工具将任务委派给子代理。
+
+**修复说明：**
+
+修复前，装饰器使用 `Agent[AstrAgentContext]` 类型参数，但 `AstrAgentContext` 仅在 `TYPE_CHECKING` 块中导入（用于类型提示），运行时不可用。当插件调用装饰器时，会触发 `NameError: name 'AstrAgentContext' is not defined` 错误。
+
+修复后，装饰器改用 `Agent[Any]` 和 `BaseAgentRunHooks[Any]`，避免运行时对 `AstrAgentContext` 的依赖。此修改不影响运行时行为，因为泛型参数主要用于类型提示，与 Agent 类的设计完全兼容。
 
 ### 2. FutureTask（定时任务）机制
 

^{How did I do? Any feedback?}  

[sourcery-ai]

Hey - 我发现了 1 个问题，并留下了一些高层次的反馈：

• 将 Agent[AstrAgentContext] 和 BaseAgentRunHooks[AstrAgentContext] 切换为 Any 虽然能解决运行时问题，但会丢失类型安全性；建议引入一个类型变量（例如 TContext = TypeVar('TContext', bound=BaseContext)），在运行时默认使用 Any，同时为调用方保留更严格的类型约束。
• 测试中的 guarded_import 使用 name == 'astrbot.core.astr_agent_context' 来检查，这可能会遗漏通过不同拼写或包路径引入的导入；建议改用子串匹配或元组包含检查，使这个保护逻辑在重构时更稳健。
• 测试会修改 star_handler.llm_tools.func_list，并在 finally 中手动 pop；为避免测试之间可能的相互干扰，建议通过 fixture 或辅助函数来统一处理这些清理逻辑，以恢复列表的原始状态。

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- Switching `Agent[AstrAgentContext]` and `BaseAgentRunHooks[AstrAgentContext]` to `Any` fixes the runtime issue but loses type safety; consider introducing a type variable (e.g., `TContext = TypeVar('TContext', bound=BaseContext)`) that defaults to `Any` at runtime while preserving stricter typing for callers.
- The test’s `guarded_import` checks `name == 'astrbot.core.astr_agent_context'`, which may miss imports via different spellings or package paths; consider using a substring or tuple membership check to make this guard more robust to refactors.
- The test mutates `star_handler.llm_tools.func_list` and manually pops in `finally`; to avoid potential interference between tests, consider centralizing this cleanup via a fixture or helper that restores the original list state.

## Individual Comments

### Comment 1
<location path="tests/unit/test_star_register_agent.py" line_range="36-45" />
<code_context>
+    async def test_agent(_event, _context):
+        return "ok"
+
+    registering_agent = star_handler.register_agent(
+        name="test_agent",
+        instruction="You are a test helper.",
+    )(test_agent)
+
+    try:
+        assert isinstance(registering_agent, star_handler.RegisteringAgent)
+        assert registering_agent._agent.name == "test_agent"
+        assert isinstance(registering_agent._agent.run_hooks, BaseAgentRunHooks)
+        assert len(star_handler.llm_tools.func_list) == before_count + 1
+    finally:
+        if len(star_handler.llm_tools.func_list) > before_count:
</code_context>
<issue_to_address>
**suggestion (testing):** Strengthen the assertion to verify that the decorated coroutine is actually wired as the handoff handler.

The current test only checks that an agent is created and registered, not that `test_agent` is actually set as the handler on the underlying handoff tool. To cover the decorator’s runtime behavior, consider extending `_DummyHandoffTool` (e.g., track the last created instance) and assert that its `handler` attribute is `test_agent`. This verifies the decorator both avoids the runtime import and correctly wires the handler.

Suggested implementation:

```python
    try:
        assert isinstance(registering_agent, star_handler.RegisteringAgent)
        assert registering_agent._agent.name == "test_agent"
        assert isinstance(registering_agent._agent.run_hooks, BaseAgentRunHooks)
        assert len(star_handler.llm_tools.func_list) == before_count + 1

        # Verify that the decorated coroutine is wired as the handoff handler
        last_tool = star_handler.llm_tools.func_list[-1]
        assert isinstance(last_tool, _DummyHandoffTool)
        assert last_tool.handler is test_agent
    finally:
        if len(star_handler.llm_tools.func_list) > before_count:
            star_handler.llm_tools.func_list.pop()

```

This change assumes `_DummyHandoffTool` is already defined or imported in this test module (it likely is, given the usage of `llm_tools.func_list`). If it is defined under a different name or in a different module, update `_DummyHandoffTool` in the new assertions to the correct class name or import it into this file.
</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.}

Original comment in English

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

• Switching Agent[AstrAgentContext] and BaseAgentRunHooks[AstrAgentContext] to Any fixes the runtime issue but loses type safety; consider introducing a type variable (e.g., TContext = TypeVar('TContext', bound=BaseContext)) that defaults to Any at runtime while preserving stricter typing for callers.
• The test’s guarded_import checks name == 'astrbot.core.astr_agent_context', which may miss imports via different spellings or package paths; consider using a substring or tuple membership check to make this guard more robust to refactors.
• The test mutates star_handler.llm_tools.func_list and manually pops in finally; to avoid potential interference between tests, consider centralizing this cleanup via a fixture or helper that restores the original list state.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- Switching `Agent[AstrAgentContext]` and `BaseAgentRunHooks[AstrAgentContext]` to `Any` fixes the runtime issue but loses type safety; consider introducing a type variable (e.g., `TContext = TypeVar('TContext', bound=BaseContext)`) that defaults to `Any` at runtime while preserving stricter typing for callers.
- The test’s `guarded_import` checks `name == 'astrbot.core.astr_agent_context'`, which may miss imports via different spellings or package paths; consider using a substring or tuple membership check to make this guard more robust to refactors.
- The test mutates `star_handler.llm_tools.func_list` and manually pops in `finally`; to avoid potential interference between tests, consider centralizing this cleanup via a fixture or helper that restores the original list state.

## Individual Comments

### Comment 1
<location path="tests/unit/test_star_register_agent.py" line_range="36-45" />
<code_context>
+    async def test_agent(_event, _context):
+        return "ok"
+
+    registering_agent = star_handler.register_agent(
+        name="test_agent",
+        instruction="You are a test helper.",
+    )(test_agent)
+
+    try:
+        assert isinstance(registering_agent, star_handler.RegisteringAgent)
+        assert registering_agent._agent.name == "test_agent"
+        assert isinstance(registering_agent._agent.run_hooks, BaseAgentRunHooks)
+        assert len(star_handler.llm_tools.func_list) == before_count + 1
+    finally:
+        if len(star_handler.llm_tools.func_list) > before_count:
</code_context>
<issue_to_address>
**suggestion (testing):** Strengthen the assertion to verify that the decorated coroutine is actually wired as the handoff handler.

The current test only checks that an agent is created and registered, not that `test_agent` is actually set as the handler on the underlying handoff tool. To cover the decorator’s runtime behavior, consider extending `_DummyHandoffTool` (e.g., track the last created instance) and assert that its `handler` attribute is `test_agent`. This verifies the decorator both avoids the runtime import and correctly wires the handler.

Suggested implementation:

```python
    try:
        assert isinstance(registering_agent, star_handler.RegisteringAgent)
        assert registering_agent._agent.name == "test_agent"
        assert isinstance(registering_agent._agent.run_hooks, BaseAgentRunHooks)
        assert len(star_handler.llm_tools.func_list) == before_count + 1

        # Verify that the decorated coroutine is wired as the handoff handler
        last_tool = star_handler.llm_tools.func_list[-1]
        assert isinstance(last_tool, _DummyHandoffTool)
        assert last_tool.handler is test_agent
    finally:
        if len(star_handler.llm_tools.func_list) > before_count:
            star_handler.llm_tools.func_list.pop()

```

This change assumes `_DummyHandoffTool` is already defined or imported in this test module (it likely is, given the usage of `llm_tools.func_list`). If it is defined under a different name or in a different module, update `_DummyHandoffTool` in the new assertions to the correct class name or import it into this file.
</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.}

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

此拉取请求旨在解决 @register_agent 装饰器在使用时可能出现的 NameError，该错误源于 AstrAgentContext 在运行时不可用。通过将相关类型参数泛化为 Any，并移除条件导入，确保了装饰器在不依赖特定上下文类运行时存在的情况下也能正常工作，从而提高了代理注册机制的健壮性和兼容性。

Highlights

• 错误修复: 修复了 @register_agent 装饰器在插件中使用时导致的 NameError: name 'AstrAgentContext' is not defined 错误。
• 类型参数泛化: 将 Agent[AstrAgentContext] 和 BaseAgentRunHooks[AstrAgentContext] 的类型参数更改为 Any。
• 移除运行时依赖: 移除了 TYPE_CHECKING 块中对 AstrAgentContext 的导入，以避免运行时依赖。
• 新增单元测试: 新增了单元测试来验证修复效果，确保 register_agent 装饰器在运行时不会触发 AstrAgentContext 的导入。

Changelog

• astrbot/core/star/register/star_handler.py
  • 移除了 TYPE_CHECKING 块中对 AstrAgentContext 的导入。
  • 将 RegisteringAgent 类的 __init__ 方法和 register_agent 函数中的 Agent 和 BaseAgentRunHooks 的泛型参数从 AstrAgentContext 修改为 Any。
• tests/unit/test_star_register_agent.py
  • 新增了一个单元测试文件，用于验证 register_agent 装饰器在运行时不会尝试导入 astrbot.core.astr_agent_context，并能成功注册代理。

Activity

• 此拉取请求自创建以来，没有人工活动。

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

此拉取请求解决了在使用 @register_agent 装饰器时出现的 NameError，该错误与 AstrAgentContext 的运行时依赖有关。通过将 Agent 和 BaseAgentRunHooks 的类型参数从 AstrAgentContext 更改为 Any，并移除 TYPE_CHECKING 块中对 AstrAgentContext 的导入，成功避免了运行时对该类的依赖。新增的单元测试有效验证了此修复，确保了 AstrAgentContext 不会在运行时被意外导入，并且代理注册功能正常。这些更改直接且有效地解决了问题，同时保持了类型检查的能力。

[Copilot]

Pull request overview

该 PR 修复了第三方插件在运行时使用 @register_agent 装饰器时触发的 NameError: name 'AstrAgentContext' is not defined 问题，通过避免在运行时对 AstrAgentContext 的泛型实参求值来解除依赖，并补充单测覆盖该回归场景。

Changes:

• 将 register_agent 相关的 Agent[...] / BaseAgentRunHooks[...] 泛型参数从 AstrAgentContext 调整为 Any，消除运行时 NameError。
• 移除 star_handler.py 中不再需要的 TYPE_CHECKING 导入块。
• 新增单元测试，验证 register_agent 装饰器执行过程中不会触发 AstrAgentContext 的运行时导入，且可正常注册 handoff tool。

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
astrbot/core/star/register/star_handler.py	调整 register_agent / RegisteringAgent 的运行时泛型求值方式，避免引用未导入的 AstrAgentContext。
tests/unit/test_star_register_agent.py	新增回归测试覆盖：调用 register_agent 时不发生 AstrAgentContext 运行时导入且注册行为正常。