Skip to main content

Create environment

Create a managed runtime environment with a container, dependencies, network policy, initial files, and skills.

Endpoint

POST /agents/environments Creates a managed runtime environment. A successful call returns 201, which means the environment is registered and asynchronous preparation has started. Creating a session that references the environment before preparation completes can fail.

Request body

environment object (required)Environment configuration, see below
type string (required)Environment type, fixed as openai_hostedenvironment_template_id string (optional)Environment template ID; the template must belong to the current workspace. Manage templates through Environment templates.env object (optional)Environment variables; names must match [A-Za-z_][A-Za-z0-9_]*, cannot be PATH, and cannot start with a reserved prefix; values cannot contain NULpackages object (optional)Packages grouped by npm, python, and systemnetwork object (optional)Network policy, see below
access string (optional)Network access mode, enabled, disabled, or restrictedallowed_domains array<string> (optional)Allowed domains, required and non-empty when access=restricted; host names only, with no scheme, port, or wildcard
files array (optional)Initial files; currently uses file_id to reference source files
type string (required)File reference type, fixed as file_idpath string (required)Absolute path in the environment; must be under /workspace/file_id string (required)Source file ID returned by POST /agents/file
desktop object (optional)Desktop settings; only enabled=false is accepted, and enabled=true returns 400setup_commands array (optional)Setup commands executed in order. Each item requires command and accepts an optional cwd; cwd defaults to /workspaceskills array (optional)Skills; currently uses skill_reference, up to 32 items
type string (required)Skill reference type, fixed as skill_referenceskill_id string (required)Skill resource IDversion string (optional)Skill version; if omitted, latest is resolved and frozen to a specific version
capability_directories array (optional)Capability discovery directories; must be under /workspace/
vault_ids array<string> / null (optional)Vaults to attach, up to 10A non-empty plugins array is rejected. desktop.enabled=true is rejected. skill_id comes from the Skill API. Create or list skills first: Create a Skill or List Skills.Create accepts an optional Idempotency-Key header. The same key and request body in the same workspace return the existing resource; the same key with a different body returns 409.When mounting an unrestricted credential, network.access must be restricted, and allowed_domains must be non-empty and valid.Example: "skills": [{"type": "skill_reference", "skill_id": "skill_xxx", "version": "1.0"}]

Request example

curl -sS -X POST "$BASE_URL/agents/environments" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "OpenAI-Beta: agents=v1" \
  -H "Content-Type: application/json" \
  -d '{
    "environment": {
      "type": "openai_hosted",
      "packages": {"python": ["pandas"]}
    }
  }'

Response fields

id stringEnvironment IDobject stringEnvironment object type, fixed as agent.environmenttype stringEnvironment type, fixed as openai_hostedstatus stringEnvironment status: pending, ready, connected, disconnected, suspended, expired, or failedfiles arraySafe metadata for installed files; file content is not returned.
id stringEnvironment file IDtype stringFile reference type, fixed as file_idpath stringFile path in the environmentsize_bytes integerFile size in bytesfile_id stringOriginal source file ID
skills arraySafe metadata for installed skills; package content is not returned.
type stringSkill reference type, fixed as skill_referencename stringSkill namedescription stringSkill descriptionskill_id stringSkill resource IDversion stringFrozen version
plugins arrayPlugin list; currently [] for managed environments; plugin fields in historical records do not mean plugins can be createdA 201 does not mean the environment is ready. Retrieve the status and confirm ready before use.

Response example

{
  "id": "ccarenv_xxx",
  "object": "agent.environment",
  "type": "openai_hosted",
  "status": "pending",
  "files": [],
  "skills": [],
  "plugins": []
}

Error codes

HTTP statusError type / codeSolution
400invalid_request_error / missing_required_parameter, param=environmentProvide environment in the request body
400invalid_request_error / invalid_request_errorFix type and the configuration as described for environment
404not_found_error / not_found_errorUse a template or environment that exists and is accessible in the current workspace
409conflict_error / conflict_errorUse the same request body with the same idempotency key
503server_error / environment_unavailable or template_storage_unavailableRetry later. If it keeps failing, submit a ticket with x-request-id
The error body has the shape {"error":{"type","code","message","param"}}. Gateway errors can use a different structure. Keep the HTTP status, x-request-id, and a redacted request body for troubleshooting.