Create Workspace worker
create_workspace_workerStart a worker agent to run one independent task in a Plori Workspace on its own file copy, enabling parallel tasks without conflicts.
Instructions
Use this when the user wants several independent tasks run at the same time, such as building or testing separate parts of a project or researching several topics in parallel. Do not use for a single task (send that with send_workspace_message) or for work you can finish in a few of your own tool calls. Start a worker: an agent that runs one task in a Workspace on its own copy of the Workspace files, so several workers can run at the same time without changing each other's files or the Workspace's current files. The call makes a copy of the Workspace's current revision for the worker, creates a task group unless task_group_id names an existing one, and queues the worker. It returns at once with worker_request_id, agent_id, working_copy_id and task_group_id; the worker starts when capacity allows. get_workspace_worker reports its run_id once it starts, save_state ready with saved_revision_id once its files are saved, and changeset_id and change_status. When the run completes normally and changes files, Plori submits the changes and accepts a clean comparison, so they become the Workspace's current files; otherwise submit_workspace_changeset submits the saved files. A worker started through this connector pauses before each action outside its own environment (connected-account and MCP writes, outbound HTTP writes, git push, publishing, deploys, email) until the account owner approves that one action at approve_url in the Plori web app; the calling model cannot approve. Unless executor_agent_id is given, the call creates a new agent for the worker; worker agents do not count against the account's agent limit. Runs are charged to the account's prepaid US-dollar balance. idempotency_key identifies the request for 24 hours: the same key with the same arguments returns the same worker; if the Workspace's current revision changed between two calls with the same key, the second call can be refused with 422 idempotency_key_reused, and a new key starts a new worker.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | A display name for the new agent created for this worker. Not accepted with executor_agent_id. Omitted, the agent gets a numbered name such as Worker 1. | |
| task | Yes | The task for the worker, in plain text (at most 65536 bytes). | |
| workspace_id | Yes | The Workspace UUID. | |
| task_group_id | No | An existing task group of this Workspace (task_group_id from an earlier worker), so that the workers' costs and stop request are grouped. Omitted, a new task group is created for this worker. | |
| idempotency_key | Yes | A string of 1-255 bytes you generate for this worker. Use a new key for each worker, also for two workers with the same task. | |
| max_turn_tokens | No | Optional cumulative cache-weighted token ceiling for the worker's run, with the same default, maximum and wrap-up as max_turn_tokens of send_workspace_message. Not accepted with task_group_id. | |
| executor_agent_id | No | An agent that already works in this Workspace: the Workspace's agent (default_agent_id from list_workspaces) or the agent_id of an earlier worker. Omitted, a new agent is created for this worker. Another agent of the account is refused with 409 workspace_worker_binding_refused. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cause | No | Machine-readable cause of a run that did not finish normally. | |
| run_id | No | The worker's run, present once it has started. get_run_result reads its reply, steer_workspace_worker sends it a message while it runs, and cancel_run stops it. | |
| status | Yes | Where the worker is: received, ready or blocked while it waits to start (queue_reason says why it is blocked), starting, running, or terminal when its run has ended (run_status says how). | |
| activity | No | The worker's expiring activity hint; absent when expired or unavailable. The saved changeset is authoritative. | |
| agent_id | Yes | The agent that runs the worker. get_run_result and cancel_run take it with run_id. | |
| run_status | No | The run's status: running, awaiting_input (paused on an approval or question; get_run_result lists them), completed, error or cancelled. | |
| save_state | Yes | Whether the worker's files are saved: none (no run has ended), pending (saving), ready (saved as saved_revision_id), failed (see save_failure) or unconfirmed (the save could not be confirmed). | |
| session_id | Yes | The worker's own conversation id. It is private to the worker; send_workspace_message cannot select it. | |
| stop_reason | No | The stop reason of an ended run, when one was recorded. | |
| changeset_id | No | The changeset submitted for this worker's files, if any. | |
| queue_reason | No | Why a waiting worker has not started, such as a capacity or balance limit. | |
| save_failure | No | Why the save failed, when save_state is failed. | |
| workspace_id | Yes | The Workspace UUID. | |
| base_revision | Yes | The saved revision the worker's copy started from. | |
| change_status | Yes | unsubmitted until the worker's files are submitted (by Plori when the run completes normally with changed files, or by submit_workspace_changeset), then the changeset's state. | |
| task_group_id | Yes | The task group of the worker. get_workspace_costs and stop_workspace_task_group take it. | |
| working_copy_id | Yes | The copy of the Workspace files that this worker edits. The Workspace's current files do not change until its changes are accepted. | |
| saved_revision_id | No | The saved revision that holds the worker's files once save_state is ready. read_workspace_file reads files from it. | |
| worker_request_id | Yes | The worker's id; get_workspace_worker takes it. | |
| saved_operation_id | No | The save that produced saved_revision_id. |