Move an agent's work to another machine and/or switch its model.
One mechanism for a Mac to Boat handoff, a Boat to Mac handoff and a model, connection or harness switch.
POST/api/v1/agents/{id}/move
Scopecrews
The same agent continues; no second agent is created. A working agent keeps working while its work (uncommitted changes too) is copied onto the task branch; then its turn is stopped at a safe point, what it left is saved, and its next run continues from that commit and is told it is taking over. target defaults to {"kind": "stay"} (a switch only); connectionId, model and options default to the agent's own. A move to the cloud goes through the planner like a launch: it reserves budget, honours the crew's and the install's caps and the start gates, and may start a VM. Follow it with agent.move events or GET /agents/{id}/moves. When an API key calls it, the timeline records who did what and the outcome. No query parameters.
Path parameters.
idstringrequired
The agent's id.
Headers.
Idempotency-Keystring
Makes a retry safe: the same key with the same request returns the first answer and does nothing else.
Body.
targetobject
Where the work goes. Default: stay on the machine it is on (a model or harness switch). Default {"kind":"stay"}.
ShowHide 2 fields
kindenumrequired
stay on the machine it is on, cloud, or node with nodeId.
nodeIdstring
The machine to move to. At least 5 characters. With kind node.
connectionIdstring
Another model connection (its harness comes with it). Default: the agent's own. At least 5 characters.
modelstring
Model on that connection. Default: the agent's model when the connection is unchanged, else the connection's default. At least 1 character.
optionsobject
Per-run settings chosen alongside a model. Unset means the harness's own default.
ShowHide 1 field
effortenum
How much reasoning the model spends, where its harness lets you choose. Left out, the harness's default. One of low, medium, high, xhigh, max.
Response.
200 OK: a JSON object. The example has placeholder values.
- 409 conflict
- Refused with
409 conflictand the reason, changing nothing, when the agent or the target cannot do it now (readGET /agents/{id}/move-optionsfirst). - 422 validation_failed
- The body does not match its schema; each problem is in
details.