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

Managed Agentsのenvironmentは、agentが実行されるサンドボックスの設定をまとめたリソースです。1つのenvironmentを複数のsessionが参照できますが、sessionごとにまっさらなLinuxコンテナが用意されるため、ファイルシステムの状態は共有されません。

本稿の対象はtype: cloud、つまりAnthropicが管理するクラウドサンドボックスです。自社インフラで動かすself-hostedの構成はself-hostedサンドボックスの記事が扱います。environmentを作って最初のsessionを動かすところまではClaude Managed Agentsクイックスタートにあります。ここでは「何を事前に入れるか」と「外部通信をどこまで開けるか」の判断に絞ります。

前提

Managed AgentsのAPIリクエストにはmanaged-agents-2026-04-01ベータヘッダーが必要です。SDKは自動で付けるので、cURLで直接叩くときだけ意識すれば足ります。

メモリストアのエンドポイントは例外で、agent-memory-2026-07-22ヘッダーを使います。両方のヘッダーを同じメモリストアのリクエストに付けると400エラーです。セッションにメモリストアを取り付ける呼び出しは、従来どおりmanaged-agents-2026-04-01を使います。

environmentを作ってsessionにつなぐ

最小構成は、名前とネットワーク種別だけです。次の例はlimitedにして、パッケージレジストリだけを許可しています。

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",
    "description": "Python検証用。レジストリのみ許可",
    "metadata": {"team": "data-platform"},
    "config": {
      "type": "cloud",
      "networking": {"type": "limited", "allow_package_managers": true}
    }
  }')
 
environment_id=$(jq -r '.id' <<< "$environment")
echo "Environment ID: $environment_id"

nameには用途が分かる名前を付けます。description(最大1,024文字)とmetadata(任意のキーと値)も作成時に渡せるので、チームや用途の記録はそこに残せます。

同じ設定をYAMLに書いてant applyで作る方法もあります。実行するとIDが表示され、claude-lock.jsonに記録されます。このファイルをコミットしておけば、次のant applyは新規作成ではなく既存environmentの更新になります。

name: python-dev
config:
  type: cloud
  networking:
    type: limited
    allow_package_managers: true

ant apply environment.yaml

作成した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": "limited", "allow_package_managers": true}
    }
  }')

指定できるパッケージマネージャーは6種類です。

networkingがlimitedのenvironmentでpackagesを指定するなら、allow_package_managersをtrueにします。忘れると、パッケージ指定が正しくても400エラーでリクエストごと拒否されます。allowed_hostsにレジストリのホストを書いても代わりになりません。

外部通信をどこまで開けるか(networking)

networkingが制御するのは、サンドボックスから外へ出る通信です。web_searchとweb_fetchはAnthropicのサーバー側で動くので、networkingの対象外です。到達できるサイトを絞るなら、agentツールセットのallowed_domains・blocked_domainsを使います。

APIのリクエストではnetworkingを明示します。サンドボックスの仕様ページは、Claude Studio経由で作ったサンドボックスの既定がlimitedだと書いています。環境設定ページは、Claude Consoleの作成フォームがLimitedを選んだ状態で始まり、何も許可されていないと書いています。画面側の名称はページごとに違いますが、どちらもAPIと既定が逆です。

limitedで何も足さなければ、許可されるホストは0件です。それでも、sessionに取り付けたファイル、メモリストア、GitHubリポジトリは使えます。許可されていないホストへポート80か443で出ようとすると、ブロックされたホスト名を載せた403が返ります。

limitedの3つのスイッチ

allow_mcp_serversがfalseのまま、allowed_hostsにないホストのMCPサーバーをagentが宣言していると、session作成が400エラーで失敗します。委譲先のagentが宣言したMCPサーバーも同じです。直すには、そのホストをallowed_hostsに足すか、allow_mcp_serversをtrueにします。

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

allow_package_managersで開くホスト

trueにすると、allowed_hostsとは別に次のホストへ出られます。リストはAnthropicが管理しており、変更されることがあります。

この表でGitHubとGitLab、Bitbucketが開く点には注意が要ります。許可はホスト単位で、操作単位ではありません。許可したホストには、git pushやパッケージの公開のようなアップロードも、コマンドが持つ認証情報つきで送れます。

リポジトリのファイルやWebの内容のような信頼できない入力をagentが読むなら、プロンプトインジェクションで許可先へファイルを持ち出される恐れがあります。対策として、bashツールの権限ポリシーをalways_askかautoにする方法があります。packagesを使わない構成なら、allow_package_managersをfalseのまま必要なホストだけallowed_hostsに並べるほうが開く範囲は狭くなります。

unrestrictedで起きること

unrestrictedでは、bashツールがどのホストにもリクエストを送れます。読むだけでなく、投稿、フォーム送信、APIの呼び出し、外部のデータを書き換えるスクリプトの実行も含まれます。URLを取得するだけのリクエストでも、サイトによってはデータが変わります。

agentツールセットの既定の権限ポリシーはalways_allowなので、これらのbashコマンドは承認なしで走ります。サンドボックスの中にあるファイル、ツール出力、置いた認証情報や秘密情報も外へ出せます。取得したWebページやAPIの応答に埋め込まれた指示が、agentの次の動きを変える可能性もあります。

web_searchとweb_fetchだけを使うagentなら、サイトを列挙できる限りunrestrictedは要りません。web_searchのallowed_domainsに書いたサイトは検索対象になり、allowed_hostsに足したホストはサンドボックスからも開く点に注意してください。2つは別の制御です。

通信が通らないときの症状と原因

• packagesを指定したのに400エラーになる: networking.typeがlimitedなのに、allow_package_managersがtrueではありません。unrestrictedでは不要です。
• allowed_hostsにURLを書いて弾かれる: https://api.example.com/v1のようなスキームやパスは書けません。api.example.comか*.example.comだけを書きます。
• MCPサーバーを設定したagentでsession作成が400になる: limitedでallow_mcp_serversがfalseのままです。allowed_hostsにMCPサーバーのホストを足すか、allow_mcp_serversをtrueにします。
• サンドボックスのコマンドが403を返す: 応答にブロックされたホスト名が載っています。必要なホストだけallowed_hostsへ足します。
• 設定の変更履歴が追えない: environmentにはバージョン番号がありません。metadataやdescription、Git管理のYAMLに、どのsessionがどの構成だったかを自分で残します。

標準で入っているランタイムとpackagesの使い分け

クラウドサンドボックスには、主要な言語ランタイムが最初から入っています。標準で足りるものはpackagesに書かず、足りないものだけを追加すれば、起動前のインストールを小さく保てます。次の表は、よく使う言語の抜粋です。

OSはUbuntu 24.04 LTSで、メモリは最大8GB、ディスクは最大10GBです。データベースやユーティリティ、ブラウザ自動化の内訳はクラウドサンドボックスの仕様リファレンスにあります。

environmentの管理と片付け

environmentは、archiveか削除をするまで残ります。一覧、取得、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は、次の順に止めます。

unrestrictedとlimited、どちらを選ぶか

判断の軸は、通信先を事前に列挙できるかどうかです。

検証段階でも、limitedはallow_package_managersを足すだけで始められます。unrestrictedで始めると、通信先を絞る作業が後回しになりやすい点が難点です。

まとめ

packagesは起動前のセットアップ、networkingは起動後の通信範囲を決めます。最初のsessionはlimitedとallow_package_managers: trueで動かし、サンドボックスのコマンドが403を返したら、応答に載るホスト名をallowed_hostsへ足していく流れで進められます。

agentとenvironmentを組み合わせて最初のsessionを動かす手順はClaude Managed Agentsクイックスタートにあります。agent側の設定項目はManaged Agentsのagent設定を作成・更新するにあります。全体の設計思想はAgent SDKのManaged Agentsの設計思想をどうぞ。