cayu.agents

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.

Agent

from cayu.agents import Agent

Base contract for agents.

Concrete implementations will turn messages into an event stream, using providers, tools, memory, and runtime services.

Bases: ABC.

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
spec	AgentSpec	required
tools	list[Tool]	required

run (method)

Agent.run(messages: list[Message]) -> AsyncIterator[Event]

Run the agent and return a stream of structured events.

Declared non-async on purpose: implementations are expected to be async generators (async def run(...): yield ...), which are plain callables returning an AsyncIterator. Keeping the abstract method non-async gives every implementation the same calling convention — async for event in agent.run(messages) — instead of some callers needing await agent.run(...) first.

Release source · Runtime guarantees · Capability guides

AgentAuthoringState

from cayu.agents import AgentAuthoringState

Explicit application-authoring state carried by an agent specification.

Bases: StrEnum.

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
UNFINISHED_GENERATED_TRACER_BULLET	class attribute	'unfinished_generated_tracer_bullet'

Release source · Runtime guarantees · Capability guides

AgentSpec

from cayu.agents import AgentSpec

Bases: BaseModel.

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
name	str	required
model	str	required
provider_name	str | None	None
system_prompt	str | None	None
workflow_tool_names	tuple[str, ...]	()
authoring_state	AgentAuthoringState | None	None
metadata	dict[str, Any]	Field(default_factory=dict)
provider_options	dict[str, Any]	Field(default_factory=dict)
thinking	ThinkingConfig | None	None

copy_json_mapping (method)

AgentSpec.copy_json_mapping(value: dict[str, Any], info) -> dict[str, Any]

validate_nonblank_fields (method)

AgentSpec.validate_nonblank_fields(value: str, info) -> str

validate_optional_provider_name (method)

AgentSpec.validate_optional_provider_name(value: str | None, info) -> str | None

validate_optional_system_prompt (method)

AgentSpec.validate_optional_system_prompt(value: str | None, info) -> str | None

validate_workflow_tool_names (method)

AgentSpec.validate_workflow_tool_names(value: tuple[str, ...]) -> tuple[str, ...]

Release source · Runtime guarantees · Capability guides