AgentClient#

Start here to create, run, and stream an application client. See the guide.

class zett_agent.client.AgentClient(agent, *, event_dispatcher=None)[源代码]#

Compose an initialized Agent with optional application event callbacks.

The public agent attribute exposes the original runtime for advanced APIs, including emit_external_event(). Calling it directly bypasses this client's callbacks. No methods or attributes are injected into the original Agent.

Callback failures propagate to the caller and close the underlying stream: unfinished requests are cancelled through the Agent's normal close path. If a callback fails after completion, the request remains completed. Shared handlers must distinguish sessions using event.session_id.

示例

Usage:

agent = await Agent.create(model, config=AgentRunConfig(session_id="existing"))
client = AgentClient(agent, event_dispatcher=ConsoleEvents())
reply = await client.run("Continue")
参数:
async stream(message, *, config=None, model=None, reasoning_effort=None, parallel_tool_call=None, metadata=None, tags=None)[源代码]#

Dispatch then yield each original event, in order, exactly once.

Use aclosing(client.stream(...)) when stopping consumption early. Do not dispatch yielded events manually if a handler is already bound.

参数:

  • message (UserMessage | str) -- User text or an explicit multimodal UserMessage.

  • config (AgentRunConfig | None) -- Optional per-request session and request identity.

  • model (AgentModel | None) -- Request-specific model; omitted to use the Agent default.

  • reasoning_effort (ReasoningEffort | None) -- Per-request override of the model reasoning level.

  • parallel_tool_call (bool | None) -- Per-request override of parallel tool calling.

  • metadata (Mapping[str, JsonValue] | None) -- Request-scoped JSON data supplied to extensions.

  • tags (Mapping[str, JsonValue] | None) -- Request-scoped classifications supplied to extensions.

生成器:

Original AgentEvent objects after the bound callback completes.

返回类型:

AsyncIterator[AgentEvent]

备注

Closing early cancels unfinished work. Provider, callback, and cancellation exceptions are not converted into synthetic events.

async compact(*, config=None, model=None, metadata=None, tags=None)[源代码]#

Compact the session's history now, dispatching every event it emits.

This is the one-call form of Agent.compact(): the pass runs to completion, each event reaches the bound dispatcher in order — so a UI shows the same progress a streamed run shows — and nothing is appended to the conversation or sent to the primary model.

参数:

  • config (AgentRunConfig | None) -- Session identity; defaults to the initialized configuration.

  • model (AgentModel | None) -- Model an extension compacts with when it has none of its own.

  • metadata (Mapping[str, JsonValue] | None) -- Request data visible to extensions and persistence.

  • tags (Mapping[str, JsonValue] | None) -- Request classifications visible to extensions and persistence.

返回:

The checkpoint the pass stored, or None when the extensions found nothing worth replacing.

返回类型:

CompactionEvent | None

示例

Usage:

stored = await client.compact()
async run(message, *, config=None, model=None, reasoning_effort=None, parallel_tool_call=None, metadata=None, tags=None)[源代码]#

Collect a complete stream with callbacks and return its final answer.

参数:

  • message (UserMessage | str) -- User text or an explicit multimodal UserMessage.

  • config (AgentRunConfig | None) -- Per-request identity; omitted to reuse the initialized session.

  • model (AgentModel | None) -- Request-specific model; omitted to use the Agent default.

  • reasoning_effort (ReasoningEffort | None) -- Override the runtime default for this request only.

  • parallel_tool_call (bool | None) -- Override parallel tool calling for this request.

  • metadata (Mapping[str, JsonValue] | None) -- JSON-compatible application data for persistence/extensions.

  • tags (Mapping[str, JsonValue] | None) -- JSON-compatible classifications for persistence/extensions.

返回:

The final AssistantMessage after the stream closes successfully.

抛出:

AgentProtocolError -- If no final answer is emitted or the runtime is not initialized. Model and callback failures propagate unchanged.

返回类型:

AssistantMessage

async resume_point(*, config=None, model=None)[源代码]#

Report where the session was interrupted, or None when there is nothing to resume.

See Agent.resume_point(). Nothing is written, no model is called, and no event reaches the bound dispatcher.

参数:
返回类型:

ResumePoint | None

async stream_resume(*, config=None, model=None, reasoning_effort=None, parallel_tool_call=None, metadata=None, tags=None)[源代码]#

Dispatch then yield each event of Agent.stream_resume(), in order, exactly once.

Use aclosing(client.stream_resume(...)) when stopping consumption early. A session with nothing to resume raises AgentResumeError.

参数:
返回类型:

AsyncIterator[AgentEvent]

async resume(*, config=None, model=None, reasoning_effort=None, parallel_tool_call=None, metadata=None, tags=None)[源代码]#

Pick an interrupted session up where it stopped, with callbacks, and return the answer.

See Agent.resume() for what is done in each case and what it raises.

参数:
返回类型:

AssistantMessage

sync(*, runtime=None)#

Return a context-managed synchronous view; optionally share a runtime.

Omitting runtime creates a new background thread for this view. Passing an existing runtime reuses its loop and leaves its shutdown to the caller. This API is for service entry points, not Extension lifecycle hooks.

示例

Use a model or tool from a plain function:

with read_file.sync() as read:
    result = read({"path": "README.md"})
参数:

runtime (SyncRuntime | None)

返回类型:

SyncObject[Self]