WaveSpeedAI
← ブログ

Claude Managed Agentsクイックスタートガイド2026

Claude Managed Agentsのステップバイステップガイド：ベータヘッダーのセットアップ、初回セッション、ツール呼び出し、ストリーミングイベント — 主要なコードパターンとコストチェックポイントを含む。

By Dora 2 min read
Claude Managed Agentsクイックスタートガイド2026

Managed Agentsセッションを初めて実行しようとしたとき、最初のcurlで400エラーが発生した。エージェントの作成でも、環境でもなく、ストリームエンドポイントで。createリクエストのヘッダー anthropic-beta: managed-agents-2026-04-01 をコピペしたのに、ストリーミングAPIに拒否された。当時のドキュメントでは、ストリーミングエンドポイントに別のベータヘッダーが記載されていたのだ。四十分を無駄にした。

今日初めてManaged Agentsセッションをエンドツーエンドで動かそうとしているなら、これが私が実際に歩んだ道だ。こんにちは、Doraです！障害の半分はここにあるので、まずベータヘッダーから。それからエージェント、環境、セッション、ストリームの順に。そして最後にコストチェックポイント。デバッグ中もセッションのランタイムは課金され続けるから。

始める前に

Managed Agentsへのアクセス権を持つAnthropicのAPIキーが必要だ。現在ウェイトリストはない — 既存のキーはパブリックベータで動作する。

ベータヘッダーは必須だ。 Managed Agentsのすべてのエンドポイントに anthropic-beta: managed-agents-2026-04-01 が必要だ。AnthropicのManaged Agentsの概要によれば、SDKはこれを自動的に設定する。生のcurlを使う場合は、すべてのリクエストに自分で追加する。これがコミュニティレポートで見かける400エラーの最も一般的な原因だ。

公式SDK（Pythonなら anthropic、TypeScriptなら @anthropic-ai/sdk）を使う場合は、ベータエージェントサポートを含むバージョンを使っているか確認しよう。古いバージョンには client.beta.agents や client.beta.sessions がない。

モデルの選択もここでは重要だ。 Opus 4.7は長期間のエージェント推論に優れている。Sonnet 4.6はトークンあたりのコストと速度で有利だ。クイックスタートの実行にはSonnet 4.6で十分。実際のワークロードがデバッグ、計画、または長いツールチェーンなら、Opus 4.7はその価格に見合う。

ステップ1 — エージェントを定義する

Managed Agentsにおけるエージェントは、プロセスではなく設定オブジェクトだ。名前、モデル、システムプロンプト、ツールアクセスを一度定義すれば、セッションをまたいで再利用できる。

公式クイックスタートから最小限の定義：

python

agent = client.beta.agents.create(
    name="Coding Assistant",
    model="claude-opus-4-7",
    system="You are a helpful coding agent.",
    tools=[{"type": "agent_toolset_20260401"}],
)

agent_toolset_20260401 のツールタイプは、bash、ファイル読み書き、ウェブ検索、ウェブフェッチ、コード実行など、フルの組み込みツールセットを解放する。後でスコープを絞ることもできる。最初の実行では広いままにして、エージェントが実際に何を使うか確認しよう。

agent.id を保存しておくこと。すべてのセッションがこれを参照する。

ステップ2 — 環境を作成する

環境はサンドボックス化されたコンテナを定義する。最初の実行の多くはこれで:

python

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

env.id を保存しておくこと。エージェントが自分のファイルシステムにしか触れない場合、"networking": {"type": "limited"} の方が安全で、SREインシデント対応クックブックにも詳しく記載されている。

ステップ3 — セッションを開始する

セッションはエージェントを環境に紐付ける。セッションを作成しても作業は開始されない。 プロビジョニングされるだけだ。ユーザーイベントを送信したときに作業が始まる。

python

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=env.id,
    title="Quickstart session",
)

このパターン — 作成してからイベントで駆動する — は、セッションリファレンスのステートマシンモデルが意味をなす部分だ。セッションは持続する。後でさらにイベントを送ることができる。ファイルシステムはターンをまたいで生き残る。

ステップ4 — イベントをストリームする

ストリームを開いて、ユーザーメッセージを送り、session.status_idle まで イベントを読む:

python

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": "Generate first 20 Fibonacci numbers, save to fib.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[tool: {event.name}]")
            case "session.status_idle":
                break

イベント名は {ドメイン}.{アクション} の形式に従う。完全なスキーマはイベントとストリーミングのドキュメントにある。processed_at フィールドが重要：null の場合、イベントはキューに入っているが、まだ実行されていない。最初の実行でこれを見逃して、ツールがサイレントに失敗していると思ってしまった。

コストチェックポイント

Managed Agentsは2つのことに課金される：標準トークンレートと、アクティブランタイムのセッション時間あたり$0.08。公式料金ページによれば、ランタイムはミリ秒単位で発生するが、ステータスが running の間のみだ。アイドル時間と終了したセッションは課金されない。

実際に何を意味するか：

  • デバッグ中に閉じ忘れたセッション：まだ課金が発生している（実行中なら）。
  • ウェブ検索：1,000コールあたり$10、別途課金。リサーチエージェントはこれにすぐに到達する。
  • 一日の作業を終える前にConsoleのトレーシングでアクティブセッションを確認しよう。現在のUIパスは自分で確認すること — Consoleのレイアウトは変化し続けている。

よくあるエラー

ベータヘッダーが欠けているか間違っている。 400エラー、しばしばサポートされていないエンドポイントに関するメッセージを伴う。修正：直接のHTTP呼び出しすべてに managed-agents-2026-04-01 があることを確認する。SDKを使っていてもこれが発生する場合は、SDKをアップグレードする。

レート制限。 作成エンドポイントは60rpm上限、読み取りエンドポイントは600rpm上限。組織のティア制限はその上にさらに適用される。429はジッターを加えてバックオフすることを意味し、即座にリトライしてはいけない。

サイレントツールループ。 エージェントがツールを呼び続けるが、最終的なメッセージが出ない。セッショントレースを確認する — 通常、requires_action が処理されず、レスポンスが返送されていないケースだ。

FAQ

Q1: Managed Agentsでマルチエージェント連携を有効にするにはどうすればよいか？

マルチエージェント（メモリとアウトカムとともに）は、まだリサーチプレビュー機能だ。Claude Consoleから別途アクセスをリクエストする必要がある。オーケストレーターが呼び出し可能なエージェントに委任する連携パターンはマルチエージェントセッションに記載されているが、組織でプレビューフラグが有効にならないと使えない。

Q2: セッション中にエージェントが呼んだツールを確認できるか？

できる。プログラム的なアクセスには client.beta.sessions.events.list(session.id) を使い、イベントごとのトークンとタイムスタンプを時系列で確認するにはConsoleのトレーシングビューを使う。

Q3: Managed Agentsの公式クックブックはどこにあるか？

チュートリアルはClaude Cookbookサイトにある — iterate-fix-failing-testsノートブックが最初に読むのに最適だ。operate-in-production ノートブックはhello-worldを超えたら、vault、MCP、webhookをカバーしている。

Q4: セッションランタイムコストをかけずにテストする方法はあるか？

Managed Agents専用の無料ティアは存在しない。標準APIの無料クレジットは適用される。開発中はセッションを短く保ち、作業を止めたら閉じること。アイドルセッションは課金されないが、実行中のセッションは課金される — そして「実行中」にはサイレントにループしているエージェントも含まれる。

Q5: 長時間実行のManaged Agentsタスクに最適なモデルは何か？

「長時間実行」が何を意味するかによる。重いツール使用を伴う数時間の推論ならOpus 4.7。高ボリュームでシンプルなループならプロンプトキャッシングを使ったSonnet 4.6がコストを大幅に削減する。Opus 4.7の2時間以上のセッションはまだテスト中だ。そこで私のデータは終わっている。続報を待ってほしい。

2時間を超えたときのコンパクションの動作はまだ検証中だ。自分で実行してみること — それが私より多くを教えてくれるだろう。

前回の記事：

共有