AgentClient#

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

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

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.

Examples

Usage:

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

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.

Parameters:

  • 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.

Yields:

Original AgentEvent objects after the bound callback completes.

Return type:

AsyncIterator[AgentEvent]

Note

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)[source]#

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.

Parameters:

  • 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.

Returns:

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

Return type:

CompactionEvent | None

Examples

Usage:

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

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

Parameters:

  • 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.

Returns:

The final AssistantMessage after the stream closes successfully.

Raises:

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

Return type:

AssistantMessage

async resume_point(*, config=None, model=None)[source]#

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.

Parameters:
Return type:

ResumePoint | None

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

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.

Parameters:
Return type:

AsyncIterator[AgentEvent]

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

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.

Parameters:
Return type:

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.

Examples

Use a model or tool from a plain function:

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

runtime (SyncRuntime | None)

Return type:

SyncObject[Self]