AgentEvent#

Distinguish UI streams, extension notifications, and external replies. See the guide.

class zett_agent.events.AgentEvent(type, session_id, phase=None, delta='', tool_call_delta=None, tool_calls=<factory>, server_tool_call=None, server_tool_input_delta=None, server_tool_result=None, response=None, stop=None, message=None, internal_message=None, steering_message=None, error=None, compaction=None, applied=None, name=None, payload=None)[源代码]#

One UI-facing event emitted by Agent.stream().

Optional fields are populated according to type. Consumers should first match the event type and only then read the corresponding payload.

event type                 relevant fields
-------------------------  -------------------------------------------
TEXT_DELTA                 delta
TOOL_STARTED               tool_calls
TOOL_COMPLETED/FAILED      tool_calls, message, optional error
SERVER_TOOL_STARTED        server_tool_call
SERVER_TOOL_INPUT_DELTA    server_tool_input_delta
SERVER_TOOL_COMPLETED      server_tool_result
SERVER_TOOL_FAILED         server_tool_result
MODEL_COMPLETED            response
MODEL_STOPPED              stop, response, message
RUN_COMPLETED              message
CUSTOM                     name, payload

示例

Handle a mixed stream with structural pattern matching:

async for event in agent.stream("Inspect this project"):
    match event.type:
        case AgentEventType.TEXT_DELTA:
            print(event.delta, end="", flush=True)
        case AgentEventType.TOOL_STARTED:
            print("tool:", event.tool_calls[0].name)
        case AgentEventType.CUSTOM:
            print(event.name, event.payload)

备注

Model failures and cancellation propagate as exceptions. They are not converted into a synthetic terminal AgentEvent.

参见

AgentEventDispatcher provides typed application callbacks, and 三类事件 compares all event channels.

参数:
session_id: str#

Session that owns the run emitting this event.

phase: AgentPhase | None#

Exclusive request phase when this event was emitted.

delta: str#

Incremental text or reasoning.

tool_call_delta: ToolCallDelta | None#

Incomplete tool arguments for display, never for execution.

tool_calls: list[ToolCall]#

Complete invocations associated with a tool event. Current execution emits one item per event; the list shape also supports future concurrent batches.

server_tool_call: ServerToolCall | None#

Provider-hosted invocation. It is observable but never locally executed.

server_tool_input_delta: ServerToolInputDelta | None#

Provider-hosted incremental input, correlated by call ID.

server_tool_result: ServerToolResult | None#

Provider-hosted terminal output or structured failure.

response: ModelResponse | None#

Final model response, including usage.

stop: StopInfo | None#

Why the model stopped, populated only by MODEL_STOPPED.

message: AssistantMessage | ToolMessage | None#

Tool result or final assistant answer.

internal_message: AgentMessage | None#

Internal instruction associated with INTERNAL_MESSAGE_STARTED/COMPLETED.

steering_message: UserMessage | None#

User input associated with STEERING_STARTED/COMPLETED/INTERRUPTED.

error: Exception | None#

Tool failure; skipped calls have success=False but no execution exception. Model and cancellation exceptions propagate to the caller.

compaction: CompactionEvent | None#

Applied compaction details, populated only by COMPACTION_COMPLETED.

applied: bool | None#

Whether a completed compaction replaced context; null for other events.

name: str | None#

Stable event name used by consumers to match one kind of CUSTOM event. This field is required and must be non-empty when type is CUSTOM.

payload: dict[str, Any] | None#

Extension-owned data for CUSTOM events. Extensions targeting JSON/SSE clients must supply JSON-serializable keys and values.