Courses
Software Development with Claude Code
4時間
6.1K
ツール、ファイル、スキル、指示にアクセスできる管理環境の中で、モデルが作業できるような、Claude Code 風のワークフローを Python スクリプトから実行したいと思ったことはありませんか？
Claude Managed Agents は、まさにそのためのワークフロー向けに設計されており、管理された環境でマルチステップのタスクを遂行できるエージェントの構築を支援します。
このチュートリアルでは、Anthropic の最新モデルである Claude Sonnet 5 の使い方を紹介します。高度な推論、コーディング、データ分析タスク向けに設計されており、データの検査、ツールの利用、コードの作成と実行、構造化された出力の生成をエージェントに可能にします。
Managed Agent を作成し、環境を設定し、CSV ファイルをアップロードし、ツールと XLSX スキルへのアクセスをエージェントに与えます。
エージェントはデータを分析し、Python・JSON・Excel ファイルを生成して結果を検証し、完成した成果物をダウンロード可能にします。
Claude がまったく初めての場合は、まず Claude Code 101 コースを確認してください。
Claude Managed Agents とは？
Claude Managed Agents は、Claude を自律型エージェントとして動かすための Anthropic のマネージドフレームワークです。
プロンプトを送信し、ツール呼び出しを実行し、結果を保存し、ランタイムを管理するループを自分で書く代わりに、エージェントを定義してインフラは Anthropic に任せます。
モデルが作業を完了するまでに複数のツールを使う可能性がある、長めのマルチステップタスク向けに設計されています。
Managed Agents は次の4つの主要な要素で構成されています。
- Agent: モデル、システムプロンプト、ツール、MCP サーバー、スキルを含む再利用可能な設定。
- Environment: エージェントが実行される場所。Anthropic のクラウドサンドボックス、または自前のセルフホスト型サンドボックス。
- Session: 特定のタスクを実行するエージェントの稼働インスタンス。
- Events: セッション実行中にやり取りされるメッセージ、ツール呼び出し、結果、ステータス更新。
1. Claude エージェント用ワークスペースの前提条件
このチュートリアルを進めるには、Python 3.12 以降とJupyter Notebookを PC にインストールしてください。Jupyter Notebook を使って、Managed Agent を段階的に作成・実行・確認します。
Anthropic Console のアカウントも必要です。
Console で新しい API キーを作成し、少なくとも$5 分の API クレジットを追加し、キーを安全に保管してください。
Managed Agents は 1 回のセッションで複数回のモデルおよびツール呼び出しを行う可能性があるため、標準の API リクエストよりコストがかかることがあります。
キーはノートブックに直接書いたり GitHub にコミットしたりせず、ANTHROPIC_API_KEY 環境変数として保存してください。
macOS、Linux、WSL の場合は、ターミナルで次を実行します。
export ANTHROPIC_API_KEY="your-api-key-here"Windows PowerShell の場合は次を使用します。
$env:ANTHROPIC_API_KEY="your-api-key-here"2. Anthropic Python SDK をセットアップする
Managed Agent を作成する前に、公式の Anthropic Python SDK をインストールし、このノートブックで必要なモジュールをインポートします。
SDK は Anthropic クライアントを提供しており、これを使ってエージェント、環境、ファイル、セッションを作成します。
%pip install -q --upgrade anthropic次に、環境変数から Anthropic の API キーを読み込みます。
プロジェクトを共有したり GitHub にプッシュしたりする場合、キーをコードに直接置くよりも、ノートブックの外に保持するほうが安全です。
import os
from anthropic import Anthropic
api_key = os.environ.get("ANTHROPIC_API_KEY")
assert api_key, "Set ANTHROPIC_API_KEY in your environment or in a local .env file."Managed Agents は現在 Anthropic のベータ API からアクセスします。managed-agents-2026-04-01 ベータフラグでこの機能が有効になりますが、公式 SDK は Managed Agents のリクエストに必要なベータヘッダーを自動送信します。
本ガイドでは後のセッションファイルの一覧取得とダウンロードで必要になるため、フラグをノートブック内に保持します。
BETA_FLAG = "managed-agents-2026-04-01"
client = Anthropic(api_key=api_key)最後に、このチュートリアル中に作成するあらゆるリソースの ID を保存するための辞書を用意します。
エージェント、環境、アップロードしたファイル、セッションが含まれます。これらの ID を保存しておくと、後続の手順で失敗があっても最後にクリーンアップしやすくなります。
created = {"agent": None, "environment": None, "file": None, "session": None}
print("✓ Anthropic client initialized.")これでクライアントの準備が整いました。
3. Managed Agent を作成する
Managed Agent は、ワークフローのための再利用可能な設定です。
作成時に、Claude モデルを選び、その役割と指示を定義するシステムプロンプトを書き、使用可能なツールとスキルを付与します。
一度作成すれば、毎回設定を作り直すことなく、複数のセッションで同じエージェントを再利用できます。
ここではエージェント名をSonnet 5 Data Analystとし、claude-sonnet-5を使います。
システムプロンプトでは、慎重なデータアナリストのように振る舞うよう指示します。/workspace にマウントされたファイルを確認し、分析にはコード実行を用い、結果は簡潔に数値で報告し、最終成果物は /mnt/session/outputs に保存するように伝えます。
agent = client.beta.agents.create(
name="Sonnet 5 Data Analyst",
model="claude-sonnet-5",
system=(
"You are a meticulous data analyst. When asked about data, always read the "
"file mounted at /workspace, analyse it with the code execution tool, and "
"report concise, numeric results. Use the XLSX skill for spreadsheet work. "
"Save final artifacts to /mnt/session/outputs."
),
tools=[
{"type": "agent_toolset_20260401"},
],
skills=[{"type": "anthropic", "skill_id": "xlsx"}],
)agent_toolset_20260401 はセッション内で Anthropic の組み込みツールへのアクセスを提供し、xlsx スキルは Excel ワークブックの作成と分析に関するタスク固有のガイダンスを提供します。
PowerPoint、Word、PDF のワークフロー向けの事前構築スキルも用意されています。
最後にエージェント ID を保存します。
後でセッション作成時に使用し、チュートリアル完了後のクリーンアップでエージェントをアーカイブする際にも使います。
created["agent"] = agent.id
print(f"✓ Created agent: {agent.id}")次のような出力が表示されるはずです。
✓ Created agent: agent_01EVcgvQsAkLxNnJFp6aynwm4. Anthropic クラウドサンドボックスを構成する
次に、Managed Agent がセッション中に実行される環境を作成します。
環境は安全なサンドボックスとして機能し、エージェントにマウントされたファイルの読み取り、コードの記述、コマンドの実行用の独立したワークスペースを提供します。
ここではネットワーク制限付きの Anthropic のクラウド環境を使用します。後で、アップロードした CSV ファイルを Python で分析する際にこのサンドボックスを用います。
environment = client.beta.environments.create(
name="code-exec-sandbox",
config={"type": "cloud", "networking": {"type": "limited"}},
)
created["environment"] = environment.id
print(f"✓ Created environment: {environment.id}")セルを実行すると、次のような環境 ID が表示されます。
✓ Created environment: env_01FzWACEf9UJDL65ovBPA1zf5. Anthropic Files API でデータをアップロードする
次に、エージェントが分析するデータセットをアップロードします。
Managed Agents は Anthropic の Files API を使ってローカルファイルをアップロードし、セッション環境内にマウントできます。
本ガイドでは、12 行のサンプルデータセット sales_data.csv を使用します。
アップロード前に、ファイルの存在を確認し、想定どおりのデータ行数が含まれていることを確かめます。
from pathlib import Path
csv_path = Path("sales_data.csv")
assert csv_path.exists(), f"Missing input file: {csv_path.resolve()}"
row_count = sum(1 for _ in csv_path.open(encoding="utf-8")) - 1
assert row_count == 12, f"Expected 12 data rows, found {row_count}"その後、ファイルをアップロードし、後のクリーンアップのためにその ID を保存します。
uploaded = client.beta.files.upload(file=csv_path)
created["file"] = uploaded.id
print(f"✓ Uploaded {csv_path}: {uploaded.id} ({row_count} rows)")セルを実行すると、次のような出力が表示されます。
✓ Uploaded sales_data.csv: file_011Cch3EubJkswPdo3gMBvM2 (12 rows)6. エージェント実行セッションを初期化する
ここでセッションを作成します。
セッションは、特定のタスクに必要なエージェント、環境、リソースを結び付けます。ここでは、アップロードした CSV ファイルを /workspace/sales_data.csv にマウントし、エージェントがサンドボックス内からアクセスできるようにします。
session = client.beta.sessions.create(
agent=agent.id,
environment_id=environment.id,
resources=[
{
"type": "file",
"file_id": uploaded.id,
"mount_path": "/workspace/sales_data.csv",
},
],
)
created["session"] = session.id
print(f"✓ Created session: {session.id}")次のようなセッション ID が表示されるはずです。
✓ Created session: sesn_015mNhrKhqqfe7u8VP6GuFdr7. エージェントの応答をストリーミングする
ここから、タスクをセッションに送信し、エージェントの作業状況をストリーミングで確認します。
セッションの作成はエージェントとサンドボックスの準備にすぎません。エージェントは user.message イベントを受け取って初めて作業を開始します。
イベントストリームにより、エージェントのメッセージ、ツール呼び出し、最終的なセッションステータスをリアルタイムで確認できます。
プロンプトでは、マウント済みの CSV ファイルを分析し、Python スクリプトを作成・実行し、JSON サマリーを作成し、Excel レポートを生成するよう指示します。
また、エージェントのテキスト収集、使用ツールの記録、セッションが正常終了したかどうかの確認に使う 3 つの変数を作成します。
agent_text_parts = []
tools_used = []
final_status = None
with client.beta.sessions.events.stream(session.id) as stream:
# Send the user message once the stream is open.
client.beta.sessions.events.send(
session.id,
events=[
{
"type": "user.message",
"content": [
{
"type": "text",
"text": (
"Use the XLSX skill and analyze /workspace/sales_data.csv. "
"Write /mnt/session/outputs/analyze_sales.py, run that Python "
"script, and have it create /mnt/session/outputs/summary.json. "
"Also create /mnt/session/outputs/sales_report.xlsx with the "
"source data, monthly profit, and a summary sheet."
),
}
],
}
],
)
for event in stream:
etype = getattr(event, "type", None)
if etype == "agent.message":
for block in event.content:
txt = getattr(block, "text", None)
if txt:
print(txt, end="")
agent_text_parts.append(txt)
elif etype == "agent.tool_use":
name = getattr(event, "name", "<tool>")
print(f"\n[tool_use] {name}")
tools_used.append(name)
elif etype == "session.status_idle":
final_status = "idle"
print("\n\n✓ Agent finished; session is idle.")
break
elif etype == "session.status_error":
final_status = "error"
print("\n✗ Session reported an error.")
break
print("Tools used:", tools_used)実行中、read、bash、write、edit などのツールイベントが表示されるはずです。
これは、エージェントが利用可能な指示とファイルを確認し、分析スクリプトを書き、サンドボックス内で実行し、見つかった問題を修正していることを示します。
エージェントがこれ以上行う作業がない状態になると、セッションはアイドルになります。この例では、session.status_idle がタスク完了を示すため、ストリームのリスニングを停止します。
Anthropic はサンドボックス内で組み込みツールの実行を管理します。カスタムツールを使用する場合のみ、ツール結果を自前で処理する必要があります。
8. 生成ファイルとイベント履歴を取得する
セッションが完了したら、保存されたイベント履歴を確認し、エージェントが作成したファイルをダウンロードできます。
イベント履歴には、モデルへのリクエスト、ツール呼び出しとその結果、ステータスの変化など、セッションの完全な記録が含まれます。
history = client.beta.sessions.events.list(session.id, order="asc")
print("--- Session event history ---")
for event in history.data:
print(event.type)
print(f"({len(history.data)} events total)")
次に、セッションに紐づくファイルを一覧表示し、ダウンロード可能とマークされたものを取得します。ファイルはローカルの outputs フォルダに保存されます。
import os
os.makedirs("outputs", exist_ok=True)
files = client.beta.files.list(scope_id=session.id, betas=[BETA_FLAG])
downloadable = [f for f in files.data if f.downloadable]
print(f"Found {len(downloadable)} downloadable file(s) for this session.")
downloaded_paths = []
for f in downloadable:
try:
content = client.beta.files.download(f.id, betas=[BETA_FLAG])
local_path = os.path.join("outputs", f.filename)
content.write_to_file(local_path)
downloaded_paths.append(local_path)
print(f" downloaded {f.id} -> {local_path}")
except Exception as exc:
print(f" skip {f.id}: {exc}")最後に、想定した出力がすべて正常にダウンロードされたことを確認します。
expected_outputs = {"analyze_sales.py", "summary.json", "sales_report.xlsx"}
downloaded_names = {os.path.basename(path) for path in downloaded_paths}
assert expected_outputs <= downloaded_names, (
f"Missing expected outputs: {sorted(expected_outputs - downloaded_names)}"
)生成された Python スクリプト、JSON サマリー、Excel レポートは、ローカルの outputs フォルダで利用できます。
9. Python・JSON・Excel の出力を分析する
エージェントがタスクを完了すると、生成ファイルはローカルの outputs/ ディレクトリにダウンロードされます。
これらのファイルは、テキスト応答以上のことをエージェントが行った証拠です。コードを書いて実行し、構造化データを作り、独立してレビューできるスプレッドシートレポートを生成しました。
|
File |
What it contains |
Why it matters |
|
|
エージェントが作成・実行した Python スクリプト。CSV を読み込み、売上、コスト、利益、利益率を計算し、JSON サマリーを書き出し、ワークブックを構築します。 |
エージェントの応答だけに頼らず、分析内容を確認・修正・再実行できます。 |
|
|
合計、平均、ベスト・ワーストの月、月次内訳の完全版を機械可読で格納。 |
ダッシュボード、API、自動チェック、下流アプリケーションに有用です。 |
|
|
元データ、月次利益計算、数式、サマリーシート、チャートを備えた整形済みワークブック。 |
Excel や LibreOffice で開ける、人間が読みやすいレポートを提供します。 |
以下のスクリーンショットは、生成された 3 つの成果物を示しています。
このファイルには、エージェントが作成・実行した分析コードが含まれており、ワークフローを再現可能にし、検証しやすくします。
このファイルは、ダッシュボードや API、その他のプログラムで利用できる構造化形式で結果を保存します。
この Excel ファイルは、売上、コスト、利益、利益率、合計、チャートなどの月次計算を可視化して示します。
sales_data.csv の 12 行に対して、検証済みの結果は次のとおりです。
- 総売上: $32,900
- 総コスト: $14,750
- 総利益: $18,150
- 平均月次利益: $1,512.50
- 最高の月: 12 月（利益 $2,550）
- 最低の月: 1 月（利益 $400）
ワークブックはハードコード値だけに依存せず、数式駆動になっています。
実行中、エージェントは添付の XLSX スキルの指示を読み、ワークブックを作成し、LibreOffice で再計算し、数式を確認し、循環参照の問題を修正してからタスクを完了しました。
10. Managed Agent API リソースをクリーンアップする
Managed Agent のリソースは削除するまで残り続けるため、タスク完了後はクリーンアップが重要です。
特に稼働中のセッションや環境は、放置するとコストが発生し続ける可能性があります。
セッションは削除前にアイドル状態である必要があります。
この最終ステップでは、セッション、アップロードしたファイル、環境を削除し、エージェントをアーカイブします。
各クリーンアップ処理はヘルパー関数でラップし、1 件の削除に失敗しても他のリソースの削除が止まらないようにします。
def safe(label, fn):
try:
fn()
print(f"✓ deleted {label}")
except Exception as exc:
print(f"· could not delete {label}: {exc}")
if created["session"]:
safe("session", lambda: client.beta.sessions.delete(created["session"]))
if created["file"]:
safe("file", lambda: client.beta.files.delete(created["file"]))
if created["environment"]:
safe("environment", lambda: client.beta.environments.delete(created["environment"]))
if created["agent"]:
safe("agent (archived)", lambda: client.beta.agents.archive(created["agent"]))
print("\n🎉 Cleanup complete. The agent is archived; other resources were deleted.")次のような出力が表示されるはずです。
✓ deleted session
✓ deleted file
✓ deleted environment
✓ deleted agent (archived)
🎉 Cleanup complete. The agent is archived; other resources were deleted.ノートブック、サンプル CSV ファイル、セットアップ手順を含む完全なプロジェクトは GitHub で公開しています。
このリポジトリをクローンし、ノートブックを再実行すれば、本ガイドの結果を再現できます。
まとめ
Claude Managed Agents は、セットアップも運用も容易だと感じました。
エージェントを作成し、必要なツール・スキル・サンドボックスを与え、セッションで実行します。
その後はコードの作成、ファイル生成、自己検証、最終結果の返却まで、完全なワークフローを任せられます。
最初は、より柔軟な外部環境が欲しくてModal Sandbox を使おうと試みました。
しかし、本ガイドの範囲には設定が複雑すぎたため、このプロジェクトは Anthropic のマネージドクラウドサンドボックスに焦点を当てることにしました。
個人的な難点はコストでした。12 行だけの小さな CSV ファイルでこの例を 2 回実行したところ、約$0.25 かかりました。
ダッシュボードではモデルの項目に課金が表示されましたが、詳細な内訳は見つけられませんでした。単純な計算とスプレッドシート作成のタスクとしては、低コストのオープンソース代替と比べて高く感じます。
総じて、このプロジェクトは Managed Agent のワークフロー全体を示しています。エージェントの作成、CSV ファイルのアップロード、マネージドサンドボックス内での Python 実行、JSON と Excel レポートの生成、出力の検証、ファイルのダウンロード、そしてリソースのクリーンアップまで。