Persistent agents

Named agents whose memory outlives their Space: homes in the Cua Volume, routines, notifications, pause and resume, access to your computers.

A persistent agent keeps its harness memory in its home in the Cua Volume (agents/<name>/). The daemon restores the home before each run, saves it after each turn, fires routines with or without an app open, and posts notifications. See Persistent agents.

Persistent agents#

Methods of Spaces.

`Spaces.persistent_agent_create`#

Creates a persistent agent: harness working in space, its home at agents/<name>/ in the Cua Volume.

async def persistent_agent_create(self, name: str, harness: str, space: str, options: Optional[PersistentAgentOptions]) -> PersistentAgentInfo

Parameter	Type	Default
`name`	`String`	required
`harness`	`String`	required
`space`	`String`	required
`options`	`Option<PersistentAgentOptions>`	required

Returns PersistentAgentInfo · Async · Raises CuaError

`Spaces.persistent_agents`#

Every persistent agent.

async def persistent_agents(self) -> List[PersistentAgentInfo]

Returns Vec<PersistentAgentInfo> · Async · Raises CuaError

`Spaces.persistent_agent_remove`#

Forgets a persistent agent (its home stays in the drive).

async def persistent_agent_remove(self, name: str) -> PersistentAgentInfo

Parameter	Type	Default
`name`	`String`	required

Returns PersistentAgentInfo · Async · Raises CuaError

`Spaces.persistent_agent_send`#

Gives a persistent agent a turn: a follow-up to its idle run, or a new run with its home restored.

async def persistent_agent_send(self, name: str, text: str) -> AgentDelivery

Parameter	Type	Default
`name`	`String`	required
`text`	`String`	required

Returns AgentDelivery · Async · Raises CuaError

`Spaces.persistent_agent_save`#

Saves a persistent agent's home into the drive now.

async def persistent_agent_save(self, name: str) -> HomeTransfer

Parameter	Type	Default
`name`	`String`	required

Returns HomeTransfer · Async · Raises CuaError

`Spaces.agent_pause`#

Pauses a persistent agent: run, routines and (local) Space.

async def agent_pause(self, name: str) -> AgentPauseReport

Parameter	Type	Default
`name`	`String`	required

Returns AgentPauseReport · Async · Raises CuaError

`Spaces.agent_resume`#

Resumes a paused persistent agent; with prompt, starts a run.

async def agent_resume(self, name: str, prompt: Optional[str]) -> AgentResumeReport

Parameter	Type	Default
`name`	`String`	required
`prompt`	`Option<String>`	required

Returns AgentResumeReport · Async · Raises CuaError

Routines#

Methods of Spaces.

`Spaces.routine_add`#

Adds a routine. Give exactly one of every_minutes, daily_at (HH:MM) or weekly_on (mon 09:00).

async def routine_add(self, agent: str, title: str, prompt: str, every_minutes: Optional[int], daily_at: Optional[str], weekly_on: Optional[str]) -> RoutineInfo

Parameter	Type	Default
`agent`	`String`	required
`title`	`String`	required
`prompt`	`String`	required
`every_minutes`	`Option<i64>`	required
`daily_at`	`Option<String>`	required
`weekly_on`	`Option<String>`	required

Returns RoutineInfo · Async · Raises CuaError

`Spaces.routines`#

Routines (of one agent, or all).

async def routines(self, agent: Optional[str]) -> List[RoutineInfo]

Parameter	Type	Default
`agent`	`Option<String>`	required

Returns Vec<RoutineInfo> · Async · Raises CuaError

`Spaces.routine_remove`#

Deletes a routine.

async def routine_remove(self, id: str) -> None

Parameter	Type	Default
`id`	`String`	required

Async · Raises CuaError

`Spaces.routine_set_enabled`#

Turns a routine on or off.

async def routine_set_enabled(self, id: str, enabled: bool) -> RoutineInfo

Parameter	Type	Default
`id`	`String`	required
`enabled`	`bool`	required

Returns RoutineInfo · Async · Raises CuaError

Notifications#

Methods of Spaces.

`Spaces.notify_user`#

Posts a notification to the Cua app. Returns its id.

async def notify_user(self, title: str, body: Optional[str], agent: Optional[str]) -> str

Parameter	Type	Default
`title`	`String`	required
`body`	`Option<String>`	required
`agent`	`Option<String>`	required

Returns String · Async · Raises CuaError

`Spaces.notifications`#

The notifications feed, newest first.

async def notifications(self, unread_only: bool, since_ms: Optional[int]) -> List[NotificationInfo]

Parameter	Type	Default
`unread_only`	`bool`	required
`since_ms`	`Option<u64>`	required

Returns Vec<NotificationInfo> · Async · Raises CuaError

`Spaces.notifications_ack`#

Marks notifications read (every one when ids is empty).

async def notifications_ack(self, ids: List[str]) -> int

Parameter	Type	Default
`ids`	`Vec<String>`	required

Returns u64 · Async · Raises CuaError

Access to your computers#

Methods of Spaces.

`Spaces.computer_access_grant`#

Lets one persistent agent use one of the user's computers (asks for presence).

async def computer_access_grant(self, agent: str, machine: str, expires_in_secs: Optional[int]) -> ComputerGrant

Parameter	Type	Default
`agent`	`String`	required
`machine`	`String`	required
`expires_in_secs`	`Option<u64>`	required

Returns ComputerGrant · Async · Raises CuaError

`Spaces.computer_access_revoke`#

Takes a persistent agent's computer access back (every machine when machine is empty). Returns how many grants.

async def computer_access_revoke(self, agent: str, machine: Optional[str]) -> int

Parameter	Type	Default
`agent`	`String`	required
`machine`	`Option<String>`	required

Returns u64 · Async · Raises CuaError

`Spaces.computer_access`#

Per-agent computer grants (of one agent, or all).

async def computer_access(self, agent: Optional[str]) -> List[ComputerGrant]

Parameter	Type	Default
`agent`	`Option<String>`	required

Returns Vec<ComputerGrant> · Async · Raises CuaError

`PersistentAgentInfo` record#

A persistent agent: a named harness whose memory (its home in the Cua Drive) outlives its runs and its Space.

Returned by Spaces.persistent_agent_create, Spaces.persistent_agent_remove, Spaces.persistent_agents.

Field	Type	Description
`name`	`String`
`harness`	`String`	Harness id.
`space`	`String`	The Space it works in.
`model`	`Option<String>`
`base_url` / `baseUrl`	`Option<String>`
`env_from_host` / `envFromHost`	`Vec<String>`
`paused`	`bool`
`space_state` / `spaceState`	`String`	`running`, `suspended` (a paused local Space) or `released` (a paused cloud Space).
`run_id` / `runId`	`Option<String>`	The current run.
`saved_ms` / `savedMs`	`u64`	Unix ms of the last home save.
`created_ms` / `createdMs`	`u64`
`last_error` / `lastError`	`Option<String>`

`PersistentAgentOptions` record#

How to create a persistent agent.

Field	Type	Default	Description
`model`	`Option<String>`	`None`
`base_url` / `baseUrl`	`Option<String>`	`None`
`env_from_host` / `envFromHost`	`Vec<String>`	`[]`	Provider key variables forwarded from the host's environment at each start.
`env`	`HashMap<String, String>`	`[:]`	More environment for every run (not secrets).

`AgentDelivery` record#

What Spaces.persistent_agent_send did.

Returned by Spaces.persistent_agent_send.

Field	Type	Description
`run_id` / `runId`	`String`
`started`	`bool`	A new run started (with the home restored) rather than a follow-up.
`restored`	`Option<HomeTransfer>`

`HomeTransfer` record#

What moved between the drive and a Space.

Returned by Spaces.persistent_agent_save.

Field	Type	Description
`files`	`u64`
`bytes`	`u64`
`unchanged`	`u64`
`removed`	`u64`
`blocked`	`Vec<String>`	`path (kind)` of each file the secret scanner kept out.
`millis`	`u64`

`AgentPauseReport` record#

What Spaces.agent_pause did.

Returned by Spaces.agent_pause.

Field	Type	Default	Description
`stopped_run` / `stoppedRun`	`Option<String>`
`saved`	`Option<HomeTransfer>`
`space_state` / `spaceState`	`String`
`millis`	`u64`

`AgentResumeReport` record#

What Spaces.agent_resume did.

Returned by Spaces.agent_resume.

Field	Type	Description
`space`	`String`
`recreated`	`bool`
`restored`	`Option<HomeTransfer>`
`run_id` / `runId`	`Option<String>`
`ready_ms` / `readyMs`	`u64`	From the call to the home being back in a ready Space.

`RoutineInfo` record#

A routine: a recurring turn of a persistent agent, fired by the daemon.

Returned by Spaces.routine_add, Spaces.routine_set_enabled, Spaces.routines.

Field	Type	Description
`id`	`String`
`agent`	`String`
`title`	`String`
`prompt`	`String`
`label`	`String`	`Every day at 8:00 AM`.
`enabled`	`bool`
`next_fire` / `nextFire`	`Option<String>`	RFC 3339.
`last_fired_at` / `lastFiredAt`	`Option<String>`
`last_outcome` / `lastOutcome`	`Option<String>`
`last_run_id` / `lastRunId`	`Option<String>`

`NotificationInfo` record#

One entry of the notifications feed.

Returned by Spaces.notifications.

Field	Type	Description
`id`	`String`
`at_ms` / `atMs`	`u64`
`agent`	`Option<String>`
`kind`	`String`	`turn_ended`, `message`, `approval` or `error`.
`title`	`String`
`body`	`String`
`run_id` / `runId`	`Option<String>`
`space`	`Option<String>`
`read`	`bool`

`ComputerGrant` record#

A persistent agent's grant on one of the user's computers.

Returned by Spaces.computer_access, Spaces.computer_access_grant.

Field	Type	Default	Description
`id`	`String`
`agent`	`String`
`machine`	`String`
`created_ms` / `createdMs`	`u64`
`expires_ms` / `expiresMs`	`Option<u64>`
`revoked`	`bool`

Persistent agents