Move a session to another version of its agent

curl --request PUT \
  --url https://api.recursion.labelbox.com/managed-agents/v2/sessions/{sessionId}/agent-version \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "agentVersionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "replaceActiveOutcome": false
}
'

import requests

url = "https://api.recursion.labelbox.com/managed-agents/v2/sessions/{sessionId}/agent-version"

payload = {
    "agentVersionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "replaceActiveOutcome": False
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    agentVersionId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    replaceActiveOutcome: false
  })
};

fetch('https://api.recursion.labelbox.com/managed-agents/v2/sessions/{sessionId}/agent-version', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.recursion.labelbox.com/managed-agents/v2/sessions/{sessionId}/agent-version",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'agentVersionId' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'replaceActiveOutcome' => false
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.recursion.labelbox.com/managed-agents/v2/sessions/{sessionId}/agent-version"

	payload := strings.NewReader("{\n  \"agentVersionId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"replaceActiveOutcome\": false\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.put("https://api.recursion.labelbox.com/managed-agents/v2/sessions/{sessionId}/agent-version")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"agentVersionId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"replaceActiveOutcome\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.recursion.labelbox.com/managed-agents/v2/sessions/{sessionId}/agent-version")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"agentVersionId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"replaceActiveOutcome\": false\n}"

response = http.request(request)
puts response.read_body

{
  "agentVersionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "currentAgentVersionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "lastFailure": {
    "agentVersionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "at": "2023-11-07T05:31:56Z",
    "code": "<string>",
    "message": "<string>",
    "version": 4503599627370496
  },
  "latestAgentVersion": {
    "agentVersionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "version": 4503599627370496
  },
  "members": [
    {
      "adoption": "current",
      "name": "<string>",
      "role": "root",
      "sessionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "agentVersionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "failure": {
        "agentVersionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "at": "2023-11-07T05:31:56Z",
        "code": "<string>",
        "message": "<string>",
        "version": 4503599627370496
      },
      "version": 4503599627370496
    }
  ],
  "pending": {
    "agentVersionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "requestedAt": "2023-11-07T05:31:56Z",
    "requestedByUserId": "<string>",
    "version": 4503599627370496
  },
  "state": "current",
  "currentVersion": 4503599627370496,
  "replaceActiveOutcome": false
}

{
  "code": "invalid_json",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

{
  "code": "unauthorized",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

{
  "code": "forbidden",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

{
  "code": "not_found",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

{
  "code": "conflict",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

{
  "code": "payload_too_large",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

{
  "code": "unsupported_media_type",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

{
  "code": "rate_limit_exceeded",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

{
  "code": "internal_error",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

{
  "code": "bad_gateway",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

{
  "code": "managed_agents_unavailable",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

{
  "code": "gateway_timeout",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

Sessions

Move a session to another version of its agent

Sets the version of its agent a root session runs. 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. Setting replaceActiveOutcome also replaces an active caller-supplied outcome with the target default, including on a session already at that version, preserving its objective, pass limit and grading history. An outcome under evaluation waits; terminal outcomes remain unchanged. Explicit replacement requires a usable target default rubric. 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 managedAgentsGetSessionAgentVersionV2 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.

PUT

managed-agents

sessions

{sessionId}

agent-version

Move a session to another version of its agent

curl --request PUT \
  --url https://api.recursion.labelbox.com/managed-agents/v2/sessions/{sessionId}/agent-version \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "agentVersionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "replaceActiveOutcome": false
}
'

import requests

url = "https://api.recursion.labelbox.com/managed-agents/v2/sessions/{sessionId}/agent-version"

payload = {
    "agentVersionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "replaceActiveOutcome": False
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    agentVersionId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    replaceActiveOutcome: false
  })
};

fetch('https://api.recursion.labelbox.com/managed-agents/v2/sessions/{sessionId}/agent-version', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.recursion.labelbox.com/managed-agents/v2/sessions/{sessionId}/agent-version",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'agentVersionId' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'replaceActiveOutcome' => false
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.recursion.labelbox.com/managed-agents/v2/sessions/{sessionId}/agent-version"

	payload := strings.NewReader("{\n  \"agentVersionId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"replaceActiveOutcome\": false\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.put("https://api.recursion.labelbox.com/managed-agents/v2/sessions/{sessionId}/agent-version")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"agentVersionId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"replaceActiveOutcome\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.recursion.labelbox.com/managed-agents/v2/sessions/{sessionId}/agent-version")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"agentVersionId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"replaceActiveOutcome\": false\n}"

response = http.request(request)
puts response.read_body

{
  "agentVersionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "currentAgentVersionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "lastFailure": {
    "agentVersionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "at": "2023-11-07T05:31:56Z",
    "code": "<string>",
    "message": "<string>",
    "version": 4503599627370496
  },
  "latestAgentVersion": {
    "agentVersionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "version": 4503599627370496
  },
  "members": [
    {
      "adoption": "current",
      "name": "<string>",
      "role": "root",
      "sessionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "agentVersionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "failure": {
        "agentVersionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "at": "2023-11-07T05:31:56Z",
        "code": "<string>",
        "message": "<string>",
        "version": 4503599627370496
      },
      "version": 4503599627370496
    }
  ],
  "pending": {
    "agentVersionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "requestedAt": "2023-11-07T05:31:56Z",
    "requestedByUserId": "<string>",
    "version": 4503599627370496
  },
  "state": "current",
  "currentVersion": 4503599627370496,
  "replaceActiveOutcome": false
}

{
  "code": "invalid_json",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

{
  "code": "unauthorized",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

{
  "code": "forbidden",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

{
  "code": "not_found",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

{
  "code": "conflict",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

{
  "code": "payload_too_large",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

{
  "code": "unsupported_media_type",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

{
  "code": "rate_limit_exceeded",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

{
  "code": "internal_error",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

{
  "code": "bad_gateway",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

{
  "code": "managed_agents_unavailable",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

{
  "code": "gateway_timeout",
  "message": "<string>",
  "details": {
    "field": "<string>",
    "issues": [
      "<string>"
    ],
    "requestId": "<string>",
    "retryable": true
  }
}

Authorizations

Authorization

string

header

required

A Recursion API key, created in the console under API keys.

Headers

x-tenant-id

string

Optional tenant consistency check. When present, it must name the tenant bound to the API key, including when x-organization-id is default.

Minimum string length: 1

x-organization-id

string

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.

Minimum string length: 1

Path Parameters

sessionId

string<uuid>

required

Session id (UUID) as returned by managedAgentsStartSession or managedAgentsListSessions.

Body

application/json

The agent version a root session should run.

agentVersionId

string<uuid>

required

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.

replaceActiveOutcome

boolean

default:false

Explicitly replace an active outcome, including one supplied by a caller, with this version's default rubric while preserving its objective, pass limit and grading history. A grader already in flight finishes first; terminal outcomes are not replaced. Works even when the session already runs agentVersionId.

Response

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.

agentVersionId

string<uuid>

required

Version the session is set to run: the pending version while a move is waiting, otherwise the version it runs now.

currentAgentVersionId

string<uuid>

required

read-only

Version the session runs now.

lastFailure

null | object

required

Why the most recent move was refused, or null. Null while a newer move is pending.

Show child attributes

latestAgentVersion

null | object

required

The agent's newest version, or null when the agent has been deleted.

Show child attributes

members

object[]

required

read-only

The root session and every open thread of its tree, root first, with how far each has followed the root.

Show child attributes

pending

null | object

required

The move waiting to take effect, or null.

Show child attributes

state

enum<string>

required

read-only

current: no version move is waiting; a recorded outcome replacement may still wait for the next model operation. 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.

Available options:

current,

pending,

failed

currentVersion

integer<int64>

read-only

Number of currentAgentVersionId within its agent. Absent when the number can no longer be read.

Required range: 1 <= x <= 9007199254740991

replaceActiveOutcome

boolean

default:false

Whether the pending version request explicitly replaces the active outcome with the target version default rubric. Omitted means false.

API reference

Endpoints

Move a session to another version of its agent

Authorizations

Headers

Path Parameters

Body

Response