Agents in a Space
Start, follow, message and stop coding-agent runs inside a Space.
An agent run is a coding-agent CLI started in the Space with a prompt, detached from the call that started it.
Agent runs#
Methods of Space.
Space.agent_start#
Starts an agent CLI (claude-code, openai-codex, ...) with a
prompt, as a detached spacesd process.
async def agent_start(self, agent: str, prompt: str, show: Optional[bool], options: Optional[SpaceAgentOptions]) -> AgentStartReport| Parameter | Type | Default |
|---|---|---|
agent | String | required |
prompt | String | required |
show | Option<bool> | required |
options | Option<SpaceAgentOptions> | required |
Returns AgentStartReport · Async · Raises CuaError
Space.agent_status#
A run's status with the last tail lines of output.
async def agent_status(self, run_id: str, tail: Optional[int]) -> AgentRunStatus| Parameter | Type | Default |
|---|---|---|
run_id | String | required |
tail | Option<u32> | required |
Returns AgentRunStatus · Async · Raises CuaError
Space.agent_events#
Normalized events after cursor (0: the start), as the
agent_events JSON (events, cursor, caught_up, status).
async def agent_events(self, run_id: str, cursor: Optional[int], max: Optional[int]) -> str| Parameter | Type | Default |
|---|---|---|
run_id | String | required |
cursor | Option<u64> | required |
max | Option<u32> | required |
Returns String · Async · Raises CuaError
Space.agent_message#
Sends a follow-up message to a run.
async def agent_message(self, run_id: str, text: str, force: Optional[bool]) -> AgentActionReport| Parameter | Type | Default |
|---|---|---|
run_id | String | required |
text | String | required |
force | Option<bool> | required |
Returns AgentActionReport · Async · Raises CuaError
Space.agent_interrupt#
Cancels the run's turn in flight; the session stays open.
async def agent_interrupt(self, run_id: str) -> AgentActionReport| Parameter | Type | Default |
|---|---|---|
run_id | String | required |
Returns AgentActionReport · Async · Raises CuaError
Space.agent_list#
Every agent run in this Space.
async def agent_list(self) -> List[AgentRunStatus]Returns Vec<AgentRunStatus> · Async · Raises CuaError
Space.agent_stop#
Stops a run.
async def agent_stop(self, run_id: str) -> AgentActionReport| Parameter | Type | Default |
|---|---|---|
run_id | String | required |
Returns AgentActionReport · Async · Raises CuaError
Harnesses#
Methods of Spaces.
Spaces.agent_capabilities#
What every agent harness is and cannot do (agent_capabilities),
as JSON.
async def agent_capabilities(self) -> strReturns String · Async · Raises CuaError
AgentStartReport record#
Result of Space.agent_start.
Returned by Space.agent_start.
| Field | Type | Default | Description |
|---|---|---|---|
run_id / runId | String | Run id. | |
agent | String | Agent. | |
space | String | Space. | |
process_tag / processTag | String | spacesd process tag of the first turn. | |
notes | Vec<String> | Preparation steps that could not be completed. | |
json | String | The whole report as JSON. |
AgentRunStatus record#
One agent run's status.
Returned by Space.agent_list, Space.agent_status.
| Field | Type | Default | Description |
|---|---|---|---|
run_id / runId | String | Run id. | |
agent | Option<String> | Agent. | |
status | String | Status (running, done, failed, ...). | |
reason | String | Why. | |
phase | String | Finer grain: installing, working, waiting, exited, ... | |
result_text / resultText | Option<String> | The last turn's final text (agent_status only). | |
accepts_message / acceptsMessage | bool | A follow-up sent now starts the next turn (the server's rule: idle, or a crashed or failed run it restarts; not mid-turn). Read this, never derive it from status. | |
output_tail / outputTail | Option<String> | Output tail. | |
json | String | The whole status as JSON. |
AgentActionReport record#
Result of Space.agent_message / Space.agent_stop.
Returned by Space.agent_interrupt, Space.agent_message, Space.agent_stop.
| Field | Type | Default | Description |
|---|---|---|---|
run_id / runId | String | Run id. | |
ok | bool | Delivered (message) or stopped (stop). | |
reason | String | Why. | |
json | String | The whole report as JSON. |
SpaceAgentOptions record#
Options for Space.agent_start beyond the harness and prompt.
| Field | Type | Default | Description |
|---|---|---|---|
env_from_host / envFromHost | Vec<String> | [] | Provider key variables forwarded from the Spaces host's environment. |
env | HashMap<String, String> | [:] | More environment for the agent, for example HERMES_HOME (stored 0600 in the run, redacted from its output; not for provider keys). |
repo | Option<String> | None | |
branch | Option<String> | None | |
cwd | Option<String> | None | |
model | Option<String> | None | |
base_url / baseUrl | Option<String> | None | A custom model endpoint. |
exit_when_idle / exitWhenIdle | Option<bool> | None | Stop (resumably) once the prompt is answered. |
home | Option<String> | None | Run as this persistent agent: its home in the Cua Volume is restored first and saved after every turn (see Spaces.persistent_agent_send). |