Managed Agentsのクラウド環境(Environment)を構築する — パッケージとネットワーク設定

Managed Agentsのenvironmentは、agentが実行されるサンドボックスの設定をまとめたリソースです。1つのenvironmentを複数のsessionが参照できますが、session側は毎回まっさらなLinuxコンテナを受け取るため、ファイルシステムの状態が共有されることはありません。本稿ではtype: cloudのenvironment、つまりAnthropicが管理するクラウドサンドボックスを対象に、パッケージの事前導入とネットワーク制御の設定方法、そして標準で使えるランタイムの内容を確認します。自社インフラでサンドボックスを動かすself-hostedの構成は対象外です。

パッケージ・ネットワーク設定とランタイム構成

environmentの作成手順そのものはClaude Managed Agentsクイックスタートでも触れていますが、本稿はその先の「サンドボックスに何を入れるか」「外部通信をどこまで許すか」という運用設計に絞って掘り下げます。packagesフィールドによるパッケージ管理、networkingフィールドによる通信制御、環境のライフサイクル、そしてクラウドサンドボックスに最初から入っているランタイム構成の4点が主な内容です。

前提

Managed AgentsのAPIリクエストにはmanaged-agents-2026-04-01ベータヘッダーが必要です(メモリストア関連のエンドポイントのみagent-memory-2026-07-22)。SDKを使う場合は自動付与されるため、cURLで直接叩く場合だけ意識してください。

environmentを作成する

最小構成の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 '{
    "name": "python-dev",
    "config": {"type": "cloud", "networking": {"type": "unrestricted"}}
  }')
 
environment_id=$(jq -r '.id' <<< "$environment")
echo "Environment ID: $environment_id"

nameはenvironment同士を見分けるための識別子なので、用途が分かる名前を付けておくと後で一覧を見たときに迷いません。

同じ設定はcURLの代わりにYAML定義ファイルとant applyコマンドでも作成できます。設定をGit管理下に置きたい場合はこちらが実務的です。

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

ant apply environment.yaml

作成したenvironmentのIDは、sessionを作るときにenvironment_idとして渡します。

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 "{\"agent\": \"$agent_id\", \"environment_id\": \"$environment_id\"}")

パッケージの事前導入(packages)

packagesフィールドを使うと、agentが動き出す前にパッケージをサンドボックスへ導入できます。同じenvironmentを参照する複数のsessionの間でインストール結果がキャッシュされるため、毎回ゼロからインストールし直すよりも起動が速くなります。バージョンを固定しない場合は最新版が入り、複数のパッケージマネージャーを同時に指定した場合はapt→cargo→gem→go→npm→pipのアルファベット順で実行されます。

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 '{
    "name": "data-analysis",
    "config": {
      "type": "cloud",
      "packages": {"pip": ["pandas", "numpy", "scikit-learn"], "npm": ["express"]},
      "networking": {"type": "unrestricted"}
    }
  }')

対応しているパッケージマネージャーは次の6種類です。

networkingがlimited(後述)のenvironmentでpackagesを指定する場合は、networking.allow_package_managersをtrueにする必要があります。これを忘れると、パッケージ指定自体が正しくても400エラーでリクエストごと拒否されます。

外部通信の制御(networking)

networkingフィールドはサンドボックスからの送信方向の通信を制御します。ここで注意したいのは、web_searchやweb_fetchツールはAnthropicのサーバー上で動くためnetworkingの対象外だという点です。これらのツールが到達できるサイトを絞りたい場合は、agentツールセット側のallowed_domains・blocked_domainsで個別に設定します。

本番運用ではlimitedを使い、allowed_hostsを明示的に絞り込む構成が公式の推奨です。許可ドメインは最小権限の原則に沿って定期的に見直します。

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
      }
    }
  }'

limitedネットワークで使う3つのサブフィールドの役割は次のとおりです。

• allowed_hosts: サンドボックスが到達できるドメイン。裸のホスト名かワイルドカードパターン(*.example.com)を指定します。URLスキーム・ポート・パスは含められません。
• allow_mcp_servers: agentに設定したMCPサーバーのエンドポイントへの通信を、allowed_hostsとは別枠で許可します。デフォルトはfalseです。
• allow_package_managers: PyPIやnpmなど公開パッケージレジストリへの通信を、allowed_hostsとは別枠で許可します。デフォルトはfalse。packagesを指定するenvironmentでは、レジストリのホストをallowed_hostsに含めていても、これをtrueにしない限り400エラーになります。

environmentのライフサイクルと管理操作

environmentは明示的にarchiveまたは削除するまで存続し続けます。バージョン管理の仕組みは無いため、頻繁に設定を変える場合はどのsessionがどの構成で動いたかを自分たちの記録として残しておく必要があります。同じenvironmentを参照する複数のsessionでも、サンドボックスのインスタンス自体はsessionごとに独立しています。

環境が増えてくると、どのenvironmentがどの用途で作られたかを忘れがちです。environmentにはagentのようなmetadataフィールドは無いため、用途やチーム名を残したい場合はnameの命名規則を決めておく(例: <チーム名>-<用途>-env)か、ant applyで使うYAML定義ファイル自体をGitで管理して由来を追える形にしておくのが実務的です。一覧・取得・archive・削除は次のように行います。

# 一覧
ant beta:environments list
 
# 個別取得
ant beta:environments retrieve --environment-id "$ENVIRONMENT_ID"
 
# archive(読み取り専用化。既存sessionは継続)
ant beta:environments archive --environment-id "$ENVIRONMENT_ID"
 
# 削除(参照するsessionが無い場合のみ)
ant beta:environments delete --environment-id "$ENVIRONMENT_ID"

削除は、そのenvironmentを参照しているsessionが1つも無い状態でないと実行できません。運用中のenvironmentを片付けたいときは、まずarchiveで新規session作成を止め、既存sessionが終わるのを待ってから削除する流れが安全です。archive状態のenvironmentは新規sessionの作成先には選べませんが、既存sessionの参照自体は削除されるまで有効なままです。

事前導入済みのランタイム(pre-installed runtimes)

クラウドサンドボックスには、主要な言語ランタイムが最初から導入済みです。追加インストールなしにagentがすぐ使える点がpackagesフィールドとの使い分けの基準になります。代表的な言語は次のとおりで、このほかPHP 8.3(composer)、C/C++(GCC 13、Clang)も導入済みです(下表はよく使う言語に絞った抜粋で、全量ではありません)。

OS・データベース・ブラウザ環境の詳細な内訳や、サンドボックスのスペック(メモリ・ディスク・アーキテクチャ)はクラウドサンドボックスの仕様リファレンスにまとめています。ここではpackagesとの使い分けに必要な点だけ触れると、APIから作成したenvironmentはデフォルトでunrestrictedネットワークになる一方、Claude Studio経由でプロビジョニングされたサンドボックスはデフォルトがlimitedになります。APIとUIで挙動が異なるため、意図しない通信制限に気づきにくい点は注意が必要です。

よくあるつまずき

• packagesを指定したのに400エラーになる: networking.typeがlimitedのとき、allow_package_managersをtrueにしていないとパッケージのインストール自体が拒否されます。unrestrictedではこの設定は不要です。
• allowed_hostsにURLを書いてしまう: https://api.example.com/v1のようなスキームやパスを含めると弾かれます。裸のホスト名(api.example.com)かワイルドカード(*.example.com)だけを書きます。
• MCPサーバーに繋がらない: limitedネットワークでagentにMCPサーバーを設定しても、allow_mcp_serversをtrueにしない限り到達できません。allowed_hostsにMCPサーバーのホストを追加しても代用にはなりません。
• web_search/web_fetchの制限をnetworkingで行おうとする: これら2つのツールはAnthropicのサーバー側で実行されるため、networkingの設定は影響しません。制限したい場合はagentツールセット側のallowed_domains/blocked_domainsを使います。
• environmentのバージョン管理を期待する: environmentにはagentのようなversion番号がありません。設定変更の履歴を追いたい場合は、metadataやGit管理下の定義ファイルなど自分たちの仕組みで残す必要があります。

unrestrictedとlimited、どちらを選ぶか

まとめ

Managed Agentsのcloud environmentは、packagesで起動前のセットアップを、networkingで起動後の通信範囲をそれぞれ制御します。検証段階ではunrestrictedで素早く試し、本番に上げる段階でlimitedとallowed_hostsに切り替える、という2段階の運用が公式の推奨に沿った形です。事前導入済みのランタイムを把握しておけば、packagesで追加すべきものと標準で足りるものの切り分けもしやすくなります。agentとenvironmentを組み合わせて最初のsessionを動かす手順はClaude Managed Agentsクイックスタート、agent側の設定項目はManaged Agentsのagent設定を作成・更新するを参照してください。Managed Agents全体の設計思想はAgent SDKのManaged Agentsの設計思想にまとめています。