cayu.tools.user_input

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.

UserInputTool

from cayu.tools import UserInputTool

Built-in tool that pauses the session to ask the user a question.

Opt-in: register it explicitly on the agents that should be able to ask. When the model calls it, the runtime intercepts the call before execution, checkpoints the question, emits session.awaiting_user_input, and interrupts the session; the caller resumes with CayuApp.resolve_user_input(...) and the answer becomes this tool’s result. Because the runtime handles the pause, run is never invoked on the normal path; it returns an error only if the tool is somehow executed directly.

Bases: Tool.

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
pauses_session	class attribute	True

init (method)

UserInputTool.__init__(spec: ToolSpec | None=None) -> None

name (property)

UserInputTool.name() -> str

execution_profile_identity (property)

UserInputTool.execution_profile_identity() -> ExecutionProfileBehaviorIdentity | None

Return the stable behavior declaration frozen with this tool’s spec.

retain_arguments_for_model (property)

UserInputTool.retain_arguments_for_model() -> bool

Retain bounded redacted original inputs privately for the same profile.

Independent of audit publication; oversized and compacted-away inputs may be omitted. This does not grant knowledge read or activation rights.

description (property)

UserInputTool.description() -> str

schema (property)

UserInputTool.schema() -> dict[str, Any]

run (method)

async UserInputTool.run(ctx: ToolContext, args: dict[str, Any]) -> ToolResult

Release source · Runtime guarantees · Capability guides