読み込み中

コード実行とFiles API

レッスン 4610 分
読み込み中

Anthropic APIには、組み合わせることで非常に効果を発揮する2つの強力な機能があります。それがFiles APIとコード実行です。一見別々の機能のように思えるかもしれませんが、これらを組み合わせることで、複雑なタスクをClaudeに委任するための興味深い可能性が開かれます。

Files API

Files APIは、ファイルアップロードを処理するための代替手段を提供します。画像やPDFをメッセージ内に直接base64データとしてエンコードする代わりに、事前にファイルをアップロードしておき、後でそれを参照できます。

サーバーはClaudeに生の画像データと「この画像に何が写っていますか?」というテキストを送信し、Claudeは「背の高い木が見えます」と返答します。

仕組みは次のとおりです。

  • 別のAPI呼び出しを使って、ファイル(画像、PDF、テキストなど)をClaudeにアップロードします
  • 一意のファイルIDを含むファイルメタデータオブジェクトを受け取ります
  • 以降のメッセージでは、生のファイルデータを含める代わりに、そのファイルIDを参照します

サーバーは画像ブロック内のファイルIDと「この画像に何が写っていますか?」を送信し、Claudeは「背の高い木が見えます」と返答します。

このアプローチは、同じファイルを複数回参照したい場合や、毎回のリクエストに含めるには煩雑な大きなファイルを扱う場合に特に便利です。

コード実行ツール

コード実行は、実装を用意する必要のないサーバーベースのツールです。リクエストに定義済みのツールスキーマを含めるだけで、Claudeは任意で分離されたDockerコンテナ内でPythonコードを実行できます。

サーバーはClaudeに円周率を小数第50位まで尋ね、Claudeはコードと結果「3.1415926535」、そしてテキストによる回答を返します。

コード実行環境の主な特徴は次のとおりです。

  • 分離されたDockerコンテナ内で実行される
  • ネットワークアクセスがない(外部API呼び出しができない)
  • Claudeは1回の会話中に複数回コードを実行できる
  • 結果はClaudeによって取得・解釈され、最終的な応答に反映される

Files APIとコード実行の組み合わせ

真の力は、これらの機能を組み合わせて使うことから生まれます。Dockerコンテナにはネットワークアクセスがないため、Files APIが実行環境との間でデータをやり取りする主要な手段となります。

以下に示すワークフロー:コンテナアップロードブロックとテキストを含むユーザーメッセージ、そしてそれに対するClaudeのコード、結果、テキストの返答。

典型的なワークフローは次のとおりです。

  1. Files APIを使ってデータファイル(CSVなど)をアップロードします
  2. メッセージにファイルIDを含むコンテナアップロードブロックを含めます
  3. Claudeにデータの分析を依頼します
  4. Claudeがファイルを処理するためのコードを書いて実行します
  5. Claudeは(プロットなどの)出力を生成し、それをダウンロードできます

実践例

ストリーミングサービスのデータを使った実際の例を見てみましょう。このCSVファイルには、サブスクリプションティア、視聴習慣、解約の有無(サブスクリプションをキャンセルしたかどうか)を含むユーザー情報が含まれています。

streaming.csvファイル。UserID、SubscriptionTier、TotalViewingHoursLastMonthなどの列があり、USER_00001から始まる行が並んでいます。

まず、ヘルパー関数を使ってファイルをアップロードします。

python
file_metadata = upload('streaming.csv')

次に、アップロードしたファイルと分析依頼の両方を含むメッセージを作成します。

python
messages = []
add_user_message(
    messages,
    [
        {
            "type": "text",
            "text": """Run a detailed analysis to determine major drivers of churn.
            Your final output should include at least one detailed plot summarizing your findings."""
        },
        {"type": "container_upload", "file_id": file_metadata.id},
    ],
)

chat(
    messages,
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}]
)

レスポンスを理解する

Claudeがコード実行を使用すると、レスポンスには複数の種類のブロックが含まれます。

  • テキストブロック - Claudeの分析と説明
  • サーバーツール使用ブロック - Claudeが実行を決定した実際のコード
  • コード実行ツール結果ブロック - コード実行からの出力

出力されたレスポンス:解約要因についてのテキストブロック、pandasをインポートするコードを含むサーバーツール使用ブロック、そしてツール結果。

Claudeは1回のレスポンス内で複数回コードを実行し、反復的に分析を積み上げていく場合があります。各実行サイクルには、コードとその結果が含まれます。

生成されたファイルのダウンロード

最も強力な機能の1つは、Claudeが(プロットやレポートなどの)ファイルを生成し、それをダウンロード可能な状態にする機能です。Claudeが可視化を作成すると、それはコンテナ内に保存され、Files APIを使ってダウンロードできます。

レスポンス内で type: "bash_code_execution_output" のブロックを探してください。これらには、生成されたコンテンツのファイルIDが含まれています。

python
download_file("file_id_from_response")

ダウンロードされたマルチパネルの解約分析プロット:500人のユーザー、解約率38.6%、最大の解約要因はカスタマーサービスとのやり取り。

その結果、手作業で大量のコーディングを要したであろう、プロフェッショナルな可視化を伴う包括的な分析が得られます。

データ分析にとどまらない可能性

データ分析は自然な用途ですが、Files APIとコード実行の組み合わせは、それ以外にも多くの可能性を開きます。

  • 画像処理と加工
  • ドキュメントの解析と変換
  • 数学的計算とモデリング
  • カスタムフォーマットによるレポート生成

重要なのは、Files APIを通じて入力と出力をコントロールしながら、複雑で計算量の多いタスクをClaudeに委任できるという点です。これにより、Claudeがコーディングアシスタントとなり、実際にソリューションを実行し反復改善していく強力なワークフローが実現します。