Environments

An environment is what the agent sees and acts on, one step at a time: look at the screen, reason, act. An agent gets its environments from its environments list, where each entry is either a catalog name or an inline environment object. At least one is required, with at most one per kind. The Browser is the environment H hosts today, and both the browser and the desktop can run on your own machine with local control. Cloud desktops for Mac, Windows, and Linux are in What’s next.

Toolbox

Attaching an environment equips the agent with a toolbox: the actions it can take on that surface, along with built-in guidance on how to use them. The Browser, for example, contributes web actions such as navigate, click, type, scroll, and read. The set of actions is fixed per environment, so you cannot add or remove individual ones. To shape how the agent uses them, set the agent’s instructions or attach your own skills, which load on demand on top of the built-in guidance.

Built-in environments

H ships browsers in the catalog. Browse them below, or list them with GET /api/v2/environments:

Create your own

Most agents define an environment inline in their environments list. Create a catalog environment instead when you want to reuse one across several agents, then reference it by id:

curl -X POST https://agp.eu.hcompany.ai/api/v2/environments \
  -H "Authorization: Bearer $HAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "wide-browser",
    "kind": "web",
    "mode": {"type": "visual", "width": 1920, "height": 1080}
  }'

from hai_agents import Client

client = Client()

client.environments.create_environment(
    id="wide-browser",
    kind="web",
    mode={"type": "visual", "width": 1920, "height": 1080},
)

import { HaiAgentsClient } from "hai-agents";

const client = new HaiAgentsClient();

await client.environments.createEnvironment({
  id: "wide-browser",
  kind: "web",
  mode: { type: "visual", width: 1920, height: 1080 },
});

Endpoints

Method	Path	Description
`POST`	`/api/v2/environments`	Create an environment
`GET`	`/api/v2/environments`	List environments
`GET`	`/api/v2/environments/{id}`	Retrieve an environment
`PUT`	`/api/v2/environments/{id}`	Update an environment
`PATCH`	`/api/v2/environments/{id}`	Patch an environment
`DELETE`	`/api/v2/environments/{id}`	Delete an environment

The list is paginated (page, size) and returns an items / page / total envelope; sort it with sort=created_at, prefixed with - for descending.

Get started

Concepts

Browser

Desktop

Integrations

Guides

Platform

Toolbox

Built-in environments

Create your own

Endpoints

​Toolbox

​Built-in environments

​Create your own

​Endpoints

Toolbox

Built-in environments

Create your own

Endpoints