mirror of
https://github.com/zhenxun-org/zhenxun_bot.git
synced 2026-11-04 03:30:10 +08:00
280 lines
8.9 KiB
Python
280 lines
8.9 KiB
Python
|
"""
|
|||
|
|
运行时（Run）相关核心类型定义
|
|||
|
|
"""
|
|||
|
|
|
|||
|
|
from collections.abc import AsyncIterator
|
|||
|
|
import json
|
|||
|
|
from typing import Any, Generic, cast
|
|||
|
|
from typing_extensions import TypeVar
|
|||
|
|
|
|||
|
|
from pydantic import BaseModel, ConfigDict, Field, PrivateAttr
|
|||
|
|
|
|||
|
|
from zhenxun.services.ai.core.messages import AgentMessage, LLMMessage, UsageInfo
|
|||
|
|
from zhenxun.services.ai.core.stream_events import (
|
|||
|
|
AgentStreamEvent,
|
|||
|
|
EventBus,
|
|||
|
|
ToolCallStartEvent,
|
|||
|
|
ToolStreamChunkEvent,
|
|||
|
|
)
|
|||
|
|
from zhenxun.utils.pydantic_compat import model_dump, model_validator
|
|||
|
|
|
|||
|
|
|
|||
|
|
class ChatSummary(BaseModel):
|
|||
|
|
total: int = 0
|
|||
|
|
"""大模型调用总次数"""
|
|||
|
|
total_latency_ms: float = 0.0
|
|||
|
|
"""大模型调用总耗时（毫秒）"""
|
|||
|
|
by_stop_reason: dict[str, int] = Field(default_factory=dict)
|
|||
|
|
"""按停止原因分类的大模型调用计数"""
|
|||
|
|
|
|||
|
|
|
|||
|
|
class ToolSummary(BaseModel):
|
|||
|
|
total: int = 0
|
|||
|
|
"""工具执行总次数"""
|
|||
|
|
ok: int = 0
|
|||
|
|
"""工具成功执行次数"""
|
|||
|
|
error: int = 0
|
|||
|
|
"""工具执行失败次数"""
|
|||
|
|
total_latency_ms: float = 0.0
|
|||
|
|
"""工具执行总耗时（毫秒）"""
|
|||
|
|
by_name: dict[str, dict[str, Any]] = Field(default_factory=dict)
|
|||
|
|
"""按工具名称细分的执行状态统计"""
|
|||
|
|
|
|||
|
|
|
|||
|
|
class AgentRunSummary(BaseModel):
|
|||
|
|
"""Agent 单次运行的全局可观测性遥测摘要"""
|
|||
|
|
|
|||
|
|
chats: ChatSummary = Field(default_factory=ChatSummary)
|
|||
|
|
"""大模型调用遥测摘要"""
|
|||
|
|
tools: ToolSummary = Field(default_factory=ToolSummary)
|
|||
|
|
"""工具执行遥测摘要"""
|
|||
|
|
usage: UsageInfo = Field(default_factory=UsageInfo)
|
|||
|
|
"""Token 消耗总计"""
|
|||
|
|
total_latency_ms: float = 0.0
|
|||
|
|
"""智能体运行总耗时（毫秒）"""
|
|||
|
|
|
|||
|
|
|
|||
|
|
class HandoffPayload(BaseModel):
|
|||
|
|
"""移交信息载荷"""
|
|||
|
|
|
|||
|
|
target: str
|
|||
|
|
"""移交的目标智能体名称"""
|
|||
|
|
reason: str = ""
|
|||
|
|
"""移交的原因描述"""
|
|||
|
|
context_data: Any = ""
|
|||
|
|
"""随移交传递的上下文数据"""
|
|||
|
|
|
|||
|
|
|
|||
|
|
OutputDataT = TypeVar("OutputDataT", default=str)
|
|||
|
|
|
|||
|
|
|
|||
|
|
class AgentRunResult(BaseModel, Generic[OutputDataT]):
|
|||
|
|
"""Agent 单次无状态运行的结果"""
|
|||
|
|
|
|||
|
|
output: OutputDataT
|
|||
|
|
"""最终输出数据"""
|
|||
|
|
messages: list[AgentMessage] = Field(default_factory=list)
|
|||
|
|
"""本次运行产生/更新的历史消息"""
|
|||
|
|
usage: UsageInfo = Field(default_factory=UsageInfo)
|
|||
|
|
"""本次运行的Token消耗总计"""
|
|||
|
|
structured_data: Any | None = None
|
|||
|
|
"""拦截到的结构化结果字典"""
|
|||
|
|
telemetry: AgentRunSummary | None = None
|
|||
|
|
"""单次运行的完整可观测性遥测摘要"""
|
|||
|
|
handoff: HandoffPayload | None = None
|
|||
|
|
"""向外抛出的软移交载荷（存在时说明Agent发起了移交请求）"""
|
|||
|
|
|
|||
|
|
class Config:
|
|||
|
|
arbitrary_types_allowed = True
|
|||
|
|
|
|||
|
|
@property
|
|||
|
|
def llm_messages(self) -> list[LLMMessage]:
|
|||
|
|
"""动态视图：过滤掉内部业务事件 (AgentEvent)，
|
|||
|
|
仅返回纯净的底层聊天消息历史"""
|
|||
|
|
return [m for m in self.messages if isinstance(m, LLMMessage)]
|
|||
|
|
|
|||
|
|
|
|||
|
|
class AgentRunStart(AgentStreamEvent):
|
|||
|
|
"""智能体运行开始"""
|
|||
|
|
|
|||
|
|
agent_name: str
|
|||
|
|
"""启动运行的智能体名称"""
|
|||
|
|
|
|||
|
|
|
|||
|
|
class AgentRunError(AgentStreamEvent):
|
|||
|
|
"""智能体运行发生异常"""
|
|||
|
|
|
|||
|
|
error: BaseException
|
|||
|
|
"""智能体运行过程中抛出的异常"""
|
|||
|
|
|
|||
|
|
|
|||
|
|
class AgentRunEnd(AgentStreamEvent):
|
|||
|
|
"""智能体运行完全结束"""
|
|||
|
|
|
|||
|
|
result: AgentRunResult[Any]
|
|||
|
|
"""智能体运行结束后的完整结果"""
|
|||
|
|
|
|||
|
|
|
|||
|
|
class StreamedRunResult(Generic[OutputDataT]):
|
|||
|
|
"""
|
|||
|
|
智能体流式运行的结果代理对象。
|
|||
|
|
提供高度解耦的方法来消费底层事件流，支持获取纯净文本或全部事件。
|
|||
|
|
"""
|
|||
|
|
|
|||
|
|
def __init__(self, event_bus: EventBus):
|
|||
|
|
self._event_bus = event_bus
|
|||
|
|
self.is_complete: bool = False
|
|||
|
|
self._result: AgentRunResult[OutputDataT] | None = None
|
|||
|
|
|
|||
|
|
async def stream_events(self) -> AsyncIterator[Any]:
|
|||
|
|
"""获取底层的所有原始事件（包含工具调用过程等）"""
|
|||
|
|
from zhenxun.services.ai.run.models import AgentRunEnd, AgentRunError
|
|||
|
|
|
|||
|
|
async for event in self._event_bus:
|
|||
|
|
if isinstance(event, AgentRunEnd):
|
|||
|
|
self._result = cast(AgentRunResult[OutputDataT], event.result)
|
|||
|
|
self.is_complete = True
|
|||
|
|
elif isinstance(event, AgentRunError):
|
|||
|
|
raise event.error.with_traceback(None) from None
|
|||
|
|
yield event
|
|||
|
|
|
|||
|
|
async def stream_text(self, delta: bool = False) -> AsyncIterator[str]:
|
|||
|
|
"""
|
|||
|
|
过滤大模型的输出文本。
|
|||
|
|
"""
|
|||
|
|
full_text = ""
|
|||
|
|
async for _ in self.stream_events():
|
|||
|
|
pass
|
|||
|
|
|
|||
|
|
if self._result is not None:
|
|||
|
|
output = self._result.output
|
|||
|
|
if isinstance(output, str):
|
|||
|
|
full_text = output
|
|||
|
|
else:
|
|||
|
|
if isinstance(output, BaseModel):
|
|||
|
|
full_text = json.dumps(model_dump(output), ensure_ascii=False)
|
|||
|
|
else:
|
|||
|
|
full_text = str(output)
|
|||
|
|
|
|||
|
|
if delta:
|
|||
|
|
yield full_text
|
|||
|
|
else:
|
|||
|
|
yield full_text
|
|||
|
|
|
|||
|
|
async def get_output(self) -> OutputDataT:
|
|||
|
|
"""阻塞并等待整个 Agent 执行完毕，返回最终的解析输出数据"""
|
|||
|
|
if self._result is not None:
|
|||
|
|
return self._result.output
|
|||
|
|
|
|||
|
|
async for _ in self.stream_events():
|
|||
|
|
pass
|
|||
|
|
|
|||
|
|
if self._result is None:
|
|||
|
|
raise RuntimeError("Agent 运行异常结束，未产生最终结果。")
|
|||
|
|
|
|||
|
|
return self._result.output
|
|||
|
|
|
|||
|
|
async def get_run_result(self) -> AgentRunResult[OutputDataT]:
|
|||
|
|
"""获取完整的运行结果对象（包含 Token 消耗等）"""
|
|||
|
|
if self._result is not None:
|
|||
|
|
return self._result
|
|||
|
|
|
|||
|
|
await self.get_output()
|
|||
|
|
|
|||
|
|
return cast(AgentRunResult[OutputDataT], self._result)
|
|||
|
|
|
|||
|
|
async def forward_to(
|
|||
|
|
self, target_event_bus: EventBus | None, prefix_name: str
|
|||
|
|
) -> AgentRunResult[OutputDataT]:
|
|||
|
|
"""将底层的事件流自动格式化并转发给另一个事件发射器，
|
|||
|
|
常用于 DelegateTool 嵌套调用"""
|
|||
|
|
async for event in self.stream_events():
|
|||
|
|
if not target_event_bus:
|
|||
|
|
continue
|
|||
|
|
|
|||
|
|
if isinstance(event, ToolStreamChunkEvent):
|
|||
|
|
await target_event_bus.emit(
|
|||
|
|
ToolStreamChunkEvent(
|
|||
|
|
tool_name=f"{prefix_name} -> {event.tool_name}",
|
|||
|
|
content=event.content,
|
|||
|
|
metadata=event.metadata,
|
|||
|
|
)
|
|||
|
|
)
|
|||
|
|
elif isinstance(event, ToolCallStartEvent):
|
|||
|
|
intent_str = (
|
|||
|
|
f" (意图: {event.intent})" if getattr(event, "intent", None) else ""
|
|||
|
|
)
|
|||
|
|
await target_event_bus.emit(
|
|||
|
|
ToolStreamChunkEvent(
|
|||
|
|
tool_name=prefix_name,
|
|||
|
|
content=f"🔁 正在调用工具: {event.tool_name}...{intent_str}",
|
|||
|
|
)
|
|||
|
|
)
|
|||
|
|
|
|||
|
|
return await self.get_run_result()
|
|||
|
|
|
|||
|
|
|
|||
|
|
class TaskResult(BaseModel):
|
|||
|
|
"""单个数据契约任务的执行结果"""
|
|||
|
|
|
|||
|
|
task_id: str
|
|||
|
|
"""关联的任务唯一 ID"""
|
|||
|
|
|
|||
|
|
output: Any
|
|||
|
|
"""任务的实际产出（如果是结构化任务，则为解析后的 Pydantic 实例；否则为纯文本）"""
|
|||
|
|
|
|||
|
|
raw_response: str | None = None
|
|||
|
|
"""大模型返回的原始纯文本内容"""
|
|||
|
|
|
|||
|
|
usage: UsageInfo = Field(default_factory=UsageInfo)
|
|||
|
|
"""该任务执行期间的 Token 消耗统计"""
|
|||
|
|
|
|||
|
|
model_config = ConfigDict(arbitrary_types_allowed=True)
|
|||
|
|
|
|||
|
|
|
|||
|
|
class Task(BaseModel):
|
|||
|
|
"""标准化数据契约（意图载体 Payload），定义大模型需要做什么及产出什么格式"""
|
|||
|
|
|
|||
|
|
id: str = Field(default_factory=lambda: __import__("uuid").uuid4().hex)
|
|||
|
|
"""任务的唯一标识符"""
|
|||
|
|
|
|||
|
|
name: str | None = None
|
|||
|
|
"""任务的简短名称"""
|
|||
|
|
|
|||
|
|
description: str
|
|||
|
|
"""详细的任务指令（告诉大模型具体需要做什么）"""
|
|||
|
|
|
|||
|
|
expected_output: str
|
|||
|
|
"""预期输出的自然语言描述（指导大模型如何组织最终答案）"""
|
|||
|
|
|
|||
|
|
response_model: Any | None = None
|
|||
|
|
"""强制要求返回的强类型结构 (Pydantic Model) 或
|
|||
|
|
OutputDefinition，为空则返回普通文本"""
|
|||
|
|
|
|||
|
|
tools: list[str | Any] | None = None
|
|||
|
|
"""针对此特定任务动态追加或覆盖的工具列表"""
|
|||
|
|
|
|||
|
|
guardrails: list[Any] | None = None
|
|||
|
|
"""护栏验证列表。支持传入函数、BaseGuardrail 实例，
|
|||
|
|
或直接传入自然语言字符串规则（自动转为 LLM 裁判）"""
|
|||
|
|
|
|||
|
|
_parsed_guardrails: list[Any] = PrivateAttr(default_factory=list)
|
|||
|
|
|
|||
|
|
model_config = ConfigDict(arbitrary_types_allowed=True)
|
|||
|
|
|
|||
|
|
@model_validator(mode="after")
|
|||
|
|
def _parse_and_set_guardrails(self) -> "Task":
|
|||
|
|
from zhenxun.services.ai.guardrails import parse_guardrails
|
|||
|
|
|
|||
|
|
self._parsed_guardrails = parse_guardrails(self.guardrails)
|
|||
|
|
return self
|
|||
|
|
|
|||
|
|
|
|||
|
|
__all__ = [
|
|||
|
|
"AgentRunResult",
|
|||
|
|
"OutputDataT",
|
|||
|
|
"StreamedRunResult",
|
|||
|
|
"Task",
|
|||
|
|
"TaskResult",
|
|||
|
|
]
|