Sign in
agents

Retarget a running agent's sticky runtime settings.

Changed on

Switches the model a running agent uses from its next response on, the only runtime setting today. The new model is validated exactly as a launch with it would be (present in the agent type's catalog, enabled by admin policy, and reachable with the credentials the requesting user can see, on the run's own route). The switch is posted to the agent's box as the harness's own instruction, which the box keeps across suspends (a sleeping box wakes to take it), and then recorded on the agent, so it is what cost attribution records from here on. Returns the updated agent record. 409 agent_not_switchable for a run that is still starting or can no longer take a turn (stopping/stopped/error/terminated), 400 model_switch_unsupported for a harness that takes its model only at startup, 400 agent_type_has_no_model_catalog for a single-model agent type, 400 model_not_in_catalog for a model outside the catalog, 400 model_not_reachable_for_run for a model on the other route than the run's (direct or AI Gateway), 403 model_not_allowed when admin policy disables the model or its provider, and 503 model_switch_not_delivered when the instruction could not be posted, in which case nothing changed.

post/agents/{id}/runtime-settings

Request

  • Base URL: /api (relative, and the document was published on a file host, not at the API’s origin)
  • URL: /api/agents/{id}/runtime-settings
  • Auth: none declared. Required headers: x-organization-id

Path parameters

idstring required

Headers

x-organization-idstring required

Active organization id (or slug). Required for org-scoped operations; the generated client enforces it at compile time.

Request body

modelstring

Response

Response

idstring required
streamIdstring required
agentTypestring required
status'starting' | 'running' | 'needs_input' | 'completed' | 'interrupted' | 'stopping' | 'stopped' | 'error' | 'terminated' required
turnState'working' | 'idle' nullable required
turnStateVersioninteger required
devboxIdstring nullable required
tunnelKeystring nullable
namestring required
promptstring required
systemPromptstring nullable
personaIdstring nullable
modelstring nullable
blueprintIdstring nullable
blueprintNamestring nullable
promptMode'implement' | 'plan' | 'review' nullable
createdAtnumber required
lastActiveAtnumber nullable
archivedboolean required
ownerIdstring required
userIdstring nullable
prUrlstring nullable
hasBackgroundWorkboolean
listenersEnabledboolean
suspendAtTurnEndboolean
organizationIdstring required
modelProviderSecretIdstring nullable
credentialSyncPendingboolean nullable
originatorstring nullable
pinnedboolean required
mark'blocked' | 'in_review' | 'completed' nullable
viewerAccess'owner' | 'edit' | 'view'

Changes