cayu.sessions.outcomes

Public Cayu API. Definitions are grouped by their public source module, and definitions from private implementation modules appear on their package’s page; adding a symbol does not move existing links. The import shown at each entry is a supported public namespace. Read the Python API overview and install the required extra.

run_to_completion

from cayu.sessions import run_to_completion

Run an agent to a terminal state and return a RunOutcome.

Consumes app.run(request), or app.resume(request) for a ResumeRequest, and returns the final text, terminal status, and error (if any), so you branch on outcome.ok / outcome.status instead of hand-inspecting events. To continue a conversation, pass ResumeRequest(session_id=outcome.session_id, messages=[...]); a new RunRequest always starts an empty session. A model/tool failure surfaces as status == SessionStatus.FAILED with error set. Setup-time exceptions before a terminal session event are also converted into a failed outcome.

async run_to_completion(app: CayuApp, request: RunRequest | ResumeRequest) -> RunOutcome

Release source · Runtime guarantees · Capability guides

RunOutcome

from cayu.sessions import RunOutcome

The terminal result of an agent run.

• status is SessionStatus.COMPLETED, SessionStatus.FAILED, or SessionStatus.INTERRUPTED.
• final_text is the last completed model turn’s text output ("" if the latest model turn completed without text or failed before completion).
• error is the failure message when status is SessionStatus.FAILED, else None.
• events is the full event stream, if you need more than the summary.
• structured_output is the last successfully validated structured value, including valid JSON null, or None when the run had no validated output.
• tool_completion is the successful final tool’s durable host-rendering basis, or None for ordinary model completion. It does not synthesize final_text.
• interaction_id identifies the interaction that produced final_text or the final interaction-scoped terminal outcome.

Decorators: @dataclass(frozen=True).

Fields and attributes

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name	Type	Default
session_id	str	required
status	SessionStatus	required
final_text	str	required
error	str | None	required
events	tuple[Event, ...]	required
structured_output	StructuredOutputResult | None	None
interaction_id	str | None	None
tool_completion	ToolCompletionResult | None	None

ok (property)

RunOutcome.ok() -> bool

True only if the run reached session.completed.

Release source · Runtime guarantees · Capability guides

StructuredOutputResult

from cayu.sessions import StructuredOutputResult

The last successfully validated structured output from a completed run.

The wrapper distinguishes a valid JSON null value (output is None) from a run that did not validate structured output at all (RunOutcome.structured_output is None).

Decorators: @dataclass(frozen=True).

Fields and attributes

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name	Type	Default
output	Any	required
name	str | None	required
attempt	int	required
max_retries	int	required

Release source · Runtime guarantees · Capability guides