Skip to main content

Update environment template

Update an environment template; omitted fields keep their current values.

Endpoint

POST /agents/environments/templates/{template_id} Returns 200 and the complete updated environment template. Omitted fields keep their current values.

Path parameters

template_id string (required)Environment template ID

Request body

name string / null (optional)Template namepackages object (optional)Packages grouped by npm, python, and systemenv object<string,string> (optional)Environment variables; the same name and value limits apply as at template creationsetup_commands array (optional)Setup commands executed in ordernetwork object (optional)Network policy with access and allowed_domains; 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 directoriesskills 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_idWhen only name is provided, existing network, capability_directories, and other configuration remain unchanged.An explicit null resets the field: name is cleared, network returns to the default policy, desktop returns to enabled=false, and array fields are cleared.

Request example

curl -sS -X POST "$BASE_URL/agents/environments/templates/envtmpl_xxx" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "OpenAI-Beta: agents=v1" \
  -H "Content-Type: application/json" \
  -d '{"name": "example-template-v2"}'

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_idResponses do not return env or setup_commands.

Response example

{
  "id": "envtmpl_xxx",
  "name": "example-template-v2",
  "object": "agent.environment.template",
  "created_at": 1794319007,
  "updated_at": 1794319102,
  "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
404not_found_error / not_found_errorUse an environment template ID that exists in the current workspace
500server_error / server_errorRetry later. If it keeps failing, submit a ticket with x-request-id