> ## Documentation Index > Fetch the complete documentation index at: https://simplellmfunc.cn/llms.txt > Use this file to discover all available pages before exploring further. # 事件 > 全部 14 种事件类型、ReactOutput 和流式工具的 API 参考 # 事件 API 参考 ## ReactOutput ```python theme={null} from SimpleLLMFunc.hooks import ReactOutput, ResponseYield, EventYield ``` ```python theme={null} ReactOutput = ResponseYield | EventYield ``` ### ResponseYield ```python theme={null} @dataclass class ResponseYield: response: Any # str, Pydantic model, or raw dict messages: NormalizedMessageList # Updated conversation history ``` ### EventYield ```python theme={null} @dataclass class EventYield: event: ReActEvent # One of 14+ event types origin: EventOrigin # Source identification ``` ### EventOrigin ```python theme={null} @dataclass class EventOrigin: session_id: str agent_call_id: str event_seq: int parent_agent_call_id: str | None = None fork_id: str | None = None fork_depth: int = 0 fork_seq: int | None = None selfref_instance_id: str | None = None source_memory_key: str | None = None memory_key: str | None = None tool_name: str | None = None tool_call_id: str | None = None ``` *** ## 类型守卫 ```python theme={null} from SimpleLLMFunc.hooks import is_response_yield, is_event_yield is_response_yield(output: ReactOutput) -> bool is_event_yield(output: ReactOutput) -> bool ``` *** ## 流过滤器 ```python theme={null} from SimpleLLMFunc.hooks import responses_only, events_only, filter_events # Only ResponseYield items async for resp in responses_only(agent_stream): print(resp.response) # Only EventYield items async for evt in events_only(agent_stream): handle(evt.event) # Only specific event types async for evt in filter_events(agent_stream, LLMChunkArriveEvent): print(evt.event.accumulated_content) ``` *** ## 事件类型 ### 循环生命周期事件 #### ReactStartEvent ```python theme={null} @dataclass class ReactStartEvent: event_type: ReActEventType = ReActEventType.REACT_START ``` 在 ReAct 循环开始时发射一次。 #### ReactIterationStartEvent ```python theme={null} @dataclass class ReactIterationStartEvent: iteration: int event_type: ReActEventType = ReActEventType.REACT_ITERATION_START ``` #### ReactIterationEndEvent ```python theme={null} @dataclass class ReactIterationEndEvent: iteration: int event_type: ReActEventType = ReActEventType.REACT_ITERATION_END ``` #### ReactEndEvent ```python theme={null} @dataclass class ReactEndEvent: final_messages: NormalizedMessageList response: Any event_type: ReActEventType = ReActEventType.REACT_END ``` 终止事件。包含最终对话状态和响应。 *** ### LLM 调用事件 #### LLMCallStartEvent ```python theme={null} @dataclass class LLMCallStartEvent: messages: NormalizedMessageList # What the LLM will see event_type: ReActEventType = ReActEventType.LLM_CALL_START ``` #### LLMChunkArriveEvent ```python theme={null} @dataclass class LLMChunkArriveEvent: chunk: LLMStreamChunk # Provider chunk object accumulated_content: str # Content accumulated so far chunk_index: int event_type: ReActEventType = ReActEventType.LLM_CHUNK_ARRIVE ``` 每个流式文本块到达时发射。仅在 `stream=True` 时触发。 #### LLMCallEndEvent ```python theme={null} @dataclass class LLMCallEndEvent: response: Any messages: NormalizedMessageList tool_calls: list[Any] execution_time: float content: str = "" usage: Optional[Dict[str, int]] = None event_type: ReActEventType = ReActEventType.LLM_CALL_END ``` #### LLMCallErrorEvent ```python theme={null} @dataclass class LLMCallErrorEvent: error: Exception event_type: ReActEventType = ReActEventType.LLM_CALL_ERROR ``` *** ### 工具执行事件 #### ToolCallsBatchStartEvent ```python theme={null} @dataclass class ToolCallsBatchStartEvent: tool_calls: List[Dict[str, Any]] # All calls in this batch event_type: ReActEventType = ReActEventType.TOOL_CALLS_BATCH_START ``` #### ToolCallStartEvent ```python theme={null} @dataclass class ToolCallStartEvent: tool_name: str tool_call_id: str arguments: Dict[str, Any] event_type: ReActEventType = ReActEventType.TOOL_CALL_START ``` #### ToolCallArgumentsDeltaEvent ```python theme={null} @dataclass class ToolCallArgumentsDeltaEvent: tool_name: str tool_call_id: str argname: str argcontent_delta: str # Streaming argument fragment event_type: ReActEventType = ReActEventType.TOOL_CALL_ARGUMENTS_DELTA ``` #### ToolCallEndEvent ```python theme={null} @dataclass class ToolCallEndEvent: tool_name: str tool_call_id: str arguments: Dict[str, Any] result: Any execution_time: float success: bool event_type: ReActEventType = ReActEventType.TOOL_CALL_END ``` #### ToolCallErrorEvent ```python theme={null} @dataclass class ToolCallErrorEvent: tool_name: str tool_call_id: str error: str event_type: ReActEventType = ReActEventType.TOOL_CALL_ERROR ``` #### ToolCallsBatchEndEvent ```python theme={null} @dataclass class ToolCallsBatchEndEvent: event_type: ReActEventType = ReActEventType.TOOL_CALLS_BATCH_END ``` *** ### 自定义事件 #### CustomEvent ```python theme={null} @dataclass class CustomEvent: event_name: str # e.g., "kernel_stdout", "selfref_fork_spawn" data: Dict[str, Any] # Event payload tool_call_id: Optional[str] # Which tool emitted this event_type: ReActEventType = ReActEventType.CUSTOM ``` 由工具通过 `ToolEventEmitter` 发射。常见事件名称： | 事件名称 | 来源 | 数据 | | ----------------------- | ------- | ------------------------------------- | | `kernel_stdout` | PyRepl | `{"text": "..."}` | | `kernel_stderr` | PyRepl | `{"text": "..."}` | | `selfref_fork_spawn` | SelfRef | `{"fork_id": "..."}` | | `selfref_fork_complete` | SelfRef | `{"fork_id": "...", "status": "..."}` | *** ## 事件发射器 ### ToolEventEmitter ```python theme={null} from SimpleLLMFunc.hooks import ToolEventEmitter emitter = ToolEventEmitter() # Inside a tool implementation: await emitter.emit(CustomEvent( event_name="progress", data={"percent": 50}, tool_call_id=current_tool_call_id, )) ``` ### NoOpEventEmitter ```python theme={null} from SimpleLLMFunc.hooks import NoOpEventEmitter ``` 静默发射器，用于测试或不需要事件的场景。 *** ## 事件观察器 ```python theme={null} from SimpleLLMFunc.hooks import with_event_observer @with_event_observer(my_observer_fn) @llm_chat(...) async def agent(...): ... ``` 观察器函数签名： ```python theme={null} def my_observer(event: ReActEvent, origin: EventOrigin) -> None: ... ``` *** ## AbortSignal ```python theme={null} from SimpleLLMFunc.hooks import AbortSignal, ABORT_SIGNAL_PARAM signal = AbortSignal() signal.abort("reason") # Trigger abort signal.is_aborted # bool signal.reason # str | None ``` `ABORT_SIGNAL_PARAM = "_abort_signal"` — 用于传递中止信号的参数名。