Configurar ambiente do agente

Configuração do ambiente em nuvem

Personalize contêineres em nuvem para suas sessões.

Os ambientes definem a configuração do contêiner onde seu agente é executado. Você cria um ambiente uma vez e, em seguida, referencia seu ID cada vez que inicia uma sessão. Múltiplas sessões podem compartilhar o mesmo ambiente, mas cada sessão obtém sua própria instância de contêiner isolada.

Todas as solicitações da API Managed Agents requerem o cabeçalho beta managed-agents-2026-04-01. O SDK define o cabeçalho beta automaticamente.

Criar um ambiente

environment=$(curl -fsS https://api.anthropic.com/v1/environments \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  --data @- <<'EOF'
{
  "name": "python-dev",
  "config": {
    "type": "cloud",
    "networking": {"type": "unrestricted"}
  }
}
EOF
)
environment_id=$(jq -r '.id' <<< "$environment")

echo "Environment ID: $environment_id"

O name deve ser único dentro da sua organização e espaço de trabalho.

Usar o ambiente em uma sessão

Passe o ID do ambiente como uma string ao criar uma sessão.

session=$(curl -fsS https://api.anthropic.com/v1/sessions \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  --data @- <<EOF
{
  "agent": "$agent_id",
  "environment_id": "$environment_id"
}
EOF
)

Opções de configuração

Pacotes

O campo packages pré-instala pacotes no contêiner antes do agente iniciar. Os pacotes são instalados pelos seus respectivos gerenciadores de pacotes e armazenados em cache entre sessões que compartilham o mesmo ambiente. Quando múltiplos gerenciadores de pacotes são especificados, eles são executados em ordem alfabética (apt, cargo, gem, go, npm, pip). Você pode opcionalmente fixar versões específicas; o padrão é a versão mais recente.

environment=$(curl -fsS https://api.anthropic.com/v1/environments \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  --data @- <<'EOF'
{
  "name": "data-analysis",
  "config": {
    "type": "cloud",
    "packages": {
      "pip": ["pandas", "numpy", "scikit-learn"],
      "npm": ["express"]
    },
    "networking": {"type": "unrestricted"}
  }
}
EOF
)

Gerenciadores de pacotes suportados:

Campo	Gerenciador de pacotes	Exemplo
`apt`	Pacotes do sistema (apt-get)	`"ffmpeg"`
`cargo`	Rust (cargo)	`"[email protected]"`
`gem`	Ruby (gem)	`"rails:7.1.0"`
`go`	Módulos Go	`"golang.org/x/tools/cmd/goimports@latest"`
`npm`	Node.js (npm)	`"[email protected]"`
`pip`	Python (pip)	`"pandas==2.2.0"`

Rede

O campo networking controla o acesso à rede de saída do contêiner. Ele não afeta os domínios permitidos das ferramentas web_search ou web_fetch.

Modo	Descrição
`unrestricted`	Acesso total à rede de saída, exceto por uma lista de bloqueio geral de segurança. Este é o padrão.
`limited`	Restringe o acesso à rede do contêiner à lista `allowed_hosts`. O acesso adicional é habilitado via os booleanos `allow_package_managers` e `allow_mcp_servers`.

config=$(cat <<'EOF'
{
  "type": "cloud",
  "networking": {
    "type": "limited",
    "allowed_hosts": ["api.example.com"],
    "allow_mcp_servers": true,
    "allow_package_managers": true
  }
}
EOF
)

Para implantações em produção, use rede limited com uma lista explícita de allowed_hosts. Siga o princípio do menor privilégio concedendo apenas o acesso mínimo de rede que seu agente requer, e audite regularmente seus domínios permitidos.

Ao usar rede limited:

allowed_hosts especifica os domínios que o contêiner pode acessar. Estes devem ter prefixo HTTPS.
allow_mcp_servers permite acesso de saída aos endpoints do servidor MCP configurados no agente, além daqueles listados no array allowed_hosts. O padrão é false.
allow_package_managers permite acesso de saída a registros de pacotes públicos (PyPI, npm, etc.) além daqueles listados no array allowed_hosts. O padrão é false.

Ciclo de vida do ambiente

Os ambientes persistem até serem explicitamente arquivados ou excluídos.
Múltiplas sessões podem referenciar o mesmo ambiente.
Cada sessão obtém sua própria instância de contêiner. As sessões não compartilham o estado do sistema de arquivos.
Os ambientes não são versionados. Se você atualiza seus ambientes com frequência, pode ser interessante registrar essas atualizações do seu lado, para mapear o estado do ambiente com as sessões.

Gerenciar ambientes

# List environments
environments=$(curl -fsS https://api.anthropic.com/v1/environments \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01")

# Retrieve a specific environment
env=$(curl -fsS "https://api.anthropic.com/v1/environments/$environment_id" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01")

# Archive an environment (read-only, existing sessions continue)
curl -fsS -X POST "https://api.anthropic.com/v1/environments/$environment_id/archive" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01"

# Delete an environment (only if no sessions reference it)
curl -fsS -X DELETE "https://api.anthropic.com/v1/environments/$environment_id" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01"

Runtimes pré-instalados

Os contêineres em nuvem incluem runtimes comuns prontos para uso. Consulte a Referência de contêineres para a lista completa de linguagens, bancos de dados e utilitários pré-instalados.

Was this page helpful?

Configurar ambiente do agente

Configuração do ambiente em nuvem

Personalize contêineres em nuvem para suas sessões.

Todas as solicitações da API Managed Agents requerem o cabeçalho beta managed-agents-2026-04-01. O SDK define o cabeçalho beta automaticamente.

Criar um ambiente

environment=$(curl -fsS https://api.anthropic.com/v1/environments \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  --data @- <<'EOF'
{
  "name": "python-dev",
  "config": {
    "type": "cloud",
    "networking": {"type": "unrestricted"}
  }
}
EOF
)
environment_id=$(jq -r '.id' <<< "$environment")

echo "Environment ID: $environment_id"

O name deve ser único dentro da sua organização e espaço de trabalho.

Usar o ambiente em uma sessão

Passe o ID do ambiente como uma string ao criar uma sessão.

session=$(curl -fsS https://api.anthropic.com/v1/sessions \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  --data @- <<EOF
{
  "agent": "$agent_id",
  "environment_id": "$environment_id"
}
EOF
)

Opções de configuração

Pacotes

environment=$(curl -fsS https://api.anthropic.com/v1/environments \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  --data @- <<'EOF'
{
  "name": "data-analysis",
  "config": {
    "type": "cloud",
    "packages": {
      "pip": ["pandas", "numpy", "scikit-learn"],
      "npm": ["express"]
    },
    "networking": {"type": "unrestricted"}
  }
}
EOF
)

Gerenciadores de pacotes suportados:

Campo	Gerenciador de pacotes	Exemplo
`apt`	Pacotes do sistema (apt-get)	`"ffmpeg"`
`cargo`	Rust (cargo)	`"[email protected]"`
`gem`	Ruby (gem)	`"rails:7.1.0"`
`go`	Módulos Go	`"golang.org/x/tools/cmd/goimports@latest"`
`npm`	Node.js (npm)	`"[email protected]"`
`pip`	Python (pip)	`"pandas==2.2.0"`

Rede

O campo networking controla o acesso à rede de saída do contêiner. Ele não afeta os domínios permitidos das ferramentas web_search ou web_fetch.

Modo	Descrição
`unrestricted`	Acesso total à rede de saída, exceto por uma lista de bloqueio geral de segurança. Este é o padrão.
`limited`	Restringe o acesso à rede do contêiner à lista `allowed_hosts`. O acesso adicional é habilitado via os booleanos `allow_package_managers` e `allow_mcp_servers`.

config=$(cat <<'EOF'
{
  "type": "cloud",
  "networking": {
    "type": "limited",
    "allowed_hosts": ["api.example.com"],
    "allow_mcp_servers": true,
    "allow_package_managers": true
  }
}
EOF
)

Ao usar rede limited:

allowed_hosts especifica os domínios que o contêiner pode acessar. Estes devem ter prefixo HTTPS.
allow_mcp_servers permite acesso de saída aos endpoints do servidor MCP configurados no agente, além daqueles listados no array allowed_hosts. O padrão é false.
allow_package_managers permite acesso de saída a registros de pacotes públicos (PyPI, npm, etc.) além daqueles listados no array allowed_hosts. O padrão é false.

Ciclo de vida do ambiente

Os ambientes persistem até serem explicitamente arquivados ou excluídos.
Múltiplas sessões podem referenciar o mesmo ambiente.
Cada sessão obtém sua própria instância de contêiner. As sessões não compartilham o estado do sistema de arquivos.
Os ambientes não são versionados. Se você atualiza seus ambientes com frequência, pode ser interessante registrar essas atualizações do seu lado, para mapear o estado do ambiente com as sessões.

Gerenciar ambientes

# List environments
environments=$(curl -fsS https://api.anthropic.com/v1/environments \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01")

# Retrieve a specific environment
env=$(curl -fsS "https://api.anthropic.com/v1/environments/$environment_id" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01")

# Archive an environment (read-only, existing sessions continue)
curl -fsS -X POST "https://api.anthropic.com/v1/environments/$environment_id/archive" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01"

# Delete an environment (only if no sessions reference it)
curl -fsS -X DELETE "https://api.anthropic.com/v1/environments/$environment_id" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01"

Runtimes pré-instalados

Os contêineres em nuvem incluem runtimes comuns prontos para uso. Consulte a Referência de contêineres para a lista completa de linguagens, bancos de dados e utilitários pré-instalados.

Was this page helpful?