Claude Media
Claude Managed Agentsクイックスタート — CLIとSDKで最初のセッションを作る
AnthropicAgent SDKチュートリアル

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

ant CLIとPython/TypeScript SDKをインストールし、agent・environment・sessionを作って最初の応答をストリーミングするまでの手順です。

読了目安 約25分

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

セットアップからセッション起動までの流れ

Managed Agentsを初めて触る開発者が、手元の端末からClaude Console(platform.claude.com)のAPIキーだけで最初のsessionを立ち上げられる状態になることがゴールです。具体的には、ant CLIのインストール、SDKのセットアップ、agentの作成、environmentの作成、sessionの起動とイベントストリーミングの受信までをカバーします。agentのconfiguration fieldsの詳細や、environmentのネットワーク設定の細部は別記事(Managed Agentsのagent設定を作成・更新する、Managed Agentsのクラウド環境を構築する)に譲ります。

前提条件

作業を始める前に、次の2つを用意します。

  • Claude Consoleアカウント(platform.claude.com)
  • APIキー(ConsoleのSettings → API Keysから発行)

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

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

ant CLIはHomebrew・curlによる直接ダウンロード・Go installの3通りでインストールできます。macOSならHomebrewが最短です。

brew install anthropics/tap/ant

Linux/WSL環境では、リリースバイナリをGitHubから直接取得します。OSとアーキテクチャを自動判定してから/usr/local/binに展開する形です。

VERSION=1.29.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の使い方とant CLIの認証設定にまとめています。Managed Agentsの操作だけを覚えたい場合は本稿の範囲で十分ですが、CI連携やスクリプト化まで踏み込むなら合わせて読む価値があります。

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

CLIではなくアプリケーションコードから直接呼び出したい場合は、言語ごとのSDKを入れます。PythonとTypeScriptが主要な選択肢です。

pip install anthropic
npm install @anthropic-ai/sdk

Java・Go・C#・Ruby・PHP向けの公式SDKも用意されています。パッケージ名はいずれもanthropic系で統一されているので、使っている言語のパッケージマネージャーで検索すればすぐに見つかります。

SDKを使う場合も、APIキーを環境変数として設定しておく必要があります。

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

ステップ3 — agent・environment・sessionを作成する

ここからが本題です。Managed Agentsのリソースは「agent」「environment」「session」の3つに分かれており、それぞれ独立して作成・再利用できます。agentはモデルやツールの構成、environmentはサンドボックスの設定、sessionはその2つを組み合わせた実行インスタンスです。

まずagentを作ります。次の例はClaude Opus 5を使い、事前構築のagentツールセット(ファイル操作・bash実行・Web検索などをまとめたagent_toolset_20260401)を持つコーディング支援agentです。

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

ant CLIを使う場合は、Markdownファイル1枚に設定を書いてant applyで反映します。CLIはレスポンスのagent.idを自動でclaude-lock.jsonに記録するため、cURLのように変数へ手動で拾う必要がありません。

ant apply coding-assistant.md

続いてenvironmentを作ります。Anthropicが管理するクラウドサンドボックスを使うシンプルな構成なら、ネットワークをunrestrictedにした最小構成で十分です。

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": "unrestricted"}}
    }'
)
 
ENVIRONMENT_ID=$(jq -er '.id' <<<"$environment")
echo "Environment ID: $ENVIRONMENT_ID"

自社インフラでサンドボックスを動かす場合は、typeに自己ホスト型の設定を指定します。

最後に、作ったagentとenvironmentを指定して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"

sessionができたら、メッセージを送ってイベントをストリーミングで受け取ります。この処理はcURLの一発コマンドでは表現しにくいため、公式クイックスタートもPython/TypeScript SDKでの実装を案内しています。Python SDKの例では、ストリームを開いた直後にユーザーメッセージを送信し、agent.message(モデルの発話)、agent.tool_use(ツール呼び出し)、session.status_idle(処理完了)の3種類のイベントを順に処理します。

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:
                    print(block.text, end="")
            case "agent.tool_use":
                print(f"\n[Using tool: {event.name}]")
            case "session.status_idle":
                print("\n\nAgent finished.")
                break

このコードを実行すると、agentがサンドボックス内でPythonスクリプトを書き、bashツールで実行し、出力ファイルを検証するまでの様子がリアルタイムで表示されます。

sessionを起動すると裏側で何が起きているか

ユーザーイベントを送信した瞬間、Managed Agentsの内部では次の順で処理が進みます。①environmentの設定に沿ってサンドボックスがプロビジョニングされる ②メッセージの内容に応じてモデルが使うツールを判断する ③ファイル書き込みやbashコマンドなどのツール呼び出しがサンドボックス内で実行される ④結果がイベントとしてリアルタイムにストリーミングされる ⑤やることがなくなった時点でsession.status_idleイベントが発火する。この5段階を意識しておくと、イベントハンドラを書くときにどのイベント種別を待てばよいかが判断しやすくなります。

よくあるつまずき

  • ベータヘッダーの付け忘れ: cURLで直接叩く場合、anthropic-beta: managed-agents-2026-04-01ヘッダーが無いとリクエストが通りません。SDKでは自動付与されるため気づきにくく、cURLに切り替えたときに初めて発覚するケースが多いです。メモリストア系のエンドポイントだけはベータヘッダーが異なる(agent-memory-2026-07-22)ので、混在させないよう注意します。
  • agent.idとenvironment.idを保存し忘れる: sessionの作成には両方のIDが必須です。ant applyを使えばclaude-lock.jsonに自動記録されますが、cURLで進めている場合は変数に拾い忘れると次のステップでエラーになります。
  • ストリーミング処理をcURLで完結させようとする: イベントストリームの送受信は長時間コネクションを前提にした処理で、ワンショットのシェルコマンドには向きません。ここだけはPythonかTypeScriptのSDKに切り替えるのが素直です。
  • モデルの互換性: modelフィールドはClaude 4.5以降のモデルに対応します。それより前のモデルIDは指定できません。

CLIとSDK、どちらを選ぶか

用途向いている手段理由
agent/environment定義をGit管理したい向いている手段ant CLI理由Markdown/YAMLファイル1枚をant applyで反映でき、claude-lock.jsonでID管理も自動化される
アプリケーションに組み込む向いている手段Python/TypeScript SDK理由イベントストリーミングの処理をコード内で完結できる
CIパイプラインで検証だけしたい向いている手段cURL理由依存を増やさずに疎通確認ができる。ただしストリーミングには不向き
対話的に試行錯誤したい向いている手段ant CLI理由サブコマンドで作成・一覧・更新が完結し、SDKのコードを書く手間がない

まとめ

Claude Managed Agentsを初めて触るときは、ant CLIかPython/TypeScript SDKのどちらかをインストールし、APIキーを環境変数に設定したうえで、agent → environment → sessionの順にリソースを作成します。イベントのストリーミング処理だけはSDK側で書く必要がある点を覚えておけば、公式クイックスタートのサンプルコードをそのまま動かせます。agentの設定項目を詳しく作り込みたい場合はManaged Agentsのagent設定を作成・更新するへ、environmentのネットワークやパッケージ設定を詰めたい場合はManaged Agentsのクラウド環境を構築するへ進んでください。Managed Agents全体の設計思想を先に押さえておきたい場合はAgent SDKのManaged Agentsの設計思想が背景の理解に役立ちます。

この記事を共有:XはてブLinkedIn

関連する記事

Anthropic をもっと見る →