Claude Managed Agentsクイックスタート — CLIとSDKで最初のセッションを作る

Claude Managed Agentsは、agent(モデル・システムプロンプト・ツールの構成)とenvironment(サンドボックス)を別々のリソースとして作り、その2つを組み合わせてsession(実行インスタンス)を起動する仕組みです。本稿ではant CLIまたはPython/TypeScript SDKを使い、最初のsessionでコードを書かせて応答をストリーミングするところまで進めます。

つまずきやすいのは、ストリームを開く順序、environmentのネットワーク既定値、ストリームの終わり方の3点です。手順の途中で、それぞれ該当する場所で触れます。

3つのリソースの関係

作る順番は、agent、environment、sessionです。agentとenvironmentは一度作れば再利用でき、sessionだけを何度も起動できます。

agentの項目やenvironmentのネットワーク設定の細部は、Managed Agentsのagent設定を作成・更新するとManaged Agentsのクラウド環境を構築するで扱っています。

前提条件とベータヘッダー

用意するのは、Claude Consoleアカウント(platform.claude.com)と、ConsoleのAPIキーのページ(platform.claude.com/settings/keys)で発行したAPIキーの2つです。

Managed AgentsのAPIリクエストには、anthropic-beta: managed-agents-2026-04-01ヘッダーが必要です。SDKを使う場合は自動で付くので、意識するのはcURLで直接叩くときだけです。

メモリストアのエンドポイントだけは、別のヘッダーagent-memory-2026-07-22を使います。両方を同じリクエストに入れると400エラーになるため、managed-agents-2026-04-01を置き換える形で指定します。メモリストアをsessionに接続する操作は、sessionのエンドポイントなのでmanaged-agents-2026-04-01のままです。メモリストアの使い方はManaged Agentsのメモリストアにあります。

ステップ1 — ant CLIをインストールする

ant CLIはHomebrew、リリースバイナリの直接ダウンロード、Go installの3通りで入れられます。macOSならHomebrewが最短です。

brew install anthropics/tap/ant

Linux/WSLでは、GitHubのリリースバイナリを取得します。OSとアーキテクチャを判定してから/usr/local/binに展開する形で、VERSIONには取得したいリリースの番号を入れます。クイックスタートの例は1.37.0です。

VERSION=1.37.0
OS=$(uname -s | tr '[:upper:]' '[:lower:]')
case $(uname -m) in
  x86_64) ARCH=amd64 ;;
  aarch64) ARCH=arm64 ;;
esac
curl -fsSL "https://github.com/anthropics/anthropic-cli/releases/download/v${VERSION}/ant_${VERSION}_${OS}_${ARCH}.tar.gz" \
  | sudo tar -xz -C /usr/local/bin ant

Go 1.25以降が入っている環境では、ソースから入れる方法もあります。バイナリは$(go env GOPATH)/binに置かれるので、PATHに含まれているか確かめます。

go install github.com/anthropics/anthropic-cli/cmd/ant@latest
export PATH="$PATH:$(go env GOPATH)/bin"
ant --version

認証設定とコマンド全体はant CLIの使い方とant CLIの認証設定で扱っています。CI連携やスクリプト化まで進めるなら、そちらも合わせて読むと流れがつながります。

ステップ2 — SDKをインストールする(CLIを使わない場合)

アプリケーションコードから呼び出すなら、言語ごとのSDKを入れます。

pip install anthropic
npm install @anthropic-ai/sdk

そのほかの言語のインストール方法は次のとおりです。

どの方法でも、APIキーは環境変数に設定します。

export ANTHROPIC_API_KEY="your-api-key-here"

ステップ3 — agentを作る

次の例は、Claude Opus 5.5(claude-opus-5-5)を使い、事前構築のツール一式agent_toolset_20260401を持たせたコーディング支援agentです。このツール一式には、bash・read・write・edit・glob・grep・web_fetch・web_searchの8つが入ります。

agent=$(
  curl -sS --fail-with-body https://api.anthropic.com/v1/agents \
    -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": "Coding Assistant",
      "model": "claude-opus-5-5",
      "system": "You are a helpful coding assistant. Write clean, well-documented code.",
      "tools": [{"type": "agent_toolset_20260401"}]
    }'
)
 
AGENT_ID=$(jq -er '.id' <<<"$agent")
AGENT_VERSION=$(jq -er '.version' <<<"$agent")
echo "Agent ID: $AGENT_ID, version: $AGENT_VERSION"

modelはclaude-opus-5のようなモデルID文字列のほか、{"id": "claude-opus-5"}のオブジェクトでも渡せます。オブジェクト形式ではspeed・effort・inference_geoも指定できます。対応するのはClaude 4.5以降のモデルです。

ant CLIなら、設定をMarkdownファイル1枚に書いてant applyで反映します。frontmatterがモデルとツール、本文がシステムプロンプトになります。

---
name: Coding Assistant
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
---
 
You are a helpful coding assistant. Write clean, well-documented code.

ant apply coding-assistant.md

ant applyはagentのIDを表示し、claude-lock.jsonに記録します。claude-lock.jsonをコミットしておくと、次のant applyで2つ目のagentを作らず、同じagentを更新します。cURLのように変数へIDを拾う手間もありません。

ステップ4 — environmentを作る

environmentには、ネットワークの許可範囲を必ず自分で指定します。

Claude Consoleの作成フォームは、Limitedが選ばれ、何も許可されていない状態から始まります。APIとConsoleで既定値が違うので、cURLで作るときは省略せずに書きます。

environment=$(
  curl -sS --fail-with-body 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": "quickstart-env",
      "config": {
        "type": "cloud",
        "networking": {"type": "limited", "allow_package_managers": true}
      }
    }'
)
 
ENVIRONMENT_ID=$(jq -er '.id' <<<"$environment")
echo "Environment ID: $ENVIRONMENT_ID"

ant CLIでは、YAMLで同じ設定を書きます。

name: quickstart-env
config:
  type: cloud
  networking:
    type: limited
    allow_package_managers: true

ant apply environment.yaml

agentとenvironmentは、ant apply coding-assistant.md environment.yamlのようにファイルを2つ渡せば1コマンドで作れます。IDはどちらもclaude-lock.jsonに記録されます。

limitedのときにpackagesでパッケージを事前インストールするなら、allow_package_managersもtrueにします。そうしないと、リクエストは400エラーで拒否されます。自社インフラでサンドボックスを動かす場合は、environmentのtypeが変わります。手順はManaged Agentsのセルフホストサンドボックスにあります。

ステップ5 — sessionを起動する

agentとenvironmentのIDを指定して、sessionを作ります。

session=$(
  curl -sS --fail-with-body 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" \
    -d "{\"agent\": \"$AGENT_ID\", \"environment_id\": \"$ENVIRONMENT_ID\", \"title\": \"Quickstart session\"}"
)
 
SESSION_ID=$(jq -er '.id' <<<"$session")
echo "Session ID: $SESSION_ID"

CLIでは、ant beta:sessions createにIDを渡します。--transform id --raw-outputを付けると、IDだけが標準出力に出ます。

SESSION_ID=$(ant beta:sessions create \
  --agent "$AGENT_ID" \
  --environment-id "$ENVIRONMENT_ID" \
  --title "Quickstart session" \
  --transform id --raw-output)
echo "Session ID: $SESSION_ID"

この作り方だと、sessionはidle(入力待ち)で始まります。最初のメッセージまで含めて1回で起動したいときは、作成リクエストにinitial_eventsを渡します。user.messageとuser.define_outcomeを最大50件まで渡せ、空でない配列を渡すとsessionは最初からrunningで作られます。

ステップ6 — ストリームを開いてからメッセージを送る

イベントのストリームで受け取れるのは、ストリームを開いたあとに発生したイベントだけです。先にメッセージを送ると、最初の応答を取りこぼす競合が起きます。そのため、ストリームを開いてからuser.messageを送ります。

この処理はcURLの一発コマンドでは書きにくく、クイックスタートもcURLとCLIには「SDKの例を使う」と注記しています。Python SDKでは次のようになります。

with client.beta.sessions.events.stream(session.id) as stream:
    client.beta.sessions.events.send(
        session.id,
        events=[{
            "type": "user.message",
            "content": [{"type": "text", "text": "Create a Python script that generates the first 20 Fibonacci numbers and saves them to fibonacci.txt"}],
        }],
    )
    for event in stream:
        match event.type:
            case "agent.message":
                for block in event.content:
                    if block.type == "text":
                        print(block.text, end="")
            case "agent.tool_use":
                print(f"\n[Using tool: {event.name}]")
            case "session.status_idle":
                print("\n\nAgent finished.")
                break

処理するのは3種類のイベントです。agent.messageはモデルの発話、agent.tool_useはツール呼び出し、session.status_idleはsessionが入力待ちに戻ったことを示します。実行すると、agentがwriteでスクリプトを書き、bashで実行し、出力ファイルを検証する様子が流れます。

session.status_idleは「完了」とは限らない

上のコードはsession.status_idleを受けたら「Agent finished.」と出して抜けます。ただしidleは、入力待ちになった合図です。stop_reasonが複数あり、それぞれ意味が違います。

したがって、カスタムツールを持たせたagentやbudgetを付けたsessionでは、idleだけで終了判定すると、まだ続きのある状態でループを抜けます。requires_actionのときは、stop_reason.event_idsにある呼び出しごとにuser.custom_tool_resultを返します。すべて返すと、sessionはrunningに戻ります。クイックスタートのagentはカスタムツールを持たないので、この例ではidleで抜けて問題ありません。

接続が切れたときは、新しいストリームを開き、イベント履歴を一覧で取得して既読のIDを控え、ライブのストリームから既読分を読み飛ばします。ストリーム周りの詳細はManaged Agentsのイベントストリーミングで扱っています。

sessionの裏側で起きる5段階

ユーザーイベントを送ると、Managed Agentsは次の順で動きます。

終わったsessionはterminatedにならず、idleのままです。terminatedになるのは、回復できないエラーが起きたときか、アーカイブされたときです。ほかにrunningと、一時的なエラーを自動で再試行しているreschedulingがあります。

よくあるつまずき

• ベータヘッダーの付け忘れ: cURLではanthropic-beta: managed-agents-2026-04-01が無いとリクエストが通りません。ストリームのURLが404になる原因にもなります。SDKは自動で付けるので、cURLに切り替えたときに初めて気づきがちです。
• メモリストアにヘッダーを混ぜる: メモリストアの呼び出しにmanaged-agents-2026-04-01とagent-memory-2026-07-22を両方付けると400になります。メモリストア側は後者だけにします。
• IDの保存漏れ: sessionの作成にはagentとenvironmentの両方のIDが要ります。ant applyならclaude-lock.jsonに残りますが、cURLでは変数に拾い忘れると次の手順で失敗します。
• ストリームを開く前に送信する: 開く前に送ったメッセージへの応答は、取りこぼすことがあります。必ず先にストリームを開きます。
• networkingの省略: APIでは省略するとunrestrictedになります。意図しない外部通信を許したくないなら、最初からlimitedを書きます。
• 対応モデル: modelはClaude 4.5以降が対象で、それより前のモデルIDは指定できません。

CLIとSDKの使い分け

cURLは依存を増やさずに疎通を確かめるときに便利ですが、ストリーミングには向きません。

まとめ

agent、environment、sessionの順に作り、ストリームを先に開いてからメッセージを送ります。本番に近づけるときは、networkingを明示してlimitedから始め、ストリームの終了判定をstop_reasonまで見る形にしておくと、あとで直す箇所が減ります。

背景の設計はAgent SDKのManaged Agentsの設計思想にまとまっています。