読み込み中

最初の Managed Agent を構築する

レッスン 128 分
読み込み中

最初の Managed Agent を構築する

エージェントループを自分の手で構築したことがあるなら、お決まりの手順はご存じでしょう。while ループ、stop reason によるスイッチ、ツールの実行です。それはうまく機能しますし、多くの機能にとっては 実際それが正しい形です。しかし時には、そのループが非常に長時間——数分、場合によっては数時間——にわたって、 多数のツールをまたいで実行され続けることがあります。状態を保持し、ファイルを書き込み、ネットワークの不具合の 後に作業を再開する必要もあります。そうなると、そのループを自分のサーバー上で実行したくはなくなります。 委任したくなるのです。それこそが Managed Agents なのです。

Managed Agent とは?

Managed Agent とは、あなたのインフラではなく Anthropic のインフラ上で実行されるエージェントループです。エージェントを一度記述し、作業を行う環境を与え、セッションを開始します。ループを実行するのは Anthropic であり、あなたはその動作に伴ってイベントをストリーミングで受け取るだけです。

Managed Agents はすべての API アカウントでデフォルトで有効になっており、特別なアクセス権は必要ありません。

4つのプリミティブ

4つのプリミティブがあり、それらには順序があります。

  1. Agent — ペルソナです。モデル、システムプロンプト、ツールセットから構成され、多くの実行にわたって再利用可能です。
  2. Environment — エージェントが実行される場所です。クラウドかセルフホストか、ネットワーク設定などが含まれます。
  3. Session — 特定の Environment 内でのエージェントの単一の実行です。Session が作業の単位になります。
  4. Events — 出入りするメッセージです。エージェントの行動、ツール呼び出し、結果、返信などです。

それぞれの要素がどのように組み合わさるかを説明します。アプリは Session と対話し、Session は Environment 内で作業を進め、起きたことはすべて Event ストリームを通じて戻ってきます。

Agent が Session に接続され、Session が Environment を駆動し、結果が Event ストリームを通じてアプリへ戻る様子を示すアーキテクチャ図

ここでの発想の転換に注目してください。while ループを実行しているのではありません。イベントを送信し、イベントを読み取っているのです。

最小構成の Managed Agent

何か役に立つことをする、最小構成の Managed Agent を構築してみましょう。一時ドライブにファイルを作成し、その行数を数え、結果を報告するというものです。

ツールには agent toolset を使用します。これは Anthropic がバンドルしているファイル、bash、web のツール群です。このタスクにはそれで十分なので、自分でツールを定義する必要はありません。

ステップ1: Agent を作成する

まず Agent を作成します。tools 配列の中に直接 agent toolset が定義されている点に注目してください——これがバンドルされたツールセットです。

python
import anthropic

client = anthropic.Anthropic()

agent = client.beta.agents.create(
    name="Line Counter",
    model="claude-opus-5",
    system="You are a helpful agent that completes small file tasks.",
    tools=[
        {"type": "agent_toolset_20260401", "default_config": {"enabled": True}}
    ],
)

覚えておいてください。Agent は再利用可能です。一度作成すれば、多くの Session にわたって実行できます。

ステップ2: Environment を作成する

次に Environment です。これはエージェントが実行されるサンドボックスを定義します。今回はクラウドで、ネットワークは limited とします。limited では、サンドボックスと web ツールは allowed_hosts に列挙したホストにしかアクセスできません。このタスクはネットワークを必要としないため、何もリストしません。unrestricted は、事前にリストアップできないサイトにエージェントがアクセスしなければならない場合にのみ使用してください。各 Session には独自のサンドボックスが割り当てられ、ファイルはそこに書き込まれます。

python
environment = client.beta.environments.create(
    name="line-counter-env",
    config={
        "type": "cloud",
        "networking": {"type": "limited"},
    },
)

ステップ3: Session を作成する

次に、作成した Agent と Environment を使って、任意のタイトルとともに Session を作成します。Session が作業の単位です。

python
session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    title="Count lines demo",
)

ステップ4: ストリームを開いてから、キックオフを送信する

ここで Event ストリームを開きます——これを最初に行う点に注目してください。ストリームは開いた後に発生したイベントしか配信しないため、必ずキックオフメッセージを送信する前に開いておく必要があります。その後、ユーザーメッセージをライブストリームへ送信します。

python
with client.beta.sessions.events.stream(session_id=session.id) as stream:
    # ストリームが開いている状態 — 次にキックオフを送信
    client.beta.sessions.events.send(
        session_id=session.id,
        events=[
            {
                "type": "user.message",
                "content": [
                    {
                        "type": "text",
                        "text": "Create a file in the temp directory, "
                                "count its lines, and report back.",
                    }
                ],
            }
        ],
    )

events が複数形になっている点に注目してください。この API では、すべてが Events によって流れます。

ステップ5: ストリームを消費する

最後に、ステップ4の with ブロックの内側のまま、ストリームを消費します。このデモで重要になるイベントタイプは3つです。

  • agent.message — Claude のテキスト
  • agent.tool_use — Claude が選択したツール
  • session.status_idle — エージェントが停止し、入力を待っている状態

このデモは最初の idle イベントで停止します。実際のアプリでは、作業が完了したと見なす前に event.stop_reason.type を確認してください。end_turn はエージェントがターンを終えたか、あなたが中断したことを意味し、requires_action はツール呼び出しにあなたからの回答が必要であることを意味します。

python
    for event in stream:
        if event.type == "agent.message":
            for block in event.content:
                if block.type == "text":
                    print(block.text, end="", flush=True)
        elif event.type == "agent.tool_use":
            print(f"\n[tool] {event.name}")
        elif event.type == "session.status_idle":
            print("\n--- Agent done ---")
            break

実行すると、出力はエージェントが声に出して考えている様子になります——実際のテキスト、選択したツール、そして最終的な答えです。そのすべてが、あなたのではなく Anthropic のコンテナ内で実行されています。

Managed Agent 実行のターミナル出力: agent、environment、session の ID が作成された後、Event ストリームでエージェントがファイルを書き込み、ツールを実行し、ファイルに3行含まれていると報告する様子が示されている

トレードオフ

通常、エージェントを扱う際には、すべてを自分で制御しなければならない独自のループを持つことになります。Managed Agents では、そのループ、サンドボックス、そして再開可能性を委任し、入ってくる Event ストリームを消費するだけで済みます。Session の Event 履歴はサーバー側に保存されます。そのため、接続が切れた場合は新しいストリームを開き、過去の Events を一覧表示して見逃したものを確認し、一覧にすでに含まれているライブイベントはスキップしてください。コードについてはイベントを見逃さずに再接続するを参照してください。

本番環境のアプリでは、これが長時間実行され、ファイルを扱う「これを整理しておいて」というようなタスクの形になります。ファイル共有のクリーンアップを想像してください。Managed Agent が対象のディレクトリ構造の仕様を読み取り、散らかった受信フォルダを巡回し、ファイルを適切なプロジェクトフォルダへ移動させ、重複ファイルやゼロバイトのゴミをアーカイブし、自信を持って配置できないものにはフラグを立てます——これらすべてが、数千件のファイルに対して数分間実行され得る1つの Session の中で行われます。実際のアプリでこれがどのように見えるかをご紹介します——ファイル共有のクリーンアップダッシュボードが、エージェントがファイルを仕分け、アーカイブし、フラグを立てる様子をライブでストリーミング表示します。

Managed Agent を利用したファイル共有クリーンアップの Web アプリ。整理されていくフォルダツリーと、ファイルを移動・アーカイブするエージェントの Events のライブアクティビティフィードが並んで表示されている

まとめ

  • Managed Agents はエージェントループをあなたの代わりに実行します ——あなたのサーバーではなく Anthropic のインフラ上で。
  • 流れは次のとおりです。Agent を作成し、Environment を作成し、Session を作成し、Events を送信し、Events をストリーミングで受け取る。
  • Agent(モデル、システムプロンプト、ツールセット)は実行間で再利用可能です。Session は単一の実行です。Events はすべてがどのように流れるかを表します。
  • キックオフメッセージを送信する前に Event ストリームを開いてください——ストリームは開いた後に発生した Events しか配信しません。
  • 3つの Events に注目してください。agent.message(テキスト)、agent.tool_use(ツールの選択)、そして session.status_idle(停止して入力を待っている状態で、理由は stop_reason.type に示されます)。
  • ループが長時間実行されすぎる、処理が多すぎる、あるいは不具合を乗り越える必要がある場合は Managed Agents を選んでください。完全な制御が必要な場合は、手動のループを選んでください。