Move an agent's live sessions to its latest version
Starts a background upgrade that asks every live root session of the agent the caller may change — active, queued, idle or awaiting a person — to move to the agent’s latest version, pinned when the request is accepted. It returns 202 at once with the upgrade; follow it with managedAgentsGetAgentSessionUpgrade. Each session is moved exactly as managedAgentsReplaceSessionAgentVersion moves one, and the move takes effect before that session’s next model call. A move brings the session’s instructions, model and inference settings, tools, MCP servers, skills, integrations, credentials and roster to the new version, tells the agent what changed, and moves an outcome the session inherited from the agent’s default rubric to the new version’s default; an outcome the caller supplied, or one already graded, is left as it is. Sessions that cannot move are counted as skipped with a reason and left as they are. One upgrade runs per agent at a time, and upgrades of different agents run side by side: repeating the request while the agent’s upgrade runs returns the running upgrade and starts nothing. An agentId that names no agent of the caller’s organization answers 404, and an agent with no version answers 409 conflict. Requires an Idempotency-Key header: the same key with the exact HTTP method, escaped path, raw query, and raw body bytes replays the original 202; any difference is rejected. The caller needs both managed-agents:create and managed-agents:update.
Authorizations
A Recursion API key, created in the console under API keys.
Headers
Replay-protection key in an organization-wide namespace shared by keyed mutations. It must contain 1 to 256 visible ASCII characters and be sent as exactly one header value. Request identity is the exact HTTP method, escaped path, raw query, and raw body bytes. For the legacy automation-run route only, the historical fingerprint ignores top-level JSON formatting and object-key order and removes the retired top-level idempotency_key field. The same request replays the original successful response; any different request returns 409 idempotency_conflict, and an active matching request returns 409 idempotency_in_progress. Completed receipts are retained for approximately 24 hours, pending claims may be reclaimed after approximately 1 hour, and no deduplication is guaranteed after expiry.
1 - 256^[!-~]+$Optional tenant consistency check. When present, it must name the tenant bound to the API key, including when x-organization-id is default.
1Organization in which to act. Required for a tenant-scoped API key. Optional for an organization-scoped key, where it must name that same organization. The value may be an organization id or default.
1Path Parameters
Agent id (UUID) as returned by managedAgentsCreateAgent or managedAgentsListAgents.
Response
A request to move every live root session of one agent to that agent's latest version, and how far it has come.
A request to move every live root session of one agent to that agent's latest version, and how far it has come.
The agent whose sessions this upgrade moves.
The agent's latest version when the upgrade was accepted: the version every session is asked to move to.
Sessions handled so far, by outcome.
When the upgrade completed or was cancelled, or null while it runs.
Up to 50 sessions the upgrade skipped or could not ask, in the order it met them. The counts are complete; this list is a sample.
50When the upgrade was accepted.
running: sessions are still being asked to move. completed: every live root session in scope has been asked. cancelled: the upgrade was stopped; sessions it had already asked still move.
running, completed, cancelled Path of the upgrade's status resource, where managedAgentsGetAgentSessionUpgrade reads it.
Identifier of this upgrade.
User who requested the upgrade. Absent when no user made the request.