Skip to content
For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
Primary navigation

Suggested
Overview Models Agents Tools Audio & voice Production API reference

Retrieve an agent environment

beta.agents.environments.retrieve(environment_id) -> EnvironmentInfo { id, files, object, 4 more }
GET/agents/environments/{environment_id}

Retrieves an execution environment’s connection status and safe installed metadata. See environment lifecycle.

ParametersExpand Collapse
environment_id: String
minLength0
maxLength1048576
ReturnsExpand Collapse
class EnvironmentInfo { id, files, object, 4 more }

Safe metadata for a first-class execution environment.

id: String

The ID of the environment.

minLength0
files: Array[HostedEnvironmentFile]

Files installed in the environment, without their contents.

object: :"agent.environment"

The object type. Always agent.environment.

plugins: Array[HostedPlugin { description, name, type } ]

Plugins installed in the environment, without their archive contents.

skills: Array[HostedSkill]

Skills installed in the environment, without their archive contents.

status: :pending | :ready | :connected | 4 more

The current environment connection status.

type: :openai_hosted | :self_hosted

Whether the environment is hosted by OpenAI or by the application.

Retrieve an agent environment

require "openai"

openai = OpenAI::Client.new(api_key: "My API Key")

environment_info = openai.beta.agents.environments.retrieve("environment_id")

puts(environment_info)
{
  "id": "id",
  "files": [
    {
      "id": "id",
      "file_id": "file_id",
      "path": "path",
      "size_bytes": 0,
      "type": "file_id"
    }
  ],
  "object": "agent.environment",
  "plugins": [
    {
      "description": "description",
      "name": "name",
      "type": "inline"
    }
  ],
  "skills": [
    {
      "description": "description",
      "name": "name",
      "skill_id": "skill_id",
      "type": "skill_reference",
      "version": "version"
    }
  ],
  "status": "pending",
  "type": "openai_hosted"
}
Returns Examples
{
  "id": "id",
  "files": [
    {
      "id": "id",
      "file_id": "file_id",
      "path": "path",
      "size_bytes": 0,
      "type": "file_id"
    }
  ],
  "object": "agent.environment",
  "plugins": [
    {
      "description": "description",
      "name": "name",
      "type": "inline"
    }
  ],
  "skills": [
    {
      "description": "description",
      "name": "name",
      "skill_id": "skill_id",
      "type": "skill_reference",
      "version": "version"
    }
  ],
  "status": "pending",
  "type": "openai_hosted"
}