> ## Documentation Index > Fetch the complete documentation index at: https://docs.labelbox.com/llms.txt > Use this file to discover all available pages before exploring further. # Move a session to another version of its agent > Sets the version of its agent a root session runs. The move is recorded at once and takes effect before the session's next model call, never in the middle of one: a sleeping session stays asleep and adopts the version when it next runs, and a finished session when it is next resumed. Threads adopt after their parent. The response is the representation managedAgentsGetSessionAgentVersion returns, with state pending until the move takes effect; if the version cannot run in this session, state becomes failed and lastFailure says why. Repeating the request while the move is pending, or once the session runs that version, changes nothing; repeating it after the move failed asks again. The later of two different requests wins, and naming the version the session already runs withdraws a pending move. Because a version can grant the session the vaults a new session would receive, the caller needs both managed-agents:create and managed-agents:update. Sessions that are members of another session's tree, sessions the platform runs itself, evaluations and pull request reviews stay on the version they started with and answer 409 conflict, as does a session that was not started from an agent, and one that is stopping or can no longer continue. A version of another agent answers 404. ## OpenAPI ````yaml /recursion/openapi.yaml put /managed-agents/v1/sessions/{sessionId}/agent-version openapi: 3.1.0 info: title: Managed Agents API version: 0.14.0 description: >- The Recursion Managed Agents REST API. Authenticate with a Recursion API key as a bearer token. An organization-scoped key acts in its own organization and needs nothing else; a tenant-scoped key must also send `x-organization-id` with an organization id or `default`. Field names follow each operation's published schema. servers: - url: https://api.recursion.labelbox.com security: - bearerAuth: [] paths: /managed-agents/v1/sessions/{sessionId}/agent-version: put: tags: - Sessions summary: Move a session to another version of its agent description: >- Sets the version of its agent a root session runs. The move is recorded at once and takes effect before the session's next model call, never in the middle of one: a sleeping session stays asleep and adopts the version when it next runs, and a finished session when it is next resumed. Threads adopt after their parent. The response is the representation managedAgentsGetSessionAgentVersion returns, with state pending until the move takes effect; if the version cannot run in this session, state becomes failed and lastFailure says why. Repeating the request while the move is pending, or once the session runs that version, changes nothing; repeating it after the move failed asks again. The later of two different requests wins, and naming the version the session already runs withdraws a pending move. Because a version can grant the session the vaults a new session would receive, the caller needs both managed-agents:create and managed-agents:update. Sessions that are members of another session's tree, sessions the platform runs itself, evaluations and pull request reviews stay on the version they started with and answer 409 conflict, as does a session that was not started from an agent, and one that is stopping or can no longer continue. A version of another agent answers 404. operationId: managedAgentsReplaceSessionAgentVersion parameters: - description: >- Session id (UUID) as returned by managedAgentsStartSession or managedAgentsListSessions. in: path name: sessionId required: true schema: description: >- Session id (UUID) as returned by managedAgentsStartSession or managedAgentsListSessions. format: uuid type: string - $ref: '#/components/parameters/RecursionTenantId' - $ref: '#/components/parameters/RecursionOrganizationId' requestBody: content: application/json: schema: $ref: '#/components/schemas/ReplaceSessionAgentVersionRequest' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/SessionAgentVersion' description: >- The agent version a root session runs, the move waiting to take effect if any, and how far each member of the session tree has followed. headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '400': description: Bad Request. content: application/json: schema: oneOf: - $ref: '#/components/schemas/ManagedAgentsApiErrorInvalidJson' - $ref: '#/components/schemas/ManagedAgentsApiErrorInvalidRequest' discriminator: propertyName: code mapping: invalid_json: '#/components/schemas/ManagedAgentsApiErrorInvalidJson' invalid_request: '#/components/schemas/ManagedAgentsApiErrorInvalidRequest' x-recursion-error-codes: - invalid_json - invalid_request headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '401': description: Unauthorized. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorUnauthorized' x-recursion-error-codes: - unauthorized headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorForbidden' x-recursion-error-codes: - forbidden headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '404': description: Not Found. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorNotFound' x-recursion-error-codes: - not_found headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '409': description: Conflict. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorConflict' x-recursion-error-codes: - conflict headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '413': description: Payload Too Large. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorPayloadTooLarge' x-recursion-error-codes: - payload_too_large headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '415': description: Unsupported Media Type. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorUnsupportedMediaType' x-recursion-error-codes: - unsupported_media_type headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '429': headers: Retry-After: description: When to retry, as delay seconds or an HTTP date. schema: type: string recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' description: Too Many Requests. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorRateLimitExceeded' x-recursion-error-codes: - rate_limit_exceeded '500': description: Internal Server Error. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorInternalError' x-recursion-error-codes: - internal_error headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '502': description: A dependent service returned an invalid response. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorDependencyFailure' x-recursion-error-codes: - bad_gateway headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '503': description: Service Unavailable. content: application/json: schema: oneOf: - $ref: >- #/components/schemas/ManagedAgentsApiErrorManagedAgentsUnavailable - $ref: '#/components/schemas/ManagedAgentsApiErrorPersistenceBusy' - $ref: >- #/components/schemas/ManagedAgentsApiErrorServiceUnavailable discriminator: propertyName: code mapping: managed_agents_unavailable: >- #/components/schemas/ManagedAgentsApiErrorManagedAgentsUnavailable persistence_busy: '#/components/schemas/ManagedAgentsApiErrorPersistenceBusy' service_unavailable: >- #/components/schemas/ManagedAgentsApiErrorServiceUnavailable x-recursion-error-codes: - managed_agents_unavailable - persistence_busy - service_unavailable headers: recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' '504': headers: Retry-After: description: When to retry, as delay seconds or an HTTP date. schema: type: string recursion-organization-id: $ref: '#/components/headers/RecursionOrganizationId' recursion-tenant-id: $ref: '#/components/headers/RecursionTenantId' description: A dependent service timed out. content: application/json: schema: $ref: '#/components/schemas/ManagedAgentsApiErrorDependencyTimeout' x-recursion-error-codes: - gateway_timeout components: parameters: RecursionTenantId: name: x-tenant-id in: header required: false description: >- Optional tenant consistency check. When present, it must name the tenant bound to the API key, including when x-organization-id is `default`. schema: type: string minLength: 1 RecursionOrganizationId: name: x-organization-id in: header required: false description: >- Organization 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`. schema: type: string minLength: 1 schemas: ReplaceSessionAgentVersionRequest: additionalProperties: false description: The agent version a root session should run. properties: agentVersionId: description: >- Version the session should run. It must be a version of the session's own agent. Naming the version the session already runs withdraws a move that is still pending. format: uuid type: string required: - agentVersionId type: object SessionAgentVersion: additionalProperties: false description: >- The agent version a root session runs, the move waiting to take effect if any, and how far each member of the session tree has followed. properties: agentVersionId: description: >- Version the session is set to run: the pending version while a move is waiting, otherwise the version it runs now. format: uuid type: string currentAgentVersionId: description: Version the session runs now. format: uuid readOnly: true type: string currentVersion: description: >- Number of currentAgentVersionId within its agent. Absent when the number can no longer be read. format: int64 minimum: 1 readOnly: true type: integer maximum: 9007199254740991 lastFailure: anyOf: - type: 'null' - $ref: '#/components/schemas/SessionAgentVersionFailure' description: >- Why the most recent move was refused, or null. Null while a newer move is pending. readOnly: true latestAgentVersion: anyOf: - type: 'null' - $ref: '#/components/schemas/SessionAgentVersionRef' description: The agent's newest version, or null when the agent has been deleted. readOnly: true members: description: >- The root session and every open thread of its tree, root first, with how far each has followed the root. items: $ref: '#/components/schemas/SessionAgentVersionMember' readOnly: true type: array pending: anyOf: - type: 'null' - $ref: '#/components/schemas/SessionAgentVersionPending' description: The move waiting to take effect, or null. readOnly: true state: description: >- current: nothing is waiting. pending: agentVersionId takes effect before the session's next model call. failed: the last move was refused and the session stayed on currentAgentVersionId; lastFailure says why. enum: - current - pending - failed readOnly: true type: string required: - agentVersionId - currentAgentVersionId - state - pending - lastFailure - latestAgentVersion - members type: object ManagedAgentsApiErrorInvalidJson: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - invalid_json message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorInvalidRequest: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - invalid_request message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorUnauthorized: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - unauthorized message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorForbidden: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - forbidden message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorNotFound: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - not_found message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorConflict: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - conflict message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorPayloadTooLarge: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - payload_too_large message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorUnsupportedMediaType: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - unsupported_media_type message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorRateLimitExceeded: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - rate_limit_exceeded message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorInternalError: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - internal_error message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorDependencyFailure: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - bad_gateway message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorManagedAgentsUnavailable: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - managed_agents_unavailable message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorPersistenceBusy: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - persistence_busy message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorServiceUnavailable: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - service_unavailable message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. ManagedAgentsApiErrorDependencyTimeout: type: object properties: code: type: string minLength: 1 description: Stable machine-readable error code. enum: - gateway_timeout message: type: string minLength: 1 description: Human-readable error message. details: $ref: '#/components/schemas/ManagedAgentsApiErrorDetails' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. required: - code - message additionalProperties: false description: Standard flat error response. SessionAgentVersionFailure: additionalProperties: false properties: agentVersionId: description: >- Version that was refused. For a member of the tree that names no version of its own, the version the session moved to. format: uuid type: string at: description: When the move was refused. format: date-time type: string code: description: >- Stable reason for the refusal. Current values: agent_unavailable, agent_version_unavailable, agent_changed, session_not_eligible, evaluation_toolset, model_not_allowed, model_unavailable, model_config_invalid, project_required, configuration_invalid, and temporarily_unavailable (send the request again). The list may grow; clients must accept values not listed here. type: string message: description: One fixed sentence explaining code. type: string version: description: >- Number of that version within its agent. Absent when it is not known. format: int64 minimum: 1 type: integer maximum: 9007199254740991 required: - agentVersionId - code - message - at type: object SessionAgentVersionRef: additionalProperties: false properties: agentVersionId: description: Agent version id. format: uuid type: string version: description: >- Number of the version within its agent. Absent when the version has been deleted. format: int64 minimum: 1 type: integer maximum: 9007199254740991 required: - agentVersionId type: object SessionAgentVersionMember: additionalProperties: false properties: adoption: description: >- How far the member has followed the root. current: nothing to adopt. pending: it is running and adopts before its next model call. idle: it is not running and adopts when it is next given work. failed: its move was refused; failure says why. retained: it keeps the configuration it has, because its parent is closed or could not adopt, or its roster entry was removed. enum: - current - pending - idle - failed - retained type: string agentVersionId: description: >- Version the member runs now. Absent for a member with no agent of its own. format: uuid type: string failure: $ref: '#/components/schemas/SessionAgentVersionFailure' description: >- Why the member's move was refused. Present only when adoption is failed. name: description: Name the thread was given when it was created. Empty for the root. type: string role: description: >- What the member's configuration comes from. root: the session itself. self: a copy of its parent's own agent. worker: a thread with no agent of its own, which takes its parent's model and tools. roster: another agent named by the parent's roster. enum: - root - self - worker - roster type: string sessionId: description: The member's session id. format: uuid type: string version: description: >- Number of agentVersionId within its agent. Absent when agentVersionId is, or when the member runs a version of another agent. format: int64 minimum: 1 type: integer maximum: 9007199254740991 required: - sessionId - name - role - adoption type: object SessionAgentVersionPending: additionalProperties: false properties: agentVersionId: description: Version the session moves to. format: uuid type: string requestedAt: description: When the move was requested. format: date-time type: string requestedByUserId: description: User who requested the move. Absent when no user made the request. type: string version: description: >- Number of that version within its agent. Absent when the version has been deleted. format: int64 minimum: 1 type: integer maximum: 9007199254740991 required: - agentVersionId - requestedAt type: object ManagedAgentsApiErrorDetails: type: object properties: field: description: >- Request field or header responsible for the error, when one can be identified. type: string issues: description: >- Boundary-validation failures as path-prefixed human-readable messages. type: array items: type: string requestId: description: Request correlation identifier for support and log lookup. type: string retryable: description: >- Server advice about failure transience. `true` means transient, `false` means non-transient, and absence gives no advice. Automatic replay is allowed only when this field is not `false` and the operation-specific retry and idempotency contract permits replay. type: boolean additionalProperties: $ref: '#/components/schemas/PlatformSafeJsonValue' description: >- Optional structured error details. Reserved transport fields are typed; code-specific fields remain forward compatible. PlatformSafeJsonValue: description: >- A JSON value whose integer members stay within the exact ECMAScript safe-integer range at every nesting level. oneOf: - type: 'null' - type: boolean - type: string - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: number not: type: integer - type: array items: $ref: '#/components/schemas/PlatformSafeJsonValue' - additionalProperties: $ref: '#/components/schemas/PlatformSafeJsonValue' type: object headers: RecursionOrganizationId: description: Organization id resolved for this request. schema: type: string minLength: 1 RecursionTenantId: description: Tenant id resolved for this request. schema: type: string minLength: 1 securitySchemes: bearerAuth: type: http scheme: bearer description: A Recursion API key, created in the console under API keys. ````