Anthropic 平台文档（英文全量）

Environments define the sandbox configuration where your agent runs. You create an environment once, then reference its ID each time you start a session. Multiple sessions can share the same environment, but each session gets its own isolated sandbox (a fresh Linux container).

This page covers type: cloud environments. To run sandboxes on your own infrastructure, see Self-hosted sandboxes.

Managed Agents API requests require the managed-agents-2026-04-01 beta header, except memory store endpoints, which use agent-memory-2026-07-22 instead. The SDK sets the correct beta header automatically. See Beta headers.

Create an environment

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"

```bash CLI
ant apply environment.yaml
```

  ```yaml
  name: python-dev
  config:
    type: cloud
    networking:
      type: unrestricted
  ```

environment = client.beta.environments.create(
    name="python-dev",
    config={
        "type": "cloud",
        "networking": {"type": "unrestricted"},
    },
)

print(f"Environment ID: {environment.id}")

const environment = await client.beta.environments.create({
  name: "python-dev",
  config: {
    type: "cloud",
    networking: { type: "unrestricted" },
  },
});

console.log(`Environment ID: ${environment.id}`);

var environment = await client.Beta.Environments.Create(new()
{
    Name = "python-dev",
    Config = new BetaCloudConfigParams
    {
        Networking = new BetaUnrestrictedNetwork(),
    },
});

Console.WriteLine($"Environment ID: {environment.ID}");

environment, err := client.Beta.Environments.New(ctx, anthropic.BetaEnvironmentNewParams{
	Name: "python-dev",
	Config: anthropic.BetaEnvironmentNewParamsConfigUnion{
		OfCloud: &anthropic.BetaCloudConfigParams{
			Networking: anthropic.BetaCloudConfigParamsNetworkingUnion{
				OfUnrestricted: &anthropic.BetaUnrestrictedNetworkParam{},
			},
		},
	},
})
if err != nil {
	panic(err)
}

fmt.Printf("Environment ID: %s\n", environment.ID)

var environment = client.beta().environments().create(EnvironmentCreateParams.builder()
    .name("python-dev")
    .config(BetaCloudConfigParams.builder()
        .networking(BetaUnrestrictedNetwork.builder().build())
        .build())
    .build());
IO.println("Environment ID: " + environment.id());

$environment = $client->beta->environments->create(
    name: 'python-dev',
    config: ['type' => 'cloud', 'networking' => ['type' => 'unrestricted']],
);
echo "Environment ID: {$environment->id}\n";

environment = client.beta.environments.create(
  name: "python-dev",
  config: {
    type: "cloud",
    networking: {type: "unrestricted"}
  }
)

puts "Environment ID: #{environment.id}"

Use a unique, descriptive name so you can tell environments apart.

Use the environment in a session

Pass the environment ID as a string when creating a session.

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
)

ant beta:sessions create --agent "$AGENT_ID" --environment-id "$ENVIRONMENT_ID"

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
)

const session = await client.beta.sessions.create({
  agent: agent.id,
  environment_id: environment.id,
});

var session = await client.Beta.Sessions.Create(new()
{
    Agent = agent.ID,
    EnvironmentID = environment.ID,
});

session, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{
	Agent: anthropic.BetaSessionNewParamsAgentUnion{
		OfString: anthropic.String(agent.ID),
	},
	EnvironmentID: environment.ID,
})
if err != nil {
	panic(err)
}

var session = client.beta().sessions().create(SessionCreateParams.builder()
    .agent(agent.id())
    .environmentId(environment.id())
    .build());

$session = $client->beta->sessions->create(
    agent: $agent->id,
    environmentID: $environment->id,
);

session = client.beta.sessions.create(
  agent: agent.id,
  environment_id: environment.id
)

Configuration options

Packages

The packages field pre-installs packages into the sandbox before the agent starts. Packages are installed by their respective package managers and cached across sessions that share the same environment. When multiple package managers are specified, they run in alphabetical order (apt, cargo, gem, go, npm, pip). You can optionally pin specific versions. Unpinned packages install the latest version. If the environment uses limited networking, also set networking.allow_package_managers to true; otherwise the request is rejected with a 400 error.

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
)

```bash CLI
ant apply environment.yaml
```

  ```yaml
  name: data-analysis
  config:
    type: cloud
    packages:
      pip:
        - pandas
        - numpy
        - scikit-learn
      npm:
        - express
    networking:
      type: unrestricted
  ```

environment = client.beta.environments.create(
    name="data-analysis",
    config={
        "type": "cloud",
        "packages": {
            "pip": ["pandas", "numpy", "scikit-learn"],
            "npm": ["express"],
        },
        "networking": {"type": "unrestricted"},
    },
)

const environment = await client.beta.environments.create({
  name: "data-analysis",
  config: {
    type: "cloud",
    packages: {
      pip: ["pandas", "numpy", "scikit-learn"],
      npm: ["express"]
    },
    networking: { type: "unrestricted" }
  }
});

using Anthropic.Models.Beta.Environments;

var environment = await client.Beta.Environments.Create(new()
{
    Name = "data-analysis",
    Config = new BetaCloudConfigParams
    {
        Packages = new()
        {
            Pip = ["pandas", "numpy", "scikit-learn"],
            Npm = ["express"],
        },
        Networking = new BetaUnrestrictedNetwork(),
    },
});

environment, err := client.Beta.Environments.New(ctx, anthropic.BetaEnvironmentNewParams{
	Name: "data-analysis",
	Config: anthropic.BetaEnvironmentNewParamsConfigUnion{
		OfCloud: &anthropic.BetaCloudConfigParams{
			Packages: anthropic.BetaPackagesParams{
				Pip: []string{"pandas", "numpy", "scikit-learn"},
				Npm: []string{"express"},
			},
			Networking: anthropic.BetaCloudConfigParamsNetworkingUnion{
				OfUnrestricted: &anthropic.BetaUnrestrictedNetworkParam{},
			},
		},
	},
})
if err != nil {
	panic(err)
}
_ = environment

import com.anthropic.models.beta.environments.*;
import java.util.List;

var environment = client.beta().environments().create(EnvironmentCreateParams.builder()
    .name("data-analysis")
    .config(BetaCloudConfigParams.builder()
        .packages(BetaPackagesParams.builder()
            .pip(List.of("pandas", "numpy", "scikit-learn"))
            .npm(List.of("express"))
            .build())
        .networking(BetaUnrestrictedNetwork.builder().build())
        .build())
    .build());

$environment = $client->beta->environments->create(
    name: 'data-analysis',
    config: [
        'type' => 'cloud',
        'packages' => [
            'pip' => ['pandas', 'numpy', 'scikit-learn'],
            'npm' => ['express'],
        ],
        'networking' => ['type' => 'unrestricted'],
    ],
);

environment = client.beta.environments.create(
  name: "data-analysis",
  config: {
    type: "cloud",
    packages: {
      pip: %w[pandas numpy scikit-learn],
      npm: %w[express]
    },
    networking: {type: "unrestricted"}
  }
)

Supported package managers:

Field	Package manager	Example
apt	System packages (apt-get)	"graphviz"
cargo	Rust (cargo)	"hyperfine@1.18.0"
gem	Ruby (gem)	"rails:7.1.0"
go	Go modules	"golang.org/x/tools/cmd/goimports@latest"
npm	Node.js (npm)	"express@4.18.0"
pip	Python (pip)	"sqlalchemy==2.0.30"

Networking

The networking field controls the sandbox's outbound network access. It does not affect the web_search or web_fetch tools, which run on Anthropic's servers; to restrict the sites those tools can reach, set allowed_domains or blocked_domains on the tool's entry in the agent toolset. See Restrict web search and web fetch domains.

Mode	Description
unrestricted	Full outbound network access, except for a general safety blocklist. This is the default.
limited	Restricts sandbox network access to the hosts in allowed_hosts. Set allow_package_managers and allow_mcp_servers to true to allow additional access.

The following example creates an environment with limited networking:

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" \
  -d '{
    "name": "api-access",
    "config": {
      "type": "cloud",
      "networking": {
        "type": "limited",
        "allowed_hosts": ["api.example.com"],
        "allow_mcp_servers": true,
        "allow_package_managers": true
      }
    }
  }'

```bash CLI
ant apply environment.yaml
```

  ```yaml
  name: api-access
  config:
    type: cloud
    networking:
      type: limited
      allowed_hosts:
        - api.example.com
      allow_mcp_servers: true
      allow_package_managers: true
  ```

environment = client.beta.environments.create(
    name="api-access",
    config={
        "type": "cloud",
        "networking": {
            "type": "limited",
            "allowed_hosts": ["api.example.com"],
            "allow_mcp_servers": True,
            "allow_package_managers": True,
        },
    },
)

const environment = await client.beta.environments.create({
  name: "api-access",
  config: {
    type: "cloud",
    networking: {
      type: "limited",
      allowed_hosts: ["api.example.com"],
      allow_mcp_servers: true,
      allow_package_managers: true
    }
  }
});

using Anthropic.Models.Beta.Environments;

var environment = await client.Beta.Environments.Create(new()
{
    Name = "api-access",
    Config = new BetaCloudConfigParams
    {
        Networking = new BetaLimitedNetworkParams
        {
            AllowedHosts = ["api.example.com"],
            AllowMcpServers = true,
            AllowPackageManagers = true,
        },
    },
});

environment, err := client.Beta.Environments.New(ctx, anthropic.BetaEnvironmentNewParams{
	Name: "api-access",
	Config: anthropic.BetaEnvironmentNewParamsConfigUnion{
		OfCloud: &anthropic.BetaCloudConfigParams{
			Networking: anthropic.BetaCloudConfigParamsNetworkingUnion{
				OfLimited: &anthropic.BetaLimitedNetworkParams{
					AllowedHosts:         []string{"api.example.com"},
					AllowMCPServers:      anthropic.Bool(true),
					AllowPackageManagers: anthropic.Bool(true),
				},
			},
		},
	},
})
if err != nil {
	panic(err)
}
_ = environment

import com.anthropic.models.beta.environments.*;
import java.util.List;

var environment = client.beta().environments().create(EnvironmentCreateParams.builder()
    .name("api-access")
    .config(BetaCloudConfigParams.builder()
        .networking(BetaLimitedNetworkParams.builder()
            .allowedHosts(List.of("api.example.com"))
            .allowMcpServers(true)
            .allowPackageManagers(true)
            .build())
        .build())
    .build());

$environment = $client->beta->environments->create(
    name: 'api-access',
    config: [
        'type' => 'cloud',
        'networking' => [
            'type' => 'limited',
            'allowed_hosts' => ['api.example.com'],
            'allow_mcp_servers' => true,
            'allow_package_managers' => true,
        ],
    ],
);

environment = client.beta.environments.create(
  name: "api-access",
  config: {
    type: "cloud",
    networking: {
      type: "limited",
      allowed_hosts: %w[api.example.com],
      allow_mcp_servers: true,
      allow_package_managers: true
    }
  }
)

For production deployments, use limited networking with an explicit allowed_hosts list. Follow the principle of least privilege by granting only the minimum network access your agent requires, and regularly audit your allowed domains.

When using limited networking:

• allowed_hosts specifies domains the sandbox can reach. Specify bare hostnames or wildcard patterns (such as *.example.com). Do not include a URL scheme, port, or path.
• allow_mcp_servers allows outbound access to MCP server endpoints configured on the agent, beyond those listed in the allowed_hosts array. Defaults to false.
• allow_package_managers allows outbound access to public package registries (such as PyPI and npm) beyond those listed in the allowed_hosts array. Defaults to false. Set it to true whenever the environment specifies packages; otherwise the request is rejected with a 400 error, even if the registry hosts are listed in allowed_hosts.

Environment lifecycle

• Environments persist until explicitly archived or deleted.
• Each session gets its own sandbox instance, even when multiple sessions reference the same environment. Sessions do not share filesystem state.
• Environments are not versioned. If you update an environment frequently, keep your own record of the changes so you can tell which configuration each session used.

Manage environments

# 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"

# List environments
ant beta:environments list

# Retrieve a specific environment
ant beta:environments retrieve --environment-id "$ENVIRONMENT_ID"

# Archive an environment (read-only, existing sessions continue)
ant beta:environments archive --environment-id "$ENVIRONMENT_ID"

# Delete an environment (only if no sessions reference it)
ant beta:environments delete --environment-id "$ENVIRONMENT_ID"

# List environments
environments = client.beta.environments.list()

# Retrieve a specific environment
env = client.beta.environments.retrieve(environment.id)

# Archive an environment (read-only, existing sessions continue)
client.beta.environments.archive(environment.id)

# Delete an environment (only if no sessions reference it)
client.beta.environments.delete(environment.id)

// List environments
const environments = await client.beta.environments.list();

// Retrieve a specific environment
const env = await client.beta.environments.retrieve(environment.id);

// Archive an environment (read-only, existing sessions continue)
await client.beta.environments.archive(environment.id);

// Delete an environment (only if no sessions reference it)
await client.beta.environments.delete(environment.id);

// List environments
var environments = await client.Beta.Environments.List();

// Retrieve a specific environment
var env = await client.Beta.Environments.Retrieve(environment.ID);

// Archive an environment (read-only, existing sessions continue)
await client.Beta.Environments.Archive(environment.ID);

// Delete an environment (only if no sessions reference it)
await client.Beta.Environments.Delete(environment.ID);

// List environments
environments, err := client.Beta.Environments.List(ctx, anthropic.BetaEnvironmentListParams{})
// ...

// Retrieve a specific environment
env, err := client.Beta.Environments.Get(ctx, environment.ID, anthropic.BetaEnvironmentGetParams{})
// ...

// Archive an environment (read-only, existing sessions continue)
_, err = client.Beta.Environments.Archive(ctx, environment.ID, anthropic.BetaEnvironmentArchiveParams{})
// ...

// Delete an environment (only if no sessions reference it)
_, err = client.Beta.Environments.Delete(ctx, environment.ID, anthropic.BetaEnvironmentDeleteParams{})

// List environments
var environments = client.beta().environments().list();
// Retrieve a specific environment
var env = client.beta().environments().retrieve(environment.id());
// Archive an environment (read-only, existing sessions continue)
client.beta().environments().archive(environment.id());
// Delete an environment (only if no sessions reference it)
client.beta().environments().delete(environment.id());

// List environments
$environments = $client->beta->environments->list();
// Retrieve a specific environment
$env = $client->beta->environments->retrieve($environment->id);
// Archive an environment (read-only, existing sessions continue)
$client->beta->environments->archive($environment->id);
// Delete an environment (only if no sessions reference it)
$client->beta->environments->delete($environment->id);

# List environments
environments = client.beta.environments.list

# Retrieve a specific environment
env = client.beta.environments.retrieve(environment.id)

# Archive an environment (read-only, existing sessions continue)
client.beta.environments.archive(environment.id)

# Delete an environment (only if no sessions reference it)
client.beta.environments.delete(environment.id)

Pre-installed runtimes

Cloud sandboxes include common language runtimes, databases, and command-line tools out of the box. See Cloud sandbox reference for the full list.

Next steps

Pre-installed packages, databases, and utilities available in cloud sandboxes.

Create a session to run your agent and start running tasks.