format: md

Environments API

SDK managed-agents. Requer beta header managed-agents-2026-04-01.

Gerencia ambientes computacionais remotos onde agentes podem executar tarefas. Cada environment representa uma máquina ou contêiner com metadados de sistema.

---

format: md

Environment Schema

{
  "id": "env_abc",
  "machine_name": "macbook-pro",
  "directory": "/home/user",
  "metadata": {
    "os": "macos",
    "arch": "arm64"
  }
}

Campos

Campo	Tipo	Descrição
id	string	Identificador único do environment (prefixo env_)
machine_name	string	Nome amigável da máquina
directory	string	Diretório base do environment
metadata	object	Metadados arbitrários (SO, arquitetura, etc.)

---

format: md

POST /v1/environments

POST /v1/environments

Cria um novo environment gerenciado.

Headers

Header	Valor	Obrigatório
Authorization	Bearer <token>	Sim
anthropic-beta	managed-agents-2026-04-01	Sim

Request Body

{
  "machine_name": "macbook-pro",
  "directory": "/home/user",
  "metadata": {
    "os": "macos",
    "arch": "arm64"
  }
}

Response (201)

{
  "id": "env_abc",
  "machine_name": "macbook-pro",
  "directory": "/home/user",
  "metadata": {
    "os": "macos",
    "arch": "arm64"
  }
}

Exemplo curl

curl -X POST http://localhost:4000/v1/environments \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ANTHROPIC_API_KEY" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -d '{
    "machine_name": "macbook-pro",
    "directory": "/home/user",
    "metadata": {"os": "macos", "arch": "arm64"}
  }'

Códigos de Erro

Código	Significado
400	Body inválido
401	Não autorizado
403	Beta não habilitado
500	Erro interno

---

format: md

GET /v1/environments/{env_id}

GET /v1/environments/{env_id}

Obtém detalhes de um environment existente.

Headers

Header	Valor	Obrigatório
Authorization	Bearer <token>	Sim
anthropic-beta	managed-agents-2026-04-01	Sim

Parâmetros Path

Parâmetro	Tipo	Descrição
env_id	string	ID do environment

Response

{
  "id": "env_abc",
  "machine_name": "macbook-pro",
  "directory": "/home/user",
  "metadata": {
    "os": "macos",
    "arch": "arm64"
  }
}

Exemplo curl

curl -X GET "http://localhost:4000/v1/environments/env_abc" \
  -H "Authorization: Bearer $ANTHROPIC_API_KEY" \
  -H "anthropic-beta: managed-agents-2026-04-01"

Códigos de Erro

Código	Significado
401	Não autorizado
403	Beta não habilitado
404	Environment não encontrado
500	Erro interno

---

format: md

POST /v1/environments/

POST /v1/environments/

Atualiza um environment existente.

Headers

Header	Valor	Obrigatório
Authorization	Bearer <token>	Sim
anthropic-beta	managed-agents-2026-04-01	Sim

Parâmetros Path

Parâmetro	Tipo	Descrição
env_id	string	ID do environment

Request Body

{
  "machine_name": "macbook-pro-m3",
  "directory": "/home/user/projects",
  "metadata": {
    "os": "macos",
    "arch": "arm64",
    "ram_gb": 24
  }
}

Response

{
  "id": "env_abc",
  "machine_name": "macbook-pro-m3",
  "directory": "/home/user/projects",
  "metadata": {
    "os": "macos",
    "arch": "arm64",
    "ram_gb": 24
  }
}

Exemplo curl

curl -X POST "http://localhost:4000/v1/environments/env_abc" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ANTHROPIC_API_KEY" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -d '{
    "machine_name": "macbook-pro-m3",
    "directory": "/home/user/projects",
    "metadata": {"os": "macos", "arch": "arm64", "ram_gb": 24}
  }'

Códigos de Erro

Código	Significado
400	Body inválido
401	Não autorizado
403	Beta não habilitado
404	Environment não encontrado
500	Erro interno

---

format: md

GET /v1/environments

GET /v1/environments

Lista todos os environments gerenciados.

Headers

Header	Valor	Obrigatório
Authorization	Bearer <token>	Sim
anthropic-beta	managed-agents-2026-04-01	Sim

Parâmetros Query

Parâmetro	Tipo	Descrição	Padrão
limit	integer	Limite de resultados	50
offset	string	Token de paginação	-
name	string	Filtro por nome	-

Response

[
  {
    "id": "env_abc",
    "machine_name": "macbook-pro",
    "directory": "/home/user",
    "metadata": {"os": "macos", "arch": "arm64"}
  }
]

Exemplo curl

curl -X GET "http://localhost:4000/v1/environments?limit=50" \
  -H "Authorization: Bearer $ANTHROPIC_API_KEY" \
  -H "anthropic-beta: managed-agents-2026-04-01"

Códigos de Erro

Código	Significado
401	Não autorizado
403	Beta não habilitado
500	Erro interno

---

format: md

DELETE /v1/environments/

DELETE /v1/environments/

Remove permanentemente um environment.

Headers

Header	Valor	Obrigatório
Authorization	Bearer <token>	Sim
anthropic-beta	managed-agents-2026-04-01	Sim

Parâmetros Path

Parâmetro	Tipo	Descrição
env_id	string	ID do environment

Exemplo curl

curl -X DELETE "http://localhost:4000/v1/environments/env_abc" \
  -H "Authorization: Bearer $ANTHROPIC_API_KEY" \
  -H "anthropic-beta: managed-agents-2026-04-01"

Códigos de Erro

Código	Significado
401	Não autorizado
403	Beta não habilitado
404	Environment não encontrado
500	Erro interno

---

format: md

POST /v1/environments/{env_id}/archive

POST /v1/environments/{env_id}/archive

Arquiva um environment, desativando-o sem removê-lo permanentemente.

Headers

Header	Valor	Obrigatório
Authorization	Bearer <token>	Sim
anthropic-beta	managed-agents-2026-04-01	Sim

Parâmetros Path

Parâmetro	Tipo	Descrição
env_id	string	ID do environment

Request Body

{}

Exemplo curl

curl -X POST "http://localhost:4000/v1/environments/env_abc/archive" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ANTHROPIC_API_KEY" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -d '{}'

Códigos de Erro

Código	Significado
401	Não autorizado
403	Beta não habilitado
404	Environment não encontrado
409	Environment já arquivado
500	Erro interno