AstrBot 4.5.6__py3-none-any.whl → 4.5.8__py3-none-any.whl

astrbot/api/all.py

@@ -36,7 +36,8 @@ from astrbot.core.star.config import *
 
 
 # provider
-from astrbot.core.provider import Provider, Personality, ProviderMetaData
+from astrbot.core.provider import Provider, ProviderMetaData
+from astrbot.core.db.po import Personality
 
 # platform
 from astrbot.core.platform import (

astrbot/api/provider/__init__.py

@@ -1,4 +1,5 @@
-from astrbot.core.provider import Personality, Provider, STTProvider
+from astrbot.core.db.po import Personality
+from astrbot.core.provider import Provider, STTProvider
 from astrbot.core.provider.entities import (
     LLMResponse,
     ProviderMetaData,

astrbot/core/agent/message.py

@@ -76,7 +76,7 @@ class ImageURLPart(ContentPart):
         """The ID of the image, to allow LLMs to distinguish different images."""
 
     type: str = "image_url"
-    image_url: str
+    image_url: ImageURL
 
 
 class AudioURLPart(ContentPart):

astrbot/core/agent/run_context.py

@@ -1,16 +1,21 @@
-from dataclasses import dataclass
 from typing import Any, Generic
 
+from pydantic import Field
+from pydantic.dataclasses import dataclass
 from typing_extensions import TypeVar
 
+from .message import Message
+
 TContext = TypeVar("TContext", default=Any)
 
 
-@dataclass
+@dataclass(config={"arbitrary_types_allowed": True})
 class ContextWrapper(Generic[TContext]):
     """A context for running an agent, which can be used to pass additional data or state."""
 
     context: TContext
+    messages: list[Message] = Field(default_factory=list)
+    """This field stores the llm message context for the agent run, agent runners will maintain this field automatically."""
     tool_call_timeout: int = 60  # Default tool call timeout in seconds
 
 

astrbot/core/agent/runners/base.py

@@ -40,6 +40,13 @@ class BaseAgentRunner(T.Generic[TContext]):
         """Process a single step of the agent."""
         ...
 
+    @abc.abstractmethod
+    async def step_until_done(
+        self, max_step: int
+    ) -> T.AsyncGenerator[AgentResponse, None]:
+        """Process steps until the agent is done."""
+        ...
+
     @abc.abstractmethod
     def done(self) -> bool:
         """Check if the agent has completed its task.

astrbot/core/agent/runners/tool_loop_agent_runner.py

@@ -23,7 +23,7 @@ from astrbot.core.provider.entities import (
 from astrbot.core.provider.provider import Provider
 
 from ..hooks import BaseAgentRunHooks
-from ..message import AssistantMessageSegment, ToolCallMessageSegment
+from ..message import AssistantMessageSegment, Message, ToolCallMessageSegment
 from ..response import AgentResponseData
 from ..run_context import ContextWrapper, TContext
 from ..tool_executor import BaseFunctionToolExecutor
@@ -55,6 +55,20 @@ class ToolLoopAgentRunner(BaseAgentRunner[TContext]):
         self.agent_hooks = agent_hooks
         self.run_context = run_context
 
+        messages = []
+        # append existing messages in the run context
+        for msg in request.contexts:
+            messages.append(Message.model_validate(msg))
+        if request.prompt is not None:
+            m = await request.assemble_context()
+            messages.append(Message.model_validate(m))
+        if request.system_prompt:
+            messages.insert(
+                0,
+                Message(role="system", content=request.system_prompt),
+            )
+        self.run_context.messages = messages
+
     def _transition_state(self, new_state: AgentState) -> None:
         """转换 Agent 状态"""
         if self._state != new_state:
@@ -96,13 +110,22 @@ class ToolLoopAgentRunner(BaseAgentRunner[TContext]):
                         type="streaming_delta",
                         data=AgentResponseData(chain=llm_response.result_chain),
                     )
-                else:
+                elif llm_response.completion_text:
                     yield AgentResponse(
                         type="streaming_delta",
                         data=AgentResponseData(
                             chain=MessageChain().message(llm_response.completion_text),
                         ),
                     )
+                elif llm_response.reasoning_content:
+                    yield AgentResponse(
+                        type="streaming_delta",
+                        data=AgentResponseData(
+                            chain=MessageChain(type="reasoning").message(
+                                llm_response.reasoning_content,
+                            ),
+                        ),
+                    )
                 continue
             llm_resp_result = llm_response
             break  # got final response
@@ -130,6 +153,13 @@ class ToolLoopAgentRunner(BaseAgentRunner[TContext]):
             # 如果没有工具调用，转换到完成状态
             self.final_llm_resp = llm_resp
             self._transition_state(AgentState.DONE)
+            # record the final assistant message
+            self.run_context.messages.append(
+                Message(
+                    role="assistant",
+                    content=llm_resp.completion_text or "",
+                ),
+            )
             try:
                 await self.agent_hooks.on_agent_done(self.run_context, llm_resp)
             except Exception as e:
@@ -156,13 +186,16 @@ class ToolLoopAgentRunner(BaseAgentRunner[TContext]):
                 yield AgentResponse(
                     type="tool_call",
                     data=AgentResponseData(
-                        chain=MessageChain().message(f"🔨 调用工具: {tool_call_name}"),
+                        chain=MessageChain(type="tool_call").message(
+                            f"🔨 调用工具: {tool_call_name}"
+                        ),
                     ),
                 )
             async for result in self._handle_function_tools(self.req, llm_resp):
                 if isinstance(result, list):
                     tool_call_result_blocks = result
                 elif isinstance(result, MessageChain):
+                    result.type = "tool_call_result"
                     yield AgentResponse(
                         type="tool_call_result",
                         data=AgentResponseData(chain=result),
@@ -175,8 +208,23 @@ class ToolLoopAgentRunner(BaseAgentRunner[TContext]):
                 ),
                 tool_calls_result=tool_call_result_blocks,
             )
+            # record the assistant message with tool calls
+            self.run_context.messages.extend(
+                tool_calls_result.to_openai_messages_model()
+            )
+
             self.req.append_tool_calls_result(tool_calls_result)
 
+    async def step_until_done(
+        self, max_step: int
+    ) -> T.AsyncGenerator[AgentResponse, None]:
+        """Process steps until the agent is done."""
+        step_count = 0
+        while not self.done() and step_count < max_step:
+            step_count += 1
+            async for resp in self.step():
+                yield resp
+
     async def _handle_function_tools(
         self,
         req: ProviderRequest,

astrbot/core/agent/tool.py

@@ -4,12 +4,13 @@ from typing import Any, Generic
 import jsonschema
 import mcp
 from deprecated import deprecated
-from pydantic import model_validator
+from pydantic import Field, model_validator
 from pydantic.dataclasses import dataclass
 
 from .run_context import ContextWrapper, TContext
 
 ParametersType = dict[str, Any]
+ToolExecResult = str | mcp.types.CallToolResult
 
 
 @dataclass
@@ -55,15 +56,14 @@ class FunctionTool(ToolSchema, Generic[TContext]):
     def __repr__(self):
         return f"FuncTool(name={self.name}, parameters={self.parameters}, description={self.description})"
 
-    async def call(
-        self, context: ContextWrapper[TContext], **kwargs
-    ) -> str | mcp.types.CallToolResult:
+    async def call(self, context: ContextWrapper[TContext], **kwargs) -> ToolExecResult:
         """Run the tool with the given arguments. The handler field has priority."""
         raise NotImplementedError(
             "FunctionTool.call() must be implemented by subclasses or set a handler."
         )
 
 
+@dataclass
 class ToolSet:
     """A set of function tools that can be used in function calling.
 
@@ -71,8 +71,7 @@ class ToolSet:
     convert the tools to different API formats (OpenAI, Anthropic, Google GenAI).
     """
 
-    def __init__(self, tools: list[FunctionTool] | None = None):
-        self.tools: list[FunctionTool] = tools or []
+    tools: list[FunctionTool] = Field(default_factory=list)
 
     def empty(self) -> bool:
         """Check if the tool set is empty."""

astrbot/core/astr_agent_context.py

@@ -1,14 +1,19 @@
-from dataclasses import dataclass
+from pydantic import Field
+from pydantic.dataclasses import dataclass
 
+from astrbot.core.agent.run_context import ContextWrapper
 from astrbot.core.platform.astr_message_event import AstrMessageEvent
-from astrbot.core.provider import Provider
-from astrbot.core.provider.entities import ProviderRequest
+from astrbot.core.star.context import Context
 
 
-@dataclass
+@dataclass(config={"arbitrary_types_allowed": True})
 class AstrAgentContext:
-    provider: Provider
-    first_provider_request: ProviderRequest
-    curr_provider_request: ProviderRequest
-    streaming: bool
+    context: Context
+    """The star context instance"""
     event: AstrMessageEvent
+    """The message event associated with the agent context."""
+    extra: dict[str, str] = Field(default_factory=dict)
+    """Customized extra data."""
+
+
+AgentContextWrapper = ContextWrapper[AstrAgentContext]

astrbot/core/astr_agent_hooks.py

@@ -0,0 +1,36 @@
+from typing import Any
+
+from mcp.types import CallToolResult
+
+from astrbot.core.agent.hooks import BaseAgentRunHooks
+from astrbot.core.agent.run_context import ContextWrapper
+from astrbot.core.agent.tool import FunctionTool
+from astrbot.core.astr_agent_context import AstrAgentContext
+from astrbot.core.pipeline.context_utils import call_event_hook
+from astrbot.core.star.star_handler import EventType
+
+
+class MainAgentHooks(BaseAgentRunHooks[AstrAgentContext]):
+    async def on_agent_done(self, run_context, llm_response):
+        # 执行事件钩子
+        await call_event_hook(
+            run_context.context.event,
+            EventType.OnLLMResponseEvent,
+            llm_response,
+        )
+
+    async def on_tool_end(
+        self,
+        run_context: ContextWrapper[AstrAgentContext],
+        tool: FunctionTool[Any],
+        tool_args: dict | None,
+        tool_result: CallToolResult | None,
+    ):
+        run_context.context.event.clear_result()
+
+
+class EmptyAgentHooks(BaseAgentRunHooks[AstrAgentContext]):
+    pass
+
+
+MAIN_AGENT_HOOKS = MainAgentHooks()

astrbot/core/astr_agent_run_util.py

@@ -0,0 +1,80 @@
+import traceback
+from collections.abc import AsyncGenerator
+
+from astrbot.core import logger
+from astrbot.core.agent.runners.tool_loop_agent_runner import ToolLoopAgentRunner
+from astrbot.core.astr_agent_context import AstrAgentContext
+from astrbot.core.message.message_event_result import (
+    MessageChain,
+    MessageEventResult,
+    ResultContentType,
+)
+
+AgentRunner = ToolLoopAgentRunner[AstrAgentContext]
+
+
+async def run_agent(
+    agent_runner: AgentRunner,
+    max_step: int = 30,
+    show_tool_use: bool = True,
+    stream_to_general: bool = False,
+    show_reasoning: bool = False,
+) -> AsyncGenerator[MessageChain | None, None]:
+    step_idx = 0
+    astr_event = agent_runner.run_context.context.event
+    while step_idx < max_step:
+        step_idx += 1
+        try:
+            async for resp in agent_runner.step():
+                if astr_event.is_stopped():
+                    return
+                if resp.type == "tool_call_result":
+                    msg_chain = resp.data["chain"]
+                    if msg_chain.type == "tool_direct_result":
+                        # tool_direct_result 用于标记 llm tool 需要直接发送给用户的内容
+                        await astr_event.send(resp.data["chain"])
+                        continue
+                    # 对于其他情况，暂时先不处理
+                    continue
+                elif resp.type == "tool_call":
+                    if agent_runner.streaming:
+                        # 用来标记流式响应需要分节
+                        yield MessageChain(chain=[], type="break")
+                    if show_tool_use:
+                        await astr_event.send(resp.data["chain"])
+                    continue
+
+                if stream_to_general and resp.type == "streaming_delta":
+                    continue
+
+                if stream_to_general or not agent_runner.streaming:
+                    content_typ = (
+                        ResultContentType.LLM_RESULT
+                        if resp.type == "llm_result"
+                        else ResultContentType.GENERAL_RESULT
+                    )
+                    astr_event.set_result(
+                        MessageEventResult(
+                            chain=resp.data["chain"].chain,
+                            result_content_type=content_typ,
+                        ),
+                    )
+                    yield
+                    astr_event.clear_result()
+                elif resp.type == "streaming_delta":
+                    chain = resp.data["chain"]
+                    if chain.type == "reasoning" and not show_reasoning:
+                        # display the reasoning content only when configured
+                        continue
+                    yield resp.data["chain"]  # MessageChain
+            if agent_runner.done():
+                break
+
+        except Exception as e:
+            logger.error(traceback.format_exc())
+            err_msg = f"\n\nAstrBot 请求失败。\n错误类型: {type(e).__name__}\n错误信息: {e!s}\n\n请在控制台查看和分享错误详情。\n"
+            if agent_runner.streaming:
+                yield MessageChain().message(err_msg)
+            else:
+                astr_event.set_result(MessageEventResult().message(err_msg))
+            return

astrbot/core/astr_agent_tool_exec.py

@@ -0,0 +1,246 @@
+import asyncio
+import inspect
+import traceback
+import typing as T
+
+import mcp
+
+from astrbot import logger
+from astrbot.core.agent.handoff import HandoffTool
+from astrbot.core.agent.mcp_client import MCPTool
+from astrbot.core.agent.run_context import ContextWrapper
+from astrbot.core.agent.tool import FunctionTool, ToolSet
+from astrbot.core.agent.tool_executor import BaseFunctionToolExecutor
+from astrbot.core.astr_agent_context import AstrAgentContext
+from astrbot.core.message.message_event_result import (
+    CommandResult,
+    MessageChain,
+    MessageEventResult,
+)
+from astrbot.core.provider.register import llm_tools
+
+
+class FunctionToolExecutor(BaseFunctionToolExecutor[AstrAgentContext]):
+    @classmethod
+    async def execute(cls, tool, run_context, **tool_args):
+        """执行函数调用。
+
+        Args:
+            event (AstrMessageEvent): 事件对象, 当 origin 为 local 时必须提供。
+            **kwargs: 函数调用的参数。
+
+        Returns:
+            AsyncGenerator[None | mcp.types.CallToolResult, None]
+
+        """
+        if isinstance(tool, HandoffTool):
+            async for r in cls._execute_handoff(tool, run_context, **tool_args):
+                yield r
+            return
+
+        elif isinstance(tool, MCPTool):
+            async for r in cls._execute_mcp(tool, run_context, **tool_args):
+                yield r
+            return
+
+        else:
+            async for r in cls._execute_local(tool, run_context, **tool_args):
+                yield r
+            return
+
+    @classmethod
+    async def _execute_handoff(
+        cls,
+        tool: HandoffTool,
+        run_context: ContextWrapper[AstrAgentContext],
+        **tool_args,
+    ):
+        input_ = tool_args.get("input")
+
+        # make toolset for the agent
+        tools = tool.agent.tools
+        if tools:
+            toolset = ToolSet()
+            for t in tools:
+                if isinstance(t, str):
+                    _t = llm_tools.get_func(t)
+                    if _t:
+                        toolset.add_tool(_t)
+                elif isinstance(t, FunctionTool):
+                    toolset.add_tool(t)
+        else:
+            toolset = None
+
+        ctx = run_context.context.context
+        event = run_context.context.event
+        umo = event.unified_msg_origin
+        prov_id = await ctx.get_current_chat_provider_id(umo)
+        llm_resp = await ctx.tool_loop_agent(
+            event=event,
+            chat_provider_id=prov_id,
+            prompt=input_,
+            system_prompt=tool.agent.instructions,
+            tools=toolset,
+            max_steps=30,
+            run_hooks=tool.agent.run_hooks,
+        )
+        yield mcp.types.CallToolResult(
+            content=[mcp.types.TextContent(type="text", text=llm_resp.completion_text)]
+        )
+
+    @classmethod
+    async def _execute_local(
+        cls,
+        tool: FunctionTool,
+        run_context: ContextWrapper[AstrAgentContext],
+        **tool_args,
+    ):
+        event = run_context.context.event
+        if not event:
+            raise ValueError("Event must be provided for local function tools.")
+
+        is_override_call = False
+        for ty in type(tool).mro():
+            if "call" in ty.__dict__ and ty.__dict__["call"] is not FunctionTool.call:
+                is_override_call = True
+                break
+
+        # 检查 tool 下有没有 run 方法
+        if not tool.handler and not hasattr(tool, "run") and not is_override_call:
+            raise ValueError("Tool must have a valid handler or override 'run' method.")
+
+        awaitable = None
+        method_name = ""
+        if tool.handler:
+            awaitable = tool.handler
+            method_name = "decorator_handler"
+        elif is_override_call:
+            awaitable = tool.call
+            method_name = "call"
+        elif hasattr(tool, "run"):
+            awaitable = getattr(tool, "run")
+            method_name = "run"
+        if awaitable is None:
+            raise ValueError("Tool must have a valid handler or override 'run' method.")
+
+        wrapper = call_local_llm_tool(
+            context=run_context,
+            handler=awaitable,
+            method_name=method_name,
+            **tool_args,
+        )
+        while True:
+            try:
+                resp = await asyncio.wait_for(
+                    anext(wrapper),
+                    timeout=run_context.tool_call_timeout,
+                )
+                if resp is not None:
+                    if isinstance(resp, mcp.types.CallToolResult):
+                        yield resp
+                    else:
+                        text_content = mcp.types.TextContent(
+                            type="text",
+                            text=str(resp),
+                        )
+                        yield mcp.types.CallToolResult(content=[text_content])
+                else:
+                    # NOTE: Tool 在这里直接请求发送消息给用户
+                    # TODO: 是否需要判断 event.get_result() 是否为空?
+                    # 如果为空,则说明没有发送消息给用户,并且返回值为空,将返回一个特殊的 TextContent,其内容如"工具没有返回内容"
+                    if res := run_context.context.event.get_result():
+                        if res.chain:
+                            try:
+                                await event.send(
+                                    MessageChain(
+                                        chain=res.chain,
+                                        type="tool_direct_result",
+                                    )
+                                )
+                            except Exception as e:
+                                logger.error(
+                                    f"Tool 直接发送消息失败: {e}",
+                                    exc_info=True,
+                                )
+                    yield None
+            except asyncio.TimeoutError:
+                raise Exception(
+                    f"tool {tool.name} execution timeout after {run_context.tool_call_timeout} seconds.",
+                )
+            except StopAsyncIteration:
+                break
+
+    @classmethod
+    async def _execute_mcp(
+        cls,
+        tool: FunctionTool,
+        run_context: ContextWrapper[AstrAgentContext],
+        **tool_args,
+    ):
+        res = await tool.call(run_context, **tool_args)
+        if not res:
+            return
+        yield res
+
+
+async def call_local_llm_tool(
+    context: ContextWrapper[AstrAgentContext],
+    handler: T.Callable[..., T.Awaitable[T.Any]],
+    method_name: str,
+    *args,
+    **kwargs,
+) -> T.AsyncGenerator[T.Any, None]:
+    """执行本地 LLM 工具的处理函数并处理其返回结果"""
+    ready_to_call = None  # 一个协程或者异步生成器
+
+    trace_ = None
+
+    event = context.context.event
+
+    try:
+        if method_name == "run" or method_name == "decorator_handler":
+            ready_to_call = handler(event, *args, **kwargs)
+        elif method_name == "call":
+            ready_to_call = handler(context, *args, **kwargs)
+        else:
+            raise ValueError(f"未知的方法名: {method_name}")
+    except ValueError as e:
+        logger.error(f"调用本地 LLM 工具时出错: {e}", exc_info=True)
+    except TypeError:
+        logger.error("处理函数参数不匹配，请检查 handler 的定义。", exc_info=True)
+    except Exception as e:
+        trace_ = traceback.format_exc()
+        logger.error(f"调用本地 LLM 工具时出错: {e}\n{trace_}")
+
+    if not ready_to_call:
+        return
+
+    if inspect.isasyncgen(ready_to_call):
+        _has_yielded = False
+        try:
+            async for ret in ready_to_call:
+                # 这里逐步执行异步生成器, 对于每个 yield 返回的 ret, 执行下面的代码
+                # 返回值只能是 MessageEventResult 或者 None（无返回值）
+                _has_yielded = True
+                if isinstance(ret, (MessageEventResult, CommandResult)):
+                    # 如果返回值是 MessageEventResult, 设置结果并继续
+                    event.set_result(ret)
+                    yield
+                else:
+                    # 如果返回值是 None, 则不设置结果并继续
+                    # 继续执行后续阶段
+                    yield ret
+            if not _has_yielded:
+                # 如果这个异步生成器没有执行到 yield 分支
+                yield
+        except Exception as e:
+            logger.error(f"Previous Error: {trace_}")
+            raise e
+    elif inspect.iscoroutine(ready_to_call):
+        # 如果只是一个协程, 直接执行
+        ret = await ready_to_call
+        if isinstance(ret, (MessageEventResult, CommandResult)):
+            event.set_result(ret)
+            yield
+        else:
+            yield ret