跳转至

事件与 Hooks

事件描述一次运行的进度，Hook 接收事件，AsyncEventStream 支持边运行边消费。事件记录默认在内存中，持久日志由应用实现。

流式输出 · Hooks 指南 · 接入聊天界面

常用接口

接口 用途
AgentEvent 包含 kind、run_id、payload、timestamp，以及可选 iteration 和 session_id。
AsyncEventStream 单次消费的异步事件流。
EventRecorder 在内存中记录事件，并按 kind 查询。

事件与流

包含 kind、run_id、payload、timestamp，以及可选 iteration 和 session_id。

AgentEvent dataclass

One structured lifecycle event emitted by an agent run.

单次消费的异步事件流。消费结束后调用 result()；提前关闭使用 aclose()。

AsyncEventStream dataclass

Bases: Generic[ResultT]

Async iterator over events produced by one background agent run.

result async 

result() -> ResultT

Return the completed background run result.

监听与记录

监听事件的协议，实现 on_event()。

AgentHook

Bases: Protocol

Consumer of agent lifecycle events.

on_event async 

on_event(event: AgentEvent) -> None

Handle one lifecycle event.

把事件回调包装为 Hook。

CallbackHook

Adapt a sync or async callable into an AgentHook.

在内存中记录事件，并按 kind 查询。

EventRecorder dataclass

Small hook useful for tests, diagnostics, and examples.

事件回调函数类型。

EventCallback module-attribute 

EventCallback = Callable[[AgentEvent], Awaitable[None] | None]

运行入口接受的 Hook 输入类型。

HookInput module-attribute 

HookInput = AgentHook | EventCallback | Iterable[AgentHook | EventCallback] | None

事件常量

按 kind 区分事件；不要假设不同事件的 payload 结构一致。工具开始、审批与结束通过调用 ID 关联。

DEFAULT_STREAM_QUEUE_SIZE module-attribute 

DEFAULT_STREAM_QUEUE_SIZE = 256

FINAL_RESULT module-attribute 

FINAL_RESULT = 'final_result'

ITERATION_FINISHED module-attribute 

ITERATION_FINISHED = 'iteration.finished'

ITERATION_STARTED module-attribute 

ITERATION_STARTED = 'iteration.started'

MODEL_REQUEST_STARTED module-attribute 

MODEL_REQUEST_STARTED = 'model.request.started'

MODEL_RESPONSE_FINISHED module-attribute 

MODEL_RESPONSE_FINISHED = 'model.response.finished'

MODEL_STREAM_CONTENT_DELTA module-attribute 

MODEL_STREAM_CONTENT_DELTA = 'model.stream.content_delta'

MODEL_STREAM_REFUSAL_DELTA module-attribute 

MODEL_STREAM_REFUSAL_DELTA = 'model.stream.refusal_delta'

MODEL_STREAM_REASONING_DELTA module-attribute 

MODEL_STREAM_REASONING_DELTA = 'model.stream.reasoning_delta'

MODEL_STREAM_RECOVERED module-attribute 

MODEL_STREAM_RECOVERED = 'model.stream.recovered'

MODEL_STREAM_TOOL_CALL_DELTA module-attribute 

MODEL_STREAM_TOOL_CALL_DELTA = 'model.stream.tool_call_delta'

RUN_ERROR module-attribute 

RUN_ERROR = 'run.error'

RUN_FINISHED module-attribute 

RUN_FINISHED = 'run.finished'

RUN_STARTED module-attribute 

RUN_STARTED = 'run.started'

TOOL_APPROVAL_FINISHED module-attribute 

TOOL_APPROVAL_FINISHED = 'tool.approval.finished'

TOOL_APPROVAL_STARTED module-attribute 

TOOL_APPROVAL_STARTED = 'tool.approval.started'

TOOL_CALL_FINISHED module-attribute 

TOOL_CALL_FINISHED = 'tool.call.finished'

TOOL_CALL_STARTED module-attribute 

TOOL_CALL_STARTED = 'tool.call.started'

TOOL_CALLS_FINISHED module-attribute 

TOOL_CALLS_FINISHED = 'tool.calls.finished'

TOOL_CALLS_STARTED module-attribute 

TOOL_CALLS_STARTED = 'tool.calls.started'

TURN_CONTEXT_BUILT module-attribute 

TURN_CONTEXT_BUILT = 'turn.context_built'

TURN_ERROR module-attribute 

TURN_ERROR = 'turn.error'

TURN_FINISHED module-attribute 

TURN_FINISHED = 'turn.finished'

TURN_STARTED module-attribute 

TURN_STARTED = 'turn.started'