Skip to main content

Create environment template

Create a reusable environment template that stores container, dependency, network, initial file, and skill configuration.

Endpoint

POST /agents/environments/templates Returns 201 and the complete environment template. The request body can be empty; in that case the template is created with default configuration.

Request body

name string / null (optional)Template namepackages object (optional)Packages grouped by npm, python, and system; all three groups default to empty arraysenv object<string,string> (optional)Environment variables; names must match [A-Za-z_][A-Za-z0-9_]*, cannot be PATH, and cannot start with a server-reserved prefix; values cannot contain NULsetup_commands array (optional)Setup commands executed in order. Each item requires command and accepts an optional cwd; cwd defaults to /workspacenetwork object (optional)Network policy, defaults to enabled; blocked_domains is not accepteddesktop object (optional)Desktop settings; only enabled=false is accepted, and enabled=true returns 400capability_directories array<string> (optional)Capability discovery directories, defaults to []skills array (optional)Skill configuration, fixed as skill_referenceplugins array (optional)Plugin configuration; only an empty array is supported, and non-empty arrays return 400files array (optional)Initial file configuration, fixed as file_id
python array<string> (optional)Python packagessystem array<string> (optional)System packagesnpm array<string> (optional)npm packages
command string (optional)Setup commandcwd string (optional)Working directory, defaults to /workspace
access string (optional)Network access mode, enabled, disabled, or restrictedallowed_domains array<string> (optional)Allowed domains when access=restricted
enabled boolean (optional)Whether the desktop is enabled
Template responses do not return env or setup_commands. files is always file_id, and skills is always skill_reference.

Request example

curl -sS -X POST "$BASE_URL/agents/environments/templates" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "OpenAI-Beta: agents=v1" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "example-template",
    "network": {"access": "disabled"},
    "capability_directories": ["/workspace/skills"]
  }'

Response fields

id stringEnvironment template IDobject stringEnvironment template object type, fixed as agent.environment.templatename string / nullTemplate namecreated_at integerCreation time in Unix secondsupdated_at integerLast update time in Unix secondspackages objectPackages with python, system, and npmnetwork objectNetwork policy with access and allowed_domainsdesktop objectDesktop settings with enabledcapability_directories array<string>Capability discovery directoriesskills arraySkill configuration with type, skill_id, and versionplugins arraySafe plugin metadata. Contains type, name, and description; currently an empty arrayfiles arrayInitial file configuration; each item contains type, path, and file_id

Response example

{
  "id": "envtmpl_xxx",
  "name": "example-template",
  "object": "agent.environment.template",
  "created_at": 1794319007,
  "updated_at": 1794319007,
  "packages": {"python": [], "system": [], "npm": []},
  "network": {"access": "disabled", "allowed_domains": []},
  "desktop": {"enabled": false},
  "capability_directories": ["/workspace/skills"],
  "skills": [],
  "plugins": [],
  "files": []
}

Error codes

HTTP statusError type / codeSolution
400invalid_request_error / invalid_request_errorFix the request body as described for each field
400invalid_request_error / invalid_request_errordesktop.enabled=true, non-empty plugins, and network.blocked_domains are rejected; adjust the field accordingly
401authentication_error / invalid_api_keySend a valid Authorization: Bearer $DASHSCOPE_API_KEY header
500server_error / server_errorRetry later. If it keeps failing, submit a ticket with x-request-id