Create a new immutable agent version

curl --request POST \
  --url https://api.recursion.labelbox.com/managed-agents/v1/agents/{agentId}/versions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "base_agent_version_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "model": "<string>",
  "name": "<string>",
  "built_in_integrations": [
    {
      "connection_id": "<string>",
      "tools": [
        "<string>"
      ]
    }
  ],
  "default_credential_refs": [
    {
      "credential_id": "<string>",
      "vault_id": "<string>"
    }
  ],
  "default_criteria": [
    {
      "criterion_key": "<string>",
      "criterion_text": "<string>",
      "label": "<string>",
      "section": "<string>"
    }
  ],
  "default_project_id": "<string>",
  "default_rubric": "<string>",
  "default_vault_ids": [
    "<string>"
  ],
  "defaultEvaluatorAgentId": "<string>",
  "description": "<string>",
  "disabled_integration_mcp_providers": [
    "<string>"
  ],
  "fileHistoryEnabled": true,
  "max_concurrent_sessions": 5000,
  "mcp_servers": [
    {}
  ],
  "metadata": {},
  "model_config": {
    "max_tokens": 0,
    "provider_params": {},
    "reasoning_effort": "<string>",
    "temperature": 123,
    "top_p": 123
  },
  "multiagent": {},
  "nativeIntegrations": [
    {
      "connectionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "permission": "<string>",
      "resources": [
        "<string>"
      ],
      "tools": [
        "<string>"
      ]
    }
  ],
  "oversight": {
    "advisor": {
      "model": "<string>"
    },
    "interventionist": {},
    "supervisor": {
      "model": "<string>"
    }
  },
  "skills": [
    {}
  ],
  "system": "<string>",
  "version_comment": "<string>",
  "web_search_enabled": true
}
'

import requests

url = "https://api.recursion.labelbox.com/managed-agents/v1/agents/{agentId}/versions"

payload = {
    "base_agent_version_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "model": "<string>",
    "name": "<string>",
    "built_in_integrations": [
        {
            "connection_id": "<string>",
            "tools": ["<string>"]
        }
    ],
    "default_credential_refs": [
        {
            "credential_id": "<string>",
            "vault_id": "<string>"
        }
    ],
    "default_criteria": [
        {
            "criterion_key": "<string>",
            "criterion_text": "<string>",
            "label": "<string>",
            "section": "<string>"
        }
    ],
    "default_project_id": "<string>",
    "default_rubric": "<string>",
    "default_vault_ids": ["<string>"],
    "defaultEvaluatorAgentId": "<string>",
    "description": "<string>",
    "disabled_integration_mcp_providers": ["<string>"],
    "fileHistoryEnabled": True,
    "max_concurrent_sessions": 5000,
    "mcp_servers": [{}],
    "metadata": {},
    "model_config": {
        "max_tokens": 0,
        "provider_params": {},
        "reasoning_effort": "<string>",
        "temperature": 123,
        "top_p": 123
    },
    "multiagent": {},
    "nativeIntegrations": [
        {
            "connectionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
            "permission": "<string>",
            "resources": ["<string>"],
            "tools": ["<string>"]
        }
    ],
    "oversight": {
        "advisor": { "model": "<string>" },
        "interventionist": {},
        "supervisor": { "model": "<string>" }
    },
    "skills": [{}],
    "system": "<string>",
    "version_comment": "<string>",
    "web_search_enabled": True
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    base_agent_version_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    model: '<string>',
    name: '<string>',
    built_in_integrations: [{connection_id: '<string>', tools: ['<string>']}],
    default_credential_refs: [{credential_id: '<string>', vault_id: '<string>'}],
    default_criteria: [
      {
        criterion_key: '<string>',
        criterion_text: '<string>',
        label: '<string>',
        section: '<string>'
      }
    ],
    default_project_id: '<string>',
    default_rubric: '<string>',
    default_vault_ids: ['<string>'],
    defaultEvaluatorAgentId: '<string>',
    description: '<string>',
    disabled_integration_mcp_providers: ['<string>'],
    fileHistoryEnabled: true,
    max_concurrent_sessions: 5000,
    mcp_servers: [{}],
    metadata: {},
    model_config: {
      max_tokens: 0,
      provider_params: {},
      reasoning_effort: '<string>',
      temperature: 123,
      top_p: 123
    },
    multiagent: {},
    nativeIntegrations: [
      {
        connectionId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
        permission: '<string>',
        resources: ['<string>'],
        tools: ['<string>']
      }
    ],
    oversight: {
      advisor: {model: '<string>'},
      interventionist: {},
      supervisor: {model: '<string>'}
    },
    skills: [{}],
    system: '<string>',
    version_comment: '<string>',
    web_search_enabled: true
  })
};

fetch('https://api.recursion.labelbox.com/managed-agents/v1/agents/{agentId}/versions', 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/v1/agents/{agentId}/versions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'base_agent_version_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'model' => '<string>',
    'name' => '<string>',
    'built_in_integrations' => [
        [
                'connection_id' => '<string>',
                'tools' => [
                                '<string>'
                ]
        ]
    ],
    'default_credential_refs' => [
        [
                'credential_id' => '<string>',
                'vault_id' => '<string>'
        ]
    ],
    'default_criteria' => [
        [
                'criterion_key' => '<string>',
                'criterion_text' => '<string>',
                'label' => '<string>',
                'section' => '<string>'
        ]
    ],
    'default_project_id' => '<string>',
    'default_rubric' => '<string>',
    'default_vault_ids' => [
        '<string>'
    ],
    'defaultEvaluatorAgentId' => '<string>',
    'description' => '<string>',
    'disabled_integration_mcp_providers' => [
        '<string>'
    ],
    'fileHistoryEnabled' => true,
    'max_concurrent_sessions' => 5000,
    'mcp_servers' => [
        [
                
        ]
    ],
    'metadata' => [
        
    ],
    'model_config' => [
        'max_tokens' => 0,
        'provider_params' => [
                
        ],
        'reasoning_effort' => '<string>',
        'temperature' => 123,
        'top_p' => 123
    ],
    'multiagent' => [
        
    ],
    'nativeIntegrations' => [
        [
                'connectionId' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
                'permission' => '<string>',
                'resources' => [
                                '<string>'
                ],
                'tools' => [
                                '<string>'
                ]
        ]
    ],
    'oversight' => [
        'advisor' => [
                'model' => '<string>'
        ],
        'interventionist' => [
                
        ],
        'supervisor' => [
                'model' => '<string>'
        ]
    ],
    'skills' => [
        [
                
        ]
    ],
    'system' => '<string>',
    'version_comment' => '<string>',
    'web_search_enabled' => true
  ]),
  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/v1/agents/{agentId}/versions"

	payload := strings.NewReader("{\n  \"base_agent_version_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"model\": \"<string>\",\n  \"name\": \"<string>\",\n  \"built_in_integrations\": [\n    {\n      \"connection_id\": \"<string>\",\n      \"tools\": [\n        \"<string>\"\n      ]\n    }\n  ],\n  \"default_credential_refs\": [\n    {\n      \"credential_id\": \"<string>\",\n      \"vault_id\": \"<string>\"\n    }\n  ],\n  \"default_criteria\": [\n    {\n      \"criterion_key\": \"<string>\",\n      \"criterion_text\": \"<string>\",\n      \"label\": \"<string>\",\n      \"section\": \"<string>\"\n    }\n  ],\n  \"default_project_id\": \"<string>\",\n  \"default_rubric\": \"<string>\",\n  \"default_vault_ids\": [\n    \"<string>\"\n  ],\n  \"defaultEvaluatorAgentId\": \"<string>\",\n  \"description\": \"<string>\",\n  \"disabled_integration_mcp_providers\": [\n    \"<string>\"\n  ],\n  \"fileHistoryEnabled\": true,\n  \"max_concurrent_sessions\": 5000,\n  \"mcp_servers\": [\n    {}\n  ],\n  \"metadata\": {},\n  \"model_config\": {\n    \"max_tokens\": 0,\n    \"provider_params\": {},\n    \"reasoning_effort\": \"<string>\",\n    \"temperature\": 123,\n    \"top_p\": 123\n  },\n  \"multiagent\": {},\n  \"nativeIntegrations\": [\n    {\n      \"connectionId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n      \"permission\": \"<string>\",\n      \"resources\": [\n        \"<string>\"\n      ],\n      \"tools\": [\n        \"<string>\"\n      ]\n    }\n  ],\n  \"oversight\": {\n    \"advisor\": {\n      \"model\": \"<string>\"\n    },\n    \"interventionist\": {},\n    \"supervisor\": {\n      \"model\": \"<string>\"\n    }\n  },\n  \"skills\": [\n    {}\n  ],\n  \"system\": \"<string>\",\n  \"version_comment\": \"<string>\",\n  \"web_search_enabled\": true\n}")

	req, _ := http.NewRequest("POST", 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.post("https://api.recursion.labelbox.com/managed-agents/v1/agents/{agentId}/versions")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"base_agent_version_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"model\": \"<string>\",\n  \"name\": \"<string>\",\n  \"built_in_integrations\": [\n    {\n      \"connection_id\": \"<string>\",\n      \"tools\": [\n        \"<string>\"\n      ]\n    }\n  ],\n  \"default_credential_refs\": [\n    {\n      \"credential_id\": \"<string>\",\n      \"vault_id\": \"<string>\"\n    }\n  ],\n  \"default_criteria\": [\n    {\n      \"criterion_key\": \"<string>\",\n      \"criterion_text\": \"<string>\",\n      \"label\": \"<string>\",\n      \"section\": \"<string>\"\n    }\n  ],\n  \"default_project_id\": \"<string>\",\n  \"default_rubric\": \"<string>\",\n  \"default_vault_ids\": [\n    \"<string>\"\n  ],\n  \"defaultEvaluatorAgentId\": \"<string>\",\n  \"description\": \"<string>\",\n  \"disabled_integration_mcp_providers\": [\n    \"<string>\"\n  ],\n  \"fileHistoryEnabled\": true,\n  \"max_concurrent_sessions\": 5000,\n  \"mcp_servers\": [\n    {}\n  ],\n  \"metadata\": {},\n  \"model_config\": {\n    \"max_tokens\": 0,\n    \"provider_params\": {},\n    \"reasoning_effort\": \"<string>\",\n    \"temperature\": 123,\n    \"top_p\": 123\n  },\n  \"multiagent\": {},\n  \"nativeIntegrations\": [\n    {\n      \"connectionId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n      \"permission\": \"<string>\",\n      \"resources\": [\n        \"<string>\"\n      ],\n      \"tools\": [\n        \"<string>\"\n      ]\n    }\n  ],\n  \"oversight\": {\n    \"advisor\": {\n      \"model\": \"<string>\"\n    },\n    \"interventionist\": {},\n    \"supervisor\": {\n      \"model\": \"<string>\"\n    }\n  },\n  \"skills\": [\n    {}\n  ],\n  \"system\": \"<string>\",\n  \"version_comment\": \"<string>\",\n  \"web_search_enabled\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.recursion.labelbox.com/managed-agents/v1/agents/{agentId}/versions")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"base_agent_version_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"model\": \"<string>\",\n  \"name\": \"<string>\",\n  \"built_in_integrations\": [\n    {\n      \"connection_id\": \"<string>\",\n      \"tools\": [\n        \"<string>\"\n      ]\n    }\n  ],\n  \"default_credential_refs\": [\n    {\n      \"credential_id\": \"<string>\",\n      \"vault_id\": \"<string>\"\n    }\n  ],\n  \"default_criteria\": [\n    {\n      \"criterion_key\": \"<string>\",\n      \"criterion_text\": \"<string>\",\n      \"label\": \"<string>\",\n      \"section\": \"<string>\"\n    }\n  ],\n  \"default_project_id\": \"<string>\",\n  \"default_rubric\": \"<string>\",\n  \"default_vault_ids\": [\n    \"<string>\"\n  ],\n  \"defaultEvaluatorAgentId\": \"<string>\",\n  \"description\": \"<string>\",\n  \"disabled_integration_mcp_providers\": [\n    \"<string>\"\n  ],\n  \"fileHistoryEnabled\": true,\n  \"max_concurrent_sessions\": 5000,\n  \"mcp_servers\": [\n    {}\n  ],\n  \"metadata\": {},\n  \"model_config\": {\n    \"max_tokens\": 0,\n    \"provider_params\": {},\n    \"reasoning_effort\": \"<string>\",\n    \"temperature\": 123,\n    \"top_p\": 123\n  },\n  \"multiagent\": {},\n  \"nativeIntegrations\": [\n    {\n      \"connectionId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n      \"permission\": \"<string>\",\n      \"resources\": [\n        \"<string>\"\n      ],\n      \"tools\": [\n        \"<string>\"\n      ]\n    }\n  ],\n  \"oversight\": {\n    \"advisor\": {\n      \"model\": \"<string>\"\n    },\n    \"interventionist\": {},\n    \"supervisor\": {\n      \"model\": \"<string>\"\n    }\n  },\n  \"skills\": [\n    {}\n  ],\n  \"system\": \"<string>\",\n  \"version_comment\": \"<string>\",\n  \"web_search_enabled\": true\n}"

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

{
  "agent_id": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "default_credential_refs": [
    {
      "credential_id": "<string>",
      "vault_id": "<string>"
    }
  ],
  "default_vault_ids": [
    "<string>"
  ],
  "disabled_integration_mcp_providers": [
    "<string>"
  ],
  "mcp_servers": [
    {}
  ],
  "model": "<string>",
  "model_config": {
    "max_tokens": 0,
    "provider_params": {},
    "reasoning_effort": "<string>",
    "temperature": 123,
    "top_p": 123
  },
  "name": "<string>",
  "organization_id": "<string>",
  "skills": [
    {}
  ],
  "system": "<string>",
  "tags": [
    {
      "color": "#14b8a6",
      "created_at": "2023-11-07T05:31:56Z",
      "label": "<string>",
      "organization_id": "<string>",
      "tag_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "updated_at": "2023-11-07T05:31:56Z",
      "description": "<string>"
    }
  ],
  "updated_at": "2023-11-07T05:31:56Z",
  "built_in_integrations": [
    {
      "connection_id": "<string>",
      "tools": [
        "<string>"
      ]
    }
  ],
  "default_criteria": [
    {
      "criterion_key": "<string>",
      "criterion_text": "<string>",
      "label": "<string>",
      "section": "<string>"
    }
  ],
  "default_project_id": "<string>",
  "default_rubric": "<string>",
  "defaultEvaluatorAgentId": "<string>",
  "description": "<string>",
  "execution_compatibility": "compatible",
  "fileHistoryEnabled": true,
  "latest_agent_version_id": "<string>",
  "max_concurrent_sessions": 5000,
  "metadata": {},
  "multiagent": {},
  "nativeIntegrations": [
    {
      "connectionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "permission": "<string>",
      "resources": [
        "<string>"
      ],
      "tools": [
        "<string>"
      ]
    }
  ],
  "oversight": {
    "advisor": {
      "agent": {
        "id": "<string>",
        "version": "<string>"
      },
      "mode": "off",
      "model": "<string>"
    },
    "interventionist": {
      "mode": "off"
    },
    "supervisor": {
      "agent": {
        "id": "<string>",
        "version": "<string>"
      },
      "mode": "off",
      "model": "<string>"
    }
  },
  "supports_new_sessions": true,
  "template": {
    "id": "<string>",
    "revision": 0
  },
  "toolMode": "native",
  "web_search_enabled": true
}

{
  "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": "managed_agent_immutable",
  "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
  }
}

Agents

Create a new immutable agent version

deprecated

Creates a new immutable agent version from a full definition and moves the agent’s latest pointer to it, in one atomic operation. base_agent_version_id must be the agent’s current latest_agent_version_id or the request is rejected with 409 revision_conflict, so the caller can re-read and retry rather than silently racing another writer. Every field is full content, there is no partial-update or omit-to-inherit semantics, so an omitted field is cleared rather than carried over from the base version. Tags are changed only through the dedicated agent tag routes. Invalid promptCacheTTL or promptCacheSharedTTL settings in model_config.provider_params return 400 when prompt caching is enabled. Invalid model_config and unsupported reasoning_effort values return 400, including when the model catalog lists no exact options for the selected model; a model catalog that cannot be read to verify them returns 503. The response’s execution definition and latest_agent_version_id are the exact values this call committed; created_at and updated_at are the authoritative persisted timestamps; tags are mutable catalog metadata and are not changed by this route. Do not automatically retry an ambiguous transport failure: re-read the agent’s latest version first, because this operation does not replay a prior response.

POST

managed-agents

agents

{agentId}

versions

Create a new immutable agent version

curl --request POST \
  --url https://api.recursion.labelbox.com/managed-agents/v1/agents/{agentId}/versions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "base_agent_version_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "model": "<string>",
  "name": "<string>",
  "built_in_integrations": [
    {
      "connection_id": "<string>",
      "tools": [
        "<string>"
      ]
    }
  ],
  "default_credential_refs": [
    {
      "credential_id": "<string>",
      "vault_id": "<string>"
    }
  ],
  "default_criteria": [
    {
      "criterion_key": "<string>",
      "criterion_text": "<string>",
      "label": "<string>",
      "section": "<string>"
    }
  ],
  "default_project_id": "<string>",
  "default_rubric": "<string>",
  "default_vault_ids": [
    "<string>"
  ],
  "defaultEvaluatorAgentId": "<string>",
  "description": "<string>",
  "disabled_integration_mcp_providers": [
    "<string>"
  ],
  "fileHistoryEnabled": true,
  "max_concurrent_sessions": 5000,
  "mcp_servers": [
    {}
  ],
  "metadata": {},
  "model_config": {
    "max_tokens": 0,
    "provider_params": {},
    "reasoning_effort": "<string>",
    "temperature": 123,
    "top_p": 123
  },
  "multiagent": {},
  "nativeIntegrations": [
    {
      "connectionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "permission": "<string>",
      "resources": [
        "<string>"
      ],
      "tools": [
        "<string>"
      ]
    }
  ],
  "oversight": {
    "advisor": {
      "model": "<string>"
    },
    "interventionist": {},
    "supervisor": {
      "model": "<string>"
    }
  },
  "skills": [
    {}
  ],
  "system": "<string>",
  "version_comment": "<string>",
  "web_search_enabled": true
}
'

import requests

url = "https://api.recursion.labelbox.com/managed-agents/v1/agents/{agentId}/versions"

payload = {
    "base_agent_version_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "model": "<string>",
    "name": "<string>",
    "built_in_integrations": [
        {
            "connection_id": "<string>",
            "tools": ["<string>"]
        }
    ],
    "default_credential_refs": [
        {
            "credential_id": "<string>",
            "vault_id": "<string>"
        }
    ],
    "default_criteria": [
        {
            "criterion_key": "<string>",
            "criterion_text": "<string>",
            "label": "<string>",
            "section": "<string>"
        }
    ],
    "default_project_id": "<string>",
    "default_rubric": "<string>",
    "default_vault_ids": ["<string>"],
    "defaultEvaluatorAgentId": "<string>",
    "description": "<string>",
    "disabled_integration_mcp_providers": ["<string>"],
    "fileHistoryEnabled": True,
    "max_concurrent_sessions": 5000,
    "mcp_servers": [{}],
    "metadata": {},
    "model_config": {
        "max_tokens": 0,
        "provider_params": {},
        "reasoning_effort": "<string>",
        "temperature": 123,
        "top_p": 123
    },
    "multiagent": {},
    "nativeIntegrations": [
        {
            "connectionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
            "permission": "<string>",
            "resources": ["<string>"],
            "tools": ["<string>"]
        }
    ],
    "oversight": {
        "advisor": { "model": "<string>" },
        "interventionist": {},
        "supervisor": { "model": "<string>" }
    },
    "skills": [{}],
    "system": "<string>",
    "version_comment": "<string>",
    "web_search_enabled": True
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    base_agent_version_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    model: '<string>',
    name: '<string>',
    built_in_integrations: [{connection_id: '<string>', tools: ['<string>']}],
    default_credential_refs: [{credential_id: '<string>', vault_id: '<string>'}],
    default_criteria: [
      {
        criterion_key: '<string>',
        criterion_text: '<string>',
        label: '<string>',
        section: '<string>'
      }
    ],
    default_project_id: '<string>',
    default_rubric: '<string>',
    default_vault_ids: ['<string>'],
    defaultEvaluatorAgentId: '<string>',
    description: '<string>',
    disabled_integration_mcp_providers: ['<string>'],
    fileHistoryEnabled: true,
    max_concurrent_sessions: 5000,
    mcp_servers: [{}],
    metadata: {},
    model_config: {
      max_tokens: 0,
      provider_params: {},
      reasoning_effort: '<string>',
      temperature: 123,
      top_p: 123
    },
    multiagent: {},
    nativeIntegrations: [
      {
        connectionId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
        permission: '<string>',
        resources: ['<string>'],
        tools: ['<string>']
      }
    ],
    oversight: {
      advisor: {model: '<string>'},
      interventionist: {},
      supervisor: {model: '<string>'}
    },
    skills: [{}],
    system: '<string>',
    version_comment: '<string>',
    web_search_enabled: true
  })
};

fetch('https://api.recursion.labelbox.com/managed-agents/v1/agents/{agentId}/versions', 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/v1/agents/{agentId}/versions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'base_agent_version_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'model' => '<string>',
    'name' => '<string>',
    'built_in_integrations' => [
        [
                'connection_id' => '<string>',
                'tools' => [
                                '<string>'
                ]
        ]
    ],
    'default_credential_refs' => [
        [
                'credential_id' => '<string>',
                'vault_id' => '<string>'
        ]
    ],
    'default_criteria' => [
        [
                'criterion_key' => '<string>',
                'criterion_text' => '<string>',
                'label' => '<string>',
                'section' => '<string>'
        ]
    ],
    'default_project_id' => '<string>',
    'default_rubric' => '<string>',
    'default_vault_ids' => [
        '<string>'
    ],
    'defaultEvaluatorAgentId' => '<string>',
    'description' => '<string>',
    'disabled_integration_mcp_providers' => [
        '<string>'
    ],
    'fileHistoryEnabled' => true,
    'max_concurrent_sessions' => 5000,
    'mcp_servers' => [
        [
                
        ]
    ],
    'metadata' => [
        
    ],
    'model_config' => [
        'max_tokens' => 0,
        'provider_params' => [
                
        ],
        'reasoning_effort' => '<string>',
        'temperature' => 123,
        'top_p' => 123
    ],
    'multiagent' => [
        
    ],
    'nativeIntegrations' => [
        [
                'connectionId' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
                'permission' => '<string>',
                'resources' => [
                                '<string>'
                ],
                'tools' => [
                                '<string>'
                ]
        ]
    ],
    'oversight' => [
        'advisor' => [
                'model' => '<string>'
        ],
        'interventionist' => [
                
        ],
        'supervisor' => [
                'model' => '<string>'
        ]
    ],
    'skills' => [
        [
                
        ]
    ],
    'system' => '<string>',
    'version_comment' => '<string>',
    'web_search_enabled' => true
  ]),
  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/v1/agents/{agentId}/versions"

	payload := strings.NewReader("{\n  \"base_agent_version_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"model\": \"<string>\",\n  \"name\": \"<string>\",\n  \"built_in_integrations\": [\n    {\n      \"connection_id\": \"<string>\",\n      \"tools\": [\n        \"<string>\"\n      ]\n    }\n  ],\n  \"default_credential_refs\": [\n    {\n      \"credential_id\": \"<string>\",\n      \"vault_id\": \"<string>\"\n    }\n  ],\n  \"default_criteria\": [\n    {\n      \"criterion_key\": \"<string>\",\n      \"criterion_text\": \"<string>\",\n      \"label\": \"<string>\",\n      \"section\": \"<string>\"\n    }\n  ],\n  \"default_project_id\": \"<string>\",\n  \"default_rubric\": \"<string>\",\n  \"default_vault_ids\": [\n    \"<string>\"\n  ],\n  \"defaultEvaluatorAgentId\": \"<string>\",\n  \"description\": \"<string>\",\n  \"disabled_integration_mcp_providers\": [\n    \"<string>\"\n  ],\n  \"fileHistoryEnabled\": true,\n  \"max_concurrent_sessions\": 5000,\n  \"mcp_servers\": [\n    {}\n  ],\n  \"metadata\": {},\n  \"model_config\": {\n    \"max_tokens\": 0,\n    \"provider_params\": {},\n    \"reasoning_effort\": \"<string>\",\n    \"temperature\": 123,\n    \"top_p\": 123\n  },\n  \"multiagent\": {},\n  \"nativeIntegrations\": [\n    {\n      \"connectionId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n      \"permission\": \"<string>\",\n      \"resources\": [\n        \"<string>\"\n      ],\n      \"tools\": [\n        \"<string>\"\n      ]\n    }\n  ],\n  \"oversight\": {\n    \"advisor\": {\n      \"model\": \"<string>\"\n    },\n    \"interventionist\": {},\n    \"supervisor\": {\n      \"model\": \"<string>\"\n    }\n  },\n  \"skills\": [\n    {}\n  ],\n  \"system\": \"<string>\",\n  \"version_comment\": \"<string>\",\n  \"web_search_enabled\": true\n}")

	req, _ := http.NewRequest("POST", 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.post("https://api.recursion.labelbox.com/managed-agents/v1/agents/{agentId}/versions")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"base_agent_version_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"model\": \"<string>\",\n  \"name\": \"<string>\",\n  \"built_in_integrations\": [\n    {\n      \"connection_id\": \"<string>\",\n      \"tools\": [\n        \"<string>\"\n      ]\n    }\n  ],\n  \"default_credential_refs\": [\n    {\n      \"credential_id\": \"<string>\",\n      \"vault_id\": \"<string>\"\n    }\n  ],\n  \"default_criteria\": [\n    {\n      \"criterion_key\": \"<string>\",\n      \"criterion_text\": \"<string>\",\n      \"label\": \"<string>\",\n      \"section\": \"<string>\"\n    }\n  ],\n  \"default_project_id\": \"<string>\",\n  \"default_rubric\": \"<string>\",\n  \"default_vault_ids\": [\n    \"<string>\"\n  ],\n  \"defaultEvaluatorAgentId\": \"<string>\",\n  \"description\": \"<string>\",\n  \"disabled_integration_mcp_providers\": [\n    \"<string>\"\n  ],\n  \"fileHistoryEnabled\": true,\n  \"max_concurrent_sessions\": 5000,\n  \"mcp_servers\": [\n    {}\n  ],\n  \"metadata\": {},\n  \"model_config\": {\n    \"max_tokens\": 0,\n    \"provider_params\": {},\n    \"reasoning_effort\": \"<string>\",\n    \"temperature\": 123,\n    \"top_p\": 123\n  },\n  \"multiagent\": {},\n  \"nativeIntegrations\": [\n    {\n      \"connectionId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n      \"permission\": \"<string>\",\n      \"resources\": [\n        \"<string>\"\n      ],\n      \"tools\": [\n        \"<string>\"\n      ]\n    }\n  ],\n  \"oversight\": {\n    \"advisor\": {\n      \"model\": \"<string>\"\n    },\n    \"interventionist\": {},\n    \"supervisor\": {\n      \"model\": \"<string>\"\n    }\n  },\n  \"skills\": [\n    {}\n  ],\n  \"system\": \"<string>\",\n  \"version_comment\": \"<string>\",\n  \"web_search_enabled\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.recursion.labelbox.com/managed-agents/v1/agents/{agentId}/versions")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"base_agent_version_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"model\": \"<string>\",\n  \"name\": \"<string>\",\n  \"built_in_integrations\": [\n    {\n      \"connection_id\": \"<string>\",\n      \"tools\": [\n        \"<string>\"\n      ]\n    }\n  ],\n  \"default_credential_refs\": [\n    {\n      \"credential_id\": \"<string>\",\n      \"vault_id\": \"<string>\"\n    }\n  ],\n  \"default_criteria\": [\n    {\n      \"criterion_key\": \"<string>\",\n      \"criterion_text\": \"<string>\",\n      \"label\": \"<string>\",\n      \"section\": \"<string>\"\n    }\n  ],\n  \"default_project_id\": \"<string>\",\n  \"default_rubric\": \"<string>\",\n  \"default_vault_ids\": [\n    \"<string>\"\n  ],\n  \"defaultEvaluatorAgentId\": \"<string>\",\n  \"description\": \"<string>\",\n  \"disabled_integration_mcp_providers\": [\n    \"<string>\"\n  ],\n  \"fileHistoryEnabled\": true,\n  \"max_concurrent_sessions\": 5000,\n  \"mcp_servers\": [\n    {}\n  ],\n  \"metadata\": {},\n  \"model_config\": {\n    \"max_tokens\": 0,\n    \"provider_params\": {},\n    \"reasoning_effort\": \"<string>\",\n    \"temperature\": 123,\n    \"top_p\": 123\n  },\n  \"multiagent\": {},\n  \"nativeIntegrations\": [\n    {\n      \"connectionId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n      \"permission\": \"<string>\",\n      \"resources\": [\n        \"<string>\"\n      ],\n      \"tools\": [\n        \"<string>\"\n      ]\n    }\n  ],\n  \"oversight\": {\n    \"advisor\": {\n      \"model\": \"<string>\"\n    },\n    \"interventionist\": {},\n    \"supervisor\": {\n      \"model\": \"<string>\"\n    }\n  },\n  \"skills\": [\n    {}\n  ],\n  \"system\": \"<string>\",\n  \"version_comment\": \"<string>\",\n  \"web_search_enabled\": true\n}"

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

{
  "agent_id": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "default_credential_refs": [
    {
      "credential_id": "<string>",
      "vault_id": "<string>"
    }
  ],
  "default_vault_ids": [
    "<string>"
  ],
  "disabled_integration_mcp_providers": [
    "<string>"
  ],
  "mcp_servers": [
    {}
  ],
  "model": "<string>",
  "model_config": {
    "max_tokens": 0,
    "provider_params": {},
    "reasoning_effort": "<string>",
    "temperature": 123,
    "top_p": 123
  },
  "name": "<string>",
  "organization_id": "<string>",
  "skills": [
    {}
  ],
  "system": "<string>",
  "tags": [
    {
      "color": "#14b8a6",
      "created_at": "2023-11-07T05:31:56Z",
      "label": "<string>",
      "organization_id": "<string>",
      "tag_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "updated_at": "2023-11-07T05:31:56Z",
      "description": "<string>"
    }
  ],
  "updated_at": "2023-11-07T05:31:56Z",
  "built_in_integrations": [
    {
      "connection_id": "<string>",
      "tools": [
        "<string>"
      ]
    }
  ],
  "default_criteria": [
    {
      "criterion_key": "<string>",
      "criterion_text": "<string>",
      "label": "<string>",
      "section": "<string>"
    }
  ],
  "default_project_id": "<string>",
  "default_rubric": "<string>",
  "defaultEvaluatorAgentId": "<string>",
  "description": "<string>",
  "execution_compatibility": "compatible",
  "fileHistoryEnabled": true,
  "latest_agent_version_id": "<string>",
  "max_concurrent_sessions": 5000,
  "metadata": {},
  "multiagent": {},
  "nativeIntegrations": [
    {
      "connectionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "permission": "<string>",
      "resources": [
        "<string>"
      ],
      "tools": [
        "<string>"
      ]
    }
  ],
  "oversight": {
    "advisor": {
      "agent": {
        "id": "<string>",
        "version": "<string>"
      },
      "mode": "off",
      "model": "<string>"
    },
    "interventionist": {
      "mode": "off"
    },
    "supervisor": {
      "agent": {
        "id": "<string>",
        "version": "<string>"
      },
      "mode": "off",
      "model": "<string>"
    }
  },
  "supports_new_sessions": true,
  "template": {
    "id": "<string>",
    "revision": 0
  },
  "toolMode": "native",
  "web_search_enabled": true
}

{
  "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": "managed_agent_immutable",
  "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

agentId

string<uuid>

required

Agent id (UUID) as returned by managedAgentsCreateAgent or managedAgentsListAgents.

Body

application/json

Request body for creating a new immutable standalone Managed Agent version. Send every field you want to keep: omitted fields are cleared, except that web search turns on and the template stays. base_agent_version_id must name the current version or the request is rejected with revision_conflict.

base_agent_version_id

string<uuid>

required

The agent's current latest_agent_version_id, as returned by managedAgentsGetAgent. Rejected with 409 revision_conflict if it is not the agent's current version, whether stale or unknown.

model

string

required

Public model id copied from GET /managed-agents/v1/models (for example anthropic/claude-sonnet-5-5). Agent reads return the same public id. An id the catalog does not list is rejected with a list of available public ids.

name

string

required

Human-readable label for the agent. Required, and not blank; surrounding whitespace is trimmed.

built_in_integrations

object[]

Built-in integrations this agent may use, each naming an active organization connection an admin added on the Integrations page. A non-empty tools list narrows this agent below the connection's organization allow-list; omission inherits it. Sessions receive short-lived access restricted to the effective tools; nothing is granted through a vault. Omit or send [] for no connections. Carried in full on every version write.

Maximum array length: 25

Show child attributes

default_credential_refs

object[]

Individual default items within default_vault_ids. The list is a whitelist across every default vault, not a filter within one, so it must name every item the agent should receive. Omit to select every item the default vaults hold when the agent is saved. The selection is stored with the agent version, so a credential added to one of those vaults later is not included until the agent is saved again with it selected. [] alongside a non-empty default_vault_ids is rejected because it would select none.

Show child attributes

default_criteria

object[]

The agent's default criteria, in order. Send [] to clear them. With defaultEvaluatorAgentId they define a default outcome for this agent's sessions; without one they are the criteria this agent checks when it evaluates another session. Send these or default_rubric; both are accepted only when the rubric parses to exactly these criteria, as in a read-back body, and the rubric is then kept as written. Criteria render to at most 256 KiB. An explicit session outcome overrides the default.

Maximum array length: 200

Show child attributes

default_project_id

null | string

Billing project copied into sessions started from this agent when their create request omits project_id. A non-empty session project_id overrides it. Accepted only on a model that GET /managed-agents/v1/models marks requiresProject; refused with 400 for an organization whose model list has no such model.

default_rubric

null | string

Deprecated: send default_criteria. Markdown rubric, read into the agent's default criteria when saved. With defaultEvaluatorAgentId it defines a default outcome for this agent's sessions; without one it supplies fallback criteria when this agent evaluates another session. Must contain at least one gradeable markdown list item. An explicit session outcome overrides the default.

default_vault_ids

string[]

Vaults granted by default when a session create request omits vault_ids. default_credential_refs may narrow their items.

defaultEvaluatorAgentId

string

Default evaluator for inherited outcomes and explicit outcomes that omit evaluatorAgentId. Without it, default_rubric supplies fallback criteria when this agent evaluates another session.

description

string

Optional free-text note about what the agent is for. Not sent to the model.

disabled_integration_mcp_providers

string[]

Native integration providers whose MCP tools sessions of this agent do not receive even though the grant is present; the agent's own mcp_servers are never affected. github is accepted but ignored, because a GitHub grant always keeps its MCP tools alongside git and gh in the sandbox. Omitting the field means none, on managedAgentsCreateAgent as on managedAgentsCreateAgentVersion.

fileHistoryEnabled

null | boolean

Whether sessions started from this agent may search and read the session outputs its earlier sessions saved, with search_agent_files and read_agent_file. Omit to leave it off. Checked again on every search and read, so turning it off takes effect at once.

max_concurrent_sessions

null | integer

Maximum number of this agent's root sessions that may run or wait on compute at once. Omit for unlimited. Sessions beyond the cap are accepted with execution_state=queued and wait until a slot frees; child/subagent sessions and outcome evaluation passes do not count.

Required range: 1 <= x <= 10000

mcp_servers

object[]

Remote MCP servers whose tools are added to the agent's tool surface. Each entry is an object with name and url, e.g. {"name": "docs", "url": "https://example.com/mcp"}. Credentials come from the vaults granted to the session, and the discovered tool list is snapshotted at session start, so a later edit here does not change a running session.

Show child attributes

metadata

object

Free-form caller-owned JSON stored with the agent and returned on reads. Not interpreted by the service and never sent to the model.

Show child attributes

model_config

object

Default inference config applied to sessions started from this agent. Omit model_config or send {} to use provider defaults; null is invalid. reasoning_effort is normalized and validated for direct providers, and must exactly match the selected catalog model's supportedReasoningEfforts. An unsupported reasoning_effort, including any value for a catalog model that lists no exact options, returns 400. Authored provider_params.thinking objects are validated. When prompt caching is enabled, invalid provider_params.promptCacheTTL or provider_params.promptCacheSharedTTL values, incompatible models, and shared retention shorter than promptCacheTTL return 400. These checks run on agent and version writes and again at session start; a model catalog that cannot be read to verify settings returns 503.

Show child attributes

multiagent

object

Multiagent roster: the delegation targets this agent may hand work to, team mode and limits. Snapshotted at session start; a child roster may tighten the recursion depth ceiling, never widen it.

Show child attributes

nativeIntegrations

object[]

Native connections this agent may use, with provider-enforced permission and resource restrictions. Omit or send [] for none. Stored in full on each agent version; secrets remain on the connection.

Maximum array length: 25

Show child attributes

oversight

object

Course correction of this agent's running sessions: an advisor it may consult, the interventionist's template steers, and a supervisor that steers or halts when a detector fires. Snapshotted at session start.

Show child attributes

skills

object[]

Skill declarations made available to the agent, passed through as given and snapshotted into the session at start. Capped at the 100 skills a session can carry.

Maximum array length: 100

Show child attributes

system

string

Optional system prompt for the agent. Omit it or send an empty string for none: the agent then runs on the platform's short general-purpose instructions, and every session still tells it which tools it has and what its task is.

template

object

Reviewed template id and revision used to prefill this definition.

Show child attributes

toolMode

enum<string>

How sessions started from this agent reach their tools: native lists every tool to the model; codemode hides ordinary tools behind one JavaScript tool, keeping tools that need approval and read_file native. Omit for native. Refused when the organization is not enabled for codemode. Snapshotted when a session starts.

Available options:

native,

codemode

version_comment

string

Optional single-line note saved with this version, for change context. At most 2000 characters and no line breaks. Not part of the definition; it never affects config-equality or restore.

Maximum string length: 2000

web_search_enabled

boolean

default:true

Whether sessions started from this agent may use the native web_search tool. Omit to enable it. The setting is snapshotted when a session starts.

Response

A configured standalone Managed Agent: its versioned execution definition plus current mutable classification tags. Publishing the execution definition mints a new immutable version; applying tags does not.

agent_id

string

required

Server-assigned id of the agent, used in the agent, agent-version, and session routes.

created_at

string<date-time>

required

Server-assigned RFC 3339 timestamp of when the agent was created.

default_credential_refs

object[] | null

required

Narrows the default vaults to individual credentials. Every credential is selected when a vault is first added, and may then be unchecked.

Show child attributes

default_vault_ids

string[] | null

required

Vaults whose credentials are copied into a new session when its create request omits vault_ids. Sending an explicit empty list on the session still overrides these.

disabled_integration_mcp_providers

string[] | null

required

Native integration providers whose MCP tools new sessions of this agent do not receive, even though the grant is present. Suppresses integration-derived servers only, never the agent's own mcp_servers. github is ignored, because a GitHub grant always keeps its MCP tools alongside git and gh in the sandbox. A version write carries the list in full: omitting it publishes a version with none.

mcp_servers

object[] | null

required

Remote MCP servers to attach. Each entry is an object with name (the label the server's tools are grouped under) and url (its http/https endpoint); any further keys are passed to the runtime unchanged. Credentials come from the vaults granted to the session, not from this entry. Tools are discovered and snapshotted at session start.

Show child attributes

model

string

required

Public model id from GET /managed-agents/v1/models, for example anthropic/claude-sonnet-5-5. Agent reads return the same public id. An id the catalog does not list is rejected here, before the session starts.

model_config

object

required

Default inference settings for every turn. temperature and top_p are stored but not sent to the model.

Show child attributes

name

string

required

Human-readable label shown wherever agents are listed. Not required to be unique.

organization_id

string

required

Organization that owns the agent. Server-assigned from the authenticated principal; never accepted from the caller.

skills

object[] | null

required

Skill packages loaded into the agent's runtime, each an entry with the skill reference and its metadata.

Show child attributes

system

string

required

System prompt prepended to every conversation this agent runs.

API reference

Endpoints

Create a new immutable agent version

Authorizations

Headers

Path Parameters

Body

Response